Enviar eventos personalizados para o Google Tag Manager e Analytics

[Discourse]

Continuando a discussão de Integrando o Google Tag Manager com o Google Analytics:

Envio de eventos personalizados para o Google Tag Manager e Analytics

Este guia explica como configurar seu site Discourse para enviar eventos personalizados para o Google Tag Manager (GTM) e o Google Analytics, permitindo rastrear interações específicas do usuário.

Nível de usuário necessário: Administrador

Pré-requisitos

Antes de implementar eventos personalizados, certifique-se de que você tenha:

1. Configurado o Google Tag Manager no seu site Discourse seguindo o guia Configurar o Google Tag Manager para Analytics
2. Adicionado seu ID de contêiner do GTM à configuração gtm container id do seu site
3. Atualizado a configuração content security policy script src do seu site para permitir scripts do Google

Adicionando eventos personalizados

Criar um componente de tema

1. Navegue até Admin > Personalizar > Componentes
2. Clique em “Novo” e selecione “Criar novo componente”
3. Dê um nome ao seu componente
4. Selecione a aba JS e adicione seu código. Por exemplo, o código abaixo captura os acionamentos de appEvent e envia os seguintes eventos para a dataLayer:

• post:liked
• post:created
• topic:created

import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  window.dataLayer = window.dataLayer || [];

  // Rastrear curtidas de postagens
  api.onAppEvent("page:like-toggled", (post, likeAction) => {
    let topic = post.topic;
    if (post && topic && likeAction && likeAction.acted) {
      window.dataLayer.push({
        'event': 'postLiked',
        'postId': post.id
      });
    }
  });

  // Rastrear novas postagens
  api.onAppEvent("post:created", post => {
    if (post) {
      window.dataLayer.push({
        'event': 'postCreated',
        'postId': post.id
      });
    }
  });

  // Rastrear novos tópicos
  api.onAppEvent("topic:created", (post, composerModel) => {
    if (post) {
      window.dataLayer.push({
        'event': 'topicCreated',
        'topicCategory': composerModel.get("category.name"),
        'topicId': post.topic_id
      });
    }
  });
});

5. Salve o componente
6. Adicione o componente a todos os temas ativos no seu site

Eventos disponíveis

Todos os eventos de gatilho disponíveis estão listados aqui: Referência de gatilhos AppEvents

Configurando o GTM

Criar um gatilho

1. Acesse https://tagmanager.google.com/
2. Selecione “Gatilhos” no menu lateral
3. Clique em “Novo”
4. Nomeie seu gatilho
5. Selecione “Evento Personalizado” como Tipo de Gatilho
6. Insira o nome do evento (ex: postCreated)
7. Configure o gatilho para disparar em “Todos os Eventos Personalizados”

Criar uma variável de Data Layer

1. Selecione “Variáveis” no menu lateral do GTM
2. Clique em “Novo” na seção Variáveis Definidas pelo Usuário
3. Nomeie sua variável
4. Selecione “Variável da Camada de Dados” como Tipo de Variável
5. Insira o nome da variável da camada de dados (ex: postCreated)
6. Defina a Versão da Camada de Dados como “Versão 2”

Criar uma Tag do Google para Rastreamento de Eventos

A partir de 2024, a abordagem recomendada é usar o novo modelo “Tag do Google” em vez do tipo de tag mais antigo “Google Analytics: GA4 Event”. A Tag do Google fornece melhor integração com o GA4 e inclui suporte integrado ao Consent Mode v2.

1. Selecione “Tags” no menu lateral do GTM
2. Clique em “Novo”
3. Nomeie sua tag (ex: “GT - Postagem Criada”)
4. Em Configuração da Tag:
   • Selecione “Tag do Google”
   • Selecione sua Configuração GA4 (ou crie uma nova se esta for sua primeira tag)
   • Para “Nome do Evento”, insira um nome descritivo seguindo as convenções de nomenclatura do GA4 (ex: post_created)
   • Em “Configurações de Configuração”, clique em “Adicionar Linha” para incluir suas variáveis da camada de dados:
     • Parâmetro de Configuração: (ex: postId)
     • Valor: Sua variável da camada de dados (ex: {{postCreated}})
5. Em “Disparo”:
   • Selecione seu gatilho de evento personalizado criado anteriormente

Se você estiver usando tags do tipo “Google Analytics: GA4 Event”, elas continuarão funcionando, mas novas implementações devem usar o modelo “Tag do Google” para melhor compatibilidade futura e recursos.

Requisitos de Nomenclatura de Eventos

O GA tem requisitos específicos para nomes de eventos:

• Use snake_case (letras minúsculas com sublinhados)
• Comprimento máximo de 40 caracteres
• Pode conter apenas caracteres alfanuméricos e sublinhados

Testando sua Tag do Google

1. Clique no botão “Visualizar” no GTM
2. Navegue até seu site Discourse
3. Realize a ação que deseja rastrear (ex: crie uma postagem)
4. No modo de Visualização do GTM:
   • Verifique se o seu evento personalizado aparece no painel esquerdo
   • Verifique se sua Tag do Google disparou corretamente
   • Confirme se todos os parâmetros estão sendo passados como esperado
5. No Google Analytics:
   • Navegue até Configurar > Eventos
   • Seu evento personalizado deve aparecer na lista depois de ter sido acionado
   • Observação: pode levar até 24 horas para que novos eventos apareçam nos relatórios do GA4

Você pode usar o GA4 DebugView para ver dados de eventos em tempo real durante o teste.

Solução de problemas

Se você não estiver vendo eventos no GTM:

1. Verifique se o ID do seu contêiner do GTM está configurado corretamente no Discourse
2. Certifique-se de que seu componente de tema esteja adicionado a todos os temas ativos
3. Adicione instruções console.log para verificar se os eventos estão disparando:

api.onAppEvent("post:created", post => {
  console.log("post:created event triggered");
  if (post) {
    window.dataLayer.push({
      'event': 'postCreated',
      'postId': post.id
    });
  }
});

4. Use a extensão do Chrome Simple Data Layer Viewer para monitorar a camada de dados
5. Se você vir erros de Content Security Policy (CSP), consulte os pré-requisitos referenciados acima e revise Mitigate XSS Attacks with Content Security Policy para etapas adicionais.

Se você tiver a configuração de site ga universal tracking code preenchida, esvazie-a, pois o GTM lidará com o script de rastreamento.