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)

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

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.

•

Helpers de Consent Mode. Consentimento é decisão de produto com peso legal; a v1 não o embrulha. Um banner de consentimento feito com o SDK pode empurrar as atualizações como eventos comuns de dataLayer via Track enquanto isso.

•

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