Skip to main content
Este guia mostra como carregar e inicializar o OneSignal Web SDK usando o Google Tag Manager (GTM) e, opcionalmente, definir um External ID e Tags do OneSignal após a inicialização.

Pré-requisitos

  • Um site que suporte HTTPS.
  • Você pode publicar alterações no GTM para o container do site.
  • Você completou o fluxo de configuração do Web SDK do OneSignal até Adicionar código ao site. Isso lhe dá:

Configuração

1. Configure seu aplicativo web do OneSignal

Siga a configuração do Web SDK até chegar à etapa Adicionar código ao site. É aqui que você obterá o OneSignal App ID.
Etapa Adicionar código ao site no painel de configuração do OneSignal Web SDK

Depois de chegar a esta etapa, você precisará fazer alguns ajustes no código para funcionar com o Google Tag Manager.

Você deve fazer upload do arquivo OneSignal Service Worker diretamente para o seu servidor. Consulte OneSignal Service Worker.

2. Crie variáveis do GTM

Crie variáveis do GTM para valores que você referencia em tags. Isso evita codificar valores fixos e torna sua configuração mais fácil de manter. Crie uma variável ONESIGNAL_APP_ID
  1. No GTM, vá para Variables > New.
  2. Escolha Constant.
  3. Nomeie como ONESIGNAL_APP_ID
  4. Defina o valor como seu OneSignal App ID.
  5. Salve
Criando uma variável do OneSignal App ID no Google Tag Manager

Criando uma variável do OneSignal App ID

Agora você pode referenciar seu App ID em qualquer lugar no GTM usando {{ ONESIGNAL_APP_ID }}.
Crie uma variável ONESIGNAL_EXTERNAL_ID (Recomendado) Use esta variável se você associar usuários com um identificador externo (por exemplo, um ID de usuário do seu banco de dados ou sistema de autenticação). Escolha o tipo de variável com base em onde o valor está disponível no seu site. Opções comuns:
  • Data Layer Variable (recomendado)
  • First-Party Cookie
  • DOM Variable (avançado)

3. Crie a tag de inicialização do OneSignal

  1. No GTM, vá para Tags > New
  2. Nomeie a tag: OneSignal - Init
  3. Tag Type: Custom HTML
  4. Cole o código abaixo.
  5. Em Advanced Settings > Tag firing options, defina Once per page.
  6. Em Triggering, selecione Initialization - All Pages.
HTML
Configurando a tag OneSignal - Init no Google Tag Manager

Configurando a tag OneSignal - Init

Se você usar um banner de consentimento / CMP, consulte as opções de Consent Mode e considerações de privacidade abaixo.

4. Defina External ID e Tags

Definir o External ID é opcional, mas recomendado, pois permite identificar usuários em dispositivos e sincronizar com seu backend. Enviar ONESIGNAL_EXTERNAL_ID para o dataLayer Este exemplo mostra como você pode enviar um ID de usuário para o dataLayer para que o GTM possa lê-lo via a variável ONESIGNAL_EXTERNAL_ID (criada no passo 2).
HTML
Crie uma tag GTM para definir o External ID Configuração da tag:
  • Nome da tag: OneSignal – Set External ID
  • Tipo da tag: Custom HTML
  • Opções de disparo da tag: Once per page
  • Trigger:
    • Crie um gatilho de evento personalizado para OneSignalInitialized (definido na tag OneSignal - Init acima) e
    • Opcionalmente se você souber que o ID do usuário está disponível no carregamento da página.
O método necessário para definir o External ID é OneSignal.login(externalId) onde externalId é uma string.Se {{ONESIGNAL_EXTERNAL_ID}} estiver vazio (ou o GTM substituir por “undefined” / “null”), a chamada de login será ignorada e o External ID não será definido. Este é um problema comum de timing do GTM.

Definir Tags

Isto envia Tags do OneSignal usando nosso Web SDK. Configuração da tag:
  • Nome: OneSignal - Add Tags
  • Tipo da tag: Custom HTML
  • Opções de disparo da tag: Once per page
  • Trigger:
    • OneSignalInitialized, e
    • Sua condição para quando os dados da tag estiverem disponíveis (por exemplo: após login, em uma página de perfil, após compra).
Cole este código e substitua o exemplo de tag TAG e VALUE.
HTML
Envie tags apenas quando você tiver os dados do usuário disponíveis (por exemplo: após login, após o carregamento de um perfil ou após um evento de conversão conhecido).
Se o seu site usar Consent Mode / um CMP, decida se o OneSignal deve carregar:
  • Apenas após consentimento (comum para UE/Reino Unido), ou
  • Imediatamente (comum onde o armazenamento “funcional” é permitido por padrão).
O GTM suporta um gatilho de inicialização de consentimento e controles de consentimento em nível de tag para gerenciar o comportamento da tag com base no consentimento do usuário. No entanto, o OneSignal também fornece métodos de consentimento de privacidade para controlar quando o SDK é carregado.

Testes

  1. No GTM, abra o modo Preview.
  2. Carregue seu site e confirme:
    • OneSignal - Init dispara uma vez.
    • OneSignalInitialized aparece na linha do tempo de eventos do GTM (se você manteve o push de evento).
  3. Inscreva-se no seu site. Consulte Solicitações de permissão web para detalhes de solicitação.
  4. No painel do OneSignal, vá para Audience > Subscriptions e confirme:
    • Uma inscrição aparece após você aceitar.
    • Um External ID é visível se você definiu um.
  5. Envie um push de teste de Messages > New Push.
Se a inicialização estiver funcionando, você verá as inscrições aparecendo no OneSignal após aceitar.

Solução de problemas

  • A tag Init dispara, mas o SDK nunca carrega
    • Verifique se a Content Security Policy (CSP) está bloqueando https://cdn.onesignal.com.
    • Verifique bloqueadores de anúncios/bloqueadores de scripts.
  • Erros de dataLayer
    • Certifique-se de que window.dataLayer = window.dataLayer || [] esteja definido antes de qualquer chamada dataLayer.push().
  • Solicitações duplicadas / carregamento duplicado do SDK
    • Certifique-se de que você não está carregando o OneSignal também através do código do site, um plugin de CMS ou outra tag do GTM.
  • Add Tags executa mas não aparece no OneSignal
    • Confirme que o Trigger Group espera OneSignalInitialized.
    • Confirme que seu gatilho de ação do usuário realmente dispara.
    • Confirme que as tags são pares chave/valor válidos e dentro dos limites do plano.
Se você ainda precisar de ajuda, consulte Solução de problemas do Web SDK para correções comuns.

Próximos passos