Analytics pt BR

Analytics e Google Tag Manager

🌐 Esta página em: English · Português

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:

1. O snippet oficial do contêiner: os mesmos bytes que o Google documenta, parametrizados só onde o próprio GTM os parametriza.
2. 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.
3. 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.