Como uma camada de dados alimenta suas tags de analytics com eventos

O que é uma camada de dados?

Em web analytics, uma camada de dados é um objeto JavaScript na página em que o seu site grava eventos e os valores deles, para que as tags de analytics e de marketing leiam dados limpos e nomeados em vez de raspá-los do HTML. A documentação do Tag Manager do Google resume assim: "The data layer is an object used by Google Tag Manager and gtag.js to pass information to tags."

O objetivo da camada é a separação. O código da sua aplicação sabe que um checkout acabou de ser concluído e quanto ele valeu. As suas tags sabem para onde enviar essa informação. A camada de dados fica entre os dois, e o Google declara o objetivo do design diretamente: as tags "are designed to reference information that is added to the data layer in an organized and predictable way, rather than by parsing variables, transaction information, page categories, and other signals scattered throughout your page." Quando um redesign move o preço para outra <div>, as tags que leem a camada de dados continuam funcionando e as que raspam a página quebram.

Quais são os dois tipos de camada de dados?

As camadas de dados têm dois formatos: um objeto de estado que descreve a página e uma fila de eventos que registra o que aconteceu, em ordem. O formato decide como uma tag faz a leitura.

O modelo de objeto de estado é o mais antigo. O Customer Experience Digital Data Layer 1.0, um Community Group Final Report de 10 de dezembro de 2013, diz que o objeto raiz "MUST be digitalData, and all data properties within this specification MUST fall within the hierarchy of the digitalData object." Sua seção de status acrescenta que "It is not a W3C Standard nor is it on the W3C Standards Track." Os eventos ficam em um array dentro do objeto, digitalData.event[n], que a especificação define como "List of events that were measured."

O modelo de fila venceu na prática por causa da ordem de carregamento. A documentação da Adobe explica a vantagem: páginas e scripts "can start to register data, to trigger events, and to register callbacks by adding them to the array, even before the data layer script itself has been loaded." Um array simples aceita pushes antes de existir qualquer código de fornecedor na página.

Como um dataLayer.push vira um evento de analytics?

Um dataLayer.push() vira um evento de analytics quando o Tag Manager processa a mensagem, associa a chave event dela a um acionador e dispara uma tag que lê os valores enviados. A sequência tem cinco etapas:

1. Declare o array uma única vez, acima do snippet do contêiner. O código de instalação do Google é window.dataLayer = window.dataLayer || [];, colocado antes de o Tag Manager carregar.
2. Envie uma mensagem com um nome de evento. A sintaxe do Google é dataLayer.push({'event': 'event_name'}), e um push pode levar valores junto com o evento, como em dataLayer.push({'color': 'red', 'conversionValue': 50, 'event': 'customize'}).
3. O Tag Manager enfileira e processa a mensagem. O Google afirma que "Tag Manager processes messages on a first-in, first-out basis: Each message is processed one at a time, in the order it was received."
4. Um acionador de evento personalizado bate com o nome do evento. "If the message is an event, any tags with trigger conditions that have been met will fire before Tag Manager moves on to the next message."
5. Uma variável da camada de dados entrega o valor à tag, e a tag o envia adiante, por exemplo como parâmetro de evento do GA4.

A etapa 4 explica uma regra que confunde muita gente. Um push sem a chave event atualiza valores, mas não dispara nada. O Google avisa que pushes vindos do código da página "are not guaranteed to be available for the next event", e a solução dele é "add an event name to a message as it is pushed to the data layer, and then listen for that event name with a Custom Event trigger."

O snippet do gtag.js usa a mesma fila. O próprio snippet do Google define a função gtag como um wrapper de uma linha:

window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'TAG_ID');

Então um site que roda gtag.js e Tag Manager ao mesmo tempo tem um único array recebendo mensagens dos dois. O Google é explícito: "Only one dataLayer object is supported per page."

Por que os valores da camada de dados passam de um push para o outro?

Os valores da camada de dados passam de um push para o outro porque cada push é mesclado em um "abstract data model" contínuo em vez de substituí-lo. A biblioteca open source data-layer-helper do Google, que documenta esse modelo, diz que ele "holds the most recent value for all keys that have been set by a data layer message." Valores escalares são sobrescritos. Objetos simples e arrays se mesclam de forma recursiva: as chaves de um objeto novo são copiadas sobre o objeto antigo, e os índices de um array novo são gravados sobre os índices do array antigo, deixando no lugar qualquer índice que o array novo não define.

Essa regra é inofensiva para uma string pageType e perigosa para ecommerce. Envie uma visualização de carrinho com dois itens e depois uma compra com um item, e o modelo ainda pode guardar o segundo item do push anterior. O guia de ecommerce do GA4 para o Tag Manager do Google evita isso limpando os dados primeiro em todos os seus 14 exemplos de evento. O exemplo de compra, resumido:

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "purchase",
  ecommerce: { transaction_id: "T_12345", value: 72.05, currency: "USD", items: [ ... ] }
});

O null funciona porque null conta como "everything else" na tabela de mesclagem, então ele sobrescreve o objeto antigo por inteiro. O push seguinte então se mescla sobre nada. Se os seus relatórios de receita mostram itens que ninguém comprou, procure uma limpeza ausente antes de auditar qualquer outra coisa. O lado do GA4 dessa configuração está em como escolher ferramentas de rastreamento de ecommerce sem rastrear demais.

O que quebra uma camada de dados?

Seis erros explicam a maioria das camadas de dados que parecem corretas e perdem eventos. Cada um vem da própria lista de solução de problemas do Google ou decorre das regras de mesclagem acima.

A linha dos nomes é onde a camada de dados encontra o resto da sua instrumentação. Uma camada de dados só é tão consistente quanto a especificação por trás dela, que é o papel de um plano de rastreamento, e os nomes em si seguem as regras de como uma convenção de nomes de eventos sobrevive à primeira renomeação.

O que um push na camada de dados deve conter?

Um push na camada de dados deve conter o nome do evento e os valores de que um relatório precisa, e nada que identifique uma pessoa. Tudo o que é enviado pode ser lido por todas as tags do contêiner, inclusive tags adicionadas depois por outra pessoa. Conteúdo de campos de formulário, endereços de e-mail e nomes não pertencem à fila; envie um identificador do formulário e um resultado, como o guia prático de rastreamento sem cookies mostra para formulários.

Um teste útil é o mesmo que você aplica a qualquer evento: cada valor no push deve responder a uma pergunta que um relatório faz. Se ninguém consegue citar o relatório, remova a chave. A prática por trás disso, registrar ações como eventos nomeados com propriedades, está em como o rastreamento de eventos registra o que os usuários realmente fizeram.

Toda ferramenta de analytics precisa de uma camada de dados?

Nenhuma ferramenta de analytics precisa estritamente de uma camada de dados; a camada existe para que um gerenciador de tags possa distribuir um único conjunto de valores para vários fornecedores. Uma ferramenta que recebe eventos por uma chamada de função direta dispensa a fila e as regras de mesclagem. A Flowsery funciona assim: o seu rastreamento de metas registra eventos a partir de uma única chamada como window.flowsery("signup"), com "No complex setup or tag managers needed." Os eventos aparecem em um feed em tempo real para você "Debug and validate your tracking instantly", valores de receita podem ser anexados aos eventos para medir o impacto de cada ação, e os eventos são rastreados sem cookies nem dados pessoais. O recurso de rastreamento de metas e eventos mostra a configuração. Sites que já rodam uma camada de dados para outros fornecedores podem mantê-la e chamar window.flowsery() no mesmo código que envia o evento.

Perguntas frequentes

A camada de dados é a mesma coisa que o Google Tag Manager?

Não. A camada de dados é o array na sua página, e o Tag Manager é um dos consumidores que o leem. O snippet do Google para o gtag.js usa o mesmo array dataLayer sem o Tag Manager, e a camada de dados de cliente da Adobe usa um array próprio chamado adobeDataLayer.

Onde o código da camada de dados deve ficar na página?

Declare-o o mais alto possível na página, acima do snippet do Tag Manager ou do gtag.js. O Google diz que qualquer valor que "need to be available to Tag Manager when the page loads" também precisa ser enviado acima do código do contêiner. Pushes colocados mais abaixo ainda chegam à fila, mas depois dos primeiros eventos do contêiner.

Posso renomear a variável dataLayer?

Sim. O Tag Manager recebe o nome como parâmetro no snippet do contêiner, e o gtag.js aceita um parâmetro de query l, como em l=myNewName. Todas as declarações e todos os pushes precisam então usar o novo nome, porque pushes para o nome antigo não chegam a lugar nenhum.

Por que meu evento de compra do GA4 contém itens de um evento anterior?

O push anterior se mesclou no modelo de dados e o seu push de compra não o limpou. Arrays e objetos simples se mesclam de forma recursiva, então itens que sobraram continuam lá. Envie { ecommerce: null } imediatamente antes de cada evento de ecommerce, como fazem os exemplos do Google.

Os valores da camada de dados persistem entre carregamentos de página?

Não. O Google afirma que cada variável da camada de dados persiste "only as long as the visitor remains on the current page." Valores que importam em todas as páginas, como o tipo de visitante ou a categoria da página, precisam ser enviados de novo a cada carregamento.

Qual é a diferença entre dataLayer.push e gtag?

gtag() é um wrapper que chama dataLayer.push(arguments), então os dois gravam na mesma fila. A diferença está no formato da mensagem e nos métodos personalizados: o Google diz que funções enviadas para acessar set, get e reset "must use .push" diretamente, porque o gtag interpreta uma função como "an invalid command" e a ignora.

Por que meu dataLayer.push não disparou nenhuma tag?

Um push só dispara uma tag quando carrega uma chave event que um gatilho de evento personalizado está esperando. Valores enviados sem essa chave atualizam a camada de dados mesmo assim, mas o Tag Manager não tem nada para comparar, então nenhum gatilho roda e nenhuma tag dispara. Adicione o nome do evento no mesmo push, ou esses valores ficam parados até chegar uma mensagem seguinte que o traga.

Devo usar digitalData ou dataLayer em um projeto novo?

Escolha o modelo de fila de eventos, o mesmo que dataLayer e adobeDataLayer usam. Ele aceita pushes antes de qualquer script do fornecedor carregar, exatamente o problema de ordem de carregamento que o modelo de objeto de estado enfrenta. Uma tag que lê digitalData antes de o objeto estar preenchido não lê nada. digitalData também vem de um relatório de um Community Group de 2013 que deixa claro que não é um padrão W3C.

É seguro enviar endereços de e-mail para a camada de dados?

Não. Tudo que é enviado para a camada de dados fica visível para qualquer tag do container, incluindo tags que outra pessoa adicionar depois. Envie um identificador de formulário e um resultado no lugar disso, nunca o conteúdo real do campo, o nome ou o e-mail.

adobeDataLayer é a mesma coisa que o dataLayer do Google?

Os dois são arrays simples que processam mensagens em ordem, mas são variáveis globais separadas. O Tag Manager e o gtag.js do Google compartilham window.dataLayer, e a camada de dados de cliente da Adobe usa seu próprio array, window.adobeDataLayer. A documentação da Adobe descreve a mesma vantagem de ordem de carregamento. Páginas e scripts podem registrar dados e disparar eventos fazendo push no array antes mesmo de o script da camada de dados carregar.