Analytics no eQuantic.UI é uma capacidade, não um script colado: a página pede IAnalytics como pede uma câmera, e nunca fica sabendo quem está ouvindo. O pacote eQuantic.UI.Gtm é um INSTALADOR: uma chamada liga um contêiner do Google Tag Manager a essa capacidade, de ponta a ponta.

Desde 0.2.0-preview.29

Instalar

using eQuantic.UI.Gtm;

builder.Services.AddUI(options => options

.ScanAssembly(typeof(Program).Assembly)

.UseGtm("GTM-XXXXXXX"));

Essa chamada instala três coisas no shell HTML:

O snippet oficial do contêiner: os mesmos bytes que o Google documenta, parametrizados só onde o próprio GTM os parametriza.

A declaração do instalador (window.__EQ_ANALYTICS__): o que arma a realização de IAnalytics do runtime. Sem instalador, rastrear é um no-op silencioso, de propósito.

Page views de SPA: o router do cliente anuncia toda navegação consumada (eq:navigate), e o shell transforma isso em pushes de page_view com page_path e page_title, os nomes de campo do próprio GA4. O contêiner vê o load inicial sozinho; estas são as navegações que ele não consegue ver.

O id do contêiner é validado na inicialização: um id com erro de digitação instala um contêiner que coleta nada em silêncio, e isso se descobre no relatório vazio do mês seguinte... recusar cedo é a falha mais gentil.

Rastrear de uma página

public override VisualNode Build(ComponentContext context)

{

_analytics = context.GetService<IAnalytics>();

// …

}

private async Task Submit()

{

// …depois que o servidor disse sim:

_analytics?.Track("sign_up");

_analytics?.Track("purchase", new Dictionary<string, object?>

{

["value"] = 42,

["currency"] = "EUR",

});

}

Track é dispara-e-esquece por contrato: analytics nunca pode fazer uma página esperar. Os nomes de evento são o SEU vocabulário (sign_up, begin_checkout); o framework nunca inventa nem prefixa nenhum. No servidor a mesma chamada é no-op: SSR não é um usuário, e uma página que rastreasse durante a renderização contaria os próprios crawlers.

Um contêiner por app, de propósito

Um contêiner GTM carrega no DOCUMENTO e nunca descarrega, e num SPA "contêiner por página" não tem como existir. Variação por rota é para o que os triggers do próprio contêiner servem: o page_view automático carrega page_path exatamente para o marketing disparar tags por rota sem o app mudar... que é o ponto inteiro de um tag manager.

O que existe é o caso agência-mais-cliente: chame UseGtm uma vez por contêiner. A segunda chamada adiciona só o snippet dela; os dois andam no mesmo dataLayer (a regra multi-contêiner do próprio GTM, imposta na inicialização).

Opções

.UseGtm("GTM-XXXXXXX", gtm => gtm

.WithDataLayerName("eqData") // quando outro script já é dono de `dataLayer`

.WithoutSpaPageViews() // o contêiner usa o trigger de histórico do GA4

.WithEnvironment("auth…", "env-9") // ambientes GTM (gtm_auth / gtm_preview)

.WithConsent()) // carrega o contêiner só depois do consentimento

Use WithoutSpaPageViews() quando o contêiner rastreia mudanças de histórico sozinho, senão a mesma navegação conta duas vezes.

Consentimento (GDPR / LGPD)

ESTADO: CONSTRUÍDO; SAI NA PRÓXIMA RELEASE DEPOIS DA 0.2.0-PREVIEW.45

As duas regulações dizem a mesma coisa sobre cookies de analytics: nada é gravado até o visitante dizer sim, e um "não" é lembrado. Três peças tornam isso verdade sem o app escrever uma linha de JavaScript:

•

IConsent — uma capacidade como qualquer outra (context.GetService<IConsent>()): State é Unknown, Granted ou Denied; Grant() / Deny() guardam a resposta. Na web vive num ÚNICO cookie, eq-consent, por um ano, e uma mudança é anunciada no documento como eq:consent. No servidor o mesmo cookie é LIDO do request, então a primeira pintura de quem já respondeu não tem banner nenhum — o SSR sabe a resposta que o navegador guarda.

•

CookieConsent(policyHref) — o cartão que pergunta. Desenhado só enquanto a resposta é desconhecida, some no momento em que ela é dada; dois botões (aceitar / recusar) e o link da política de privacidade, tudo localizado (EN, pt-BR, es) e cada peça substituível. É um cartão, não uma camada: coloque onde o shell quiser (um Sticky no fim da página é o lugar usual).

•

UseGtm(id, gtm => gtm.WithConsent()) — o instalador condiciona o contêiner à resposta. O head declara os padrões do Google Consent Mode como denied, e o script do contêiner só é baixado quando o cookie diz granted, ou no instante em que o eq:consent disser. Quem recusa ou nunca responde não baixa tag manager nenhum. Chamadas Track() feitas nesse meio-tempo ficam no array do dataLayer, que o contêiner reproduz se o consentimento chegar depois.

builder.Services.AddUI(o => o.ScanAssembly(typeof(Program).Assembly)

.UseGtm("GTM-XXXXXXX", gtm => gtm.WithConsent()));

// em algum lugar que toda página renderiza, no fim do shell:

Sticky(CookieConsent("/privacy"))

Desligado por padrão: um instalador que já rodava sem perguntar continua rodando. Ligar é decisão do app, junto com o cartão e uma página de política atrás do link — um cartão de consentimento sem política atrás é uma promessa que o site não consegue cumprir.

O que está ausente de propósito

•

O iframe <noscript> das instruções do Google. Ele mede usuários cujo browser não roda JavaScript, e esse usuário aqui não recebe app nenhum: não há nada para medir.

•

Realização nativa. IAnalytics resolve para no-op numa janela Photon hoje; os bridges de analytics móveis entram com a trilha nativa.

Relacionados

•

Integração com o servidor: AddUI, o shell, e onde o UseGtm se pendura.

•

Capacidades: o padrão pedir-por-interface que IAnalytics segue.

PREVIOUSRoadmap

NEXTArchitecture-pt-BR

ON THIS PAGE