O Singular Website SDK é um recurso empresarial. Se você estiver interessado em usar esse recurso, entre em contato com seu Gerente de Sucesso do Cliente.
| Singular Website SDK (Integração GTM) |
|
|---|---|
| Compatibilidade com navegadores |
|
Introdução
O Singular Website SDK permite atribuir atividades do site a pontos de contato de marketing e rastrear eventos do usuário em seu site. Ele também é um componente-chave na solução de atribuição entre dispositivos da Singular, possibilitando a análise das jornadas dos usuários e o cálculo do LTV e do ROAS entre plataformas. Para sua conveniência, o Singular Website SDK está integrado ao Google Tag Manager.
Pré-requisitos
Antes de integrar o Singular Website SDK, certifique-se de que:
- O Google Tag Manager foi configurado em seu site.
- Você configurou os acionadores do Gerenciador de tags do Google conforme necessário para os eventos que deseja enviar para a Singular (seu evento de conversão e quaisquer eventos personalizados). Consulte Sobre acionadoresna documentação do Google.
- Você configurou as variáveis do Google Tag Manager conforme necessário para os eventos que deseja enviar para a Singular. Por exemplo, se você quiser enviar eventos de transação e incluir a receita da transação, precisará configurar variáveis para a soma e a moeda da transação. Consulte Sobre variáveisna documentação do Google.
Integração do SDK da Singular
Inicialização do SDK
Para usar o Singular Web SDK em seu site, você deve adicionar a tag de inicialização do Singular. Recomendamos configurar esse evento para ser acionado assim que seu site for carregado (por exemplo, na exibição da página).
Para adicionar uma tag de inicialização do Singular:
- Em sua conta do Google Tag Manager, clique em Tags > Novo.
- Na janela Configuração de tags, clique em Configuração de tags e, no menu Tipo de tag, selecione "Singular Web Tracking".
- Em Track Type (Tipo de rastreamento), selecione "Initialization" (Inicialização).
- Preencha os outros parâmetros necessários:
- SDK Key e SDK Secret: você pode obtê-los fazendo login na sua conta da Singular e acessando "Developer Tools > SDK Integration > SDK Keys".
- Product Id: Um nome para seu site. Recomendamos usar a notação de DNS reverso de seu domínio principal da Web, por exemplo, "com.example", que será usado para identificar seu site em toda a plataforma Singular. Esse valor também deve corresponder ao ID do pacote de aplicativos na página de aplicativos na plataforma Singular.
- Opcional:
- Nível de registro: A configuração do registro de depuração do SDK no console. O padrão é nenhum.
- Tempo limite da sessão: Quanto tempo o usuário precisa ficar inativo para que o SDK crie uma nova sessão. A Singular envia sessões de usuários para calcular a retenção de usuários e permitir a atribuição de reengajamento. O valor padrão é 30 minutos.
- Rastreamento entre subdomínios
- Clique em Triggering (Acionamento ) e adicione o acionador "Page View" (Exibição de página).
- Clique em Save (Salvar).
Observação: Para SPAs (aplicativos de página única), você deve acionar o tipo de rastreamento PageVisit sempre que for direcionado para uma página diferente. Não chame PageVisit na primeira página que for carregada, pois a inicialização já informa uma visita à página.
Opcional: Definição do ID do usuário
Enquanto o usuário executar ações em seu site sem estar conectado, os eventos serão enviados à Singular com um ID de usuário gerado pela Singular. Porém, depois que o usuário se registrar ou fizer login, os eventos poderão ser enviados à Singular juntamente com o ID de usuário usado em seu site, por exemplo, um endereço de e-mail.
A Singular usa o ID do usuário em exportações de dados no nível do usuário (consulte Exportando logs de atribuição), bem como em postbacks internos de BI, se você os tiver configurado (consulte Configurando postbacks internos de BI).
Há duas maneiras de enviar o ID do usuário para a Singular:
- Recomendada: Se você souber o ID do usuário quando o site for aberto, defina o ID do usuário no tipo de trilha Initialization ao inicializar o SDK. Isso torna a ID de usuário disponível para a Singular desde a primeira visita à página.
- Como alternativa, você pode chamar o método Login em qualquer ponto da execução. Recomendamos chamá-lo assim que o ID de usuário estiver disponível.
Para compartilhar a ID de usuário com a Singular, adicione uma tag Singular com o tipo de rastreamento "Login":
- Em sua conta do Google Tag Manager, clique em Tags > Novo.
- Na janela Configuração de tags, clique em Configuração de tags e, no menu Tipo de tag, selecione "Singular Web Tracking".
- Em Tipo de rastreamento, selecione "Login".
- Em Custom User Id (ID do usuário personalizado), insira a variável do Google Tag Manager que contém o ID do usuário.
- Clique em Triggering (Acionamento ) e adicione o evento de acionamento: login ou registro do usuário.
- Clique em Save (Salvar).
Para cancelar a definição do ID do usuário, adicione uma tag com o tipo de rastreamento "Logout":
- Em sua conta do Google Tag Manager, clique em Tags > New (Tags > Novo).
- Na janela Configuração de tags, clique em Configuração de tags e, no menu Tipo de tag, selecione "Singular Web Tracking".
- Em Tipo de rastreamento, selecione "Logout".
- Clique em Triggering (Acionamento ) e adicione o evento de acionamento: logout do usuário.
- Clique em Save (Salvar).
Observações:
- O ID do usuário persiste até que você o desfaça usando o tipo de rastreamento de logout ou até que o usuário exclua seu armazenamento local.
- Fechar/refrescar o site não cancela a definição do ID do usuário.
- A navegação em modo privado, como incógnito, impedirá que o Singular mantenha a ID de usuário, pois o armazenamento local é excluído automaticamente ao fechar o navegador.
Opcional: Rastreamento de eventos e receita
Rastreamento de eventos (não receita)
A Singular pode coletar dados sobre eventos de usuários dentro do site para ajudar a analisar o desempenho de suas campanhas e medir KPIs. Por exemplo, sua organização pode querer coletar dados sobre logins de usuários, registros ou conclusões de tutoriais.
Você pode enviar eventos para a Singular usando o método de evento.
Observações:
- É altamente recomendável passar nomes e atributos de eventos em inglês para garantir a compatibilidade com parceiros terceirizados e soluções de análise, caso planeje usá-los.
- Os nomes de eventos são limitados a 32 caracteres ASCII. As cadeias de caracteres em caracteres não ASCII devem ter menos de 32 bytes depois de convertidas em UTF-8.
- Os atributos e valores são limitados a 500 caracteres ASCII.
Para rastrear um evento personalizado:
- Em sua conta do Google Tag Manager, clique em Tags > Novo.
- Na janela Configuração de tags, clique em Configuração de tags e, no menu Tipo de tag, selecione "Rastreamento singular da Web".
- Em Track Type (Tipo de rastreamento), selecione "Custom Event" (Evento personalizado).
- Em Event Name (Nome do evento), digite um nome para o evento ou digite uma variável do Google Tag Manager que você tenha definido anteriormente.
- Clique em Triggering (Acionamento ) e adicione o evento de acionamento.
- Clique em Save (Salvar).
Rastreamento de receita
A Singular pode coletar dados sobre a receita obtida por meio do site para ajudar a analisar o desempenho e o ROI de suas campanhas. A Singular disponibilizará os dados para você em relatórios, exportações de registros e postbacks.
Use o método de receita para relatar eventos. A receita permite que você passe um nome de evento personalizado para que você possa visualizar a receita nos relatórios da Singular divididos pelos diferentes tipos de eventos de receita.
Observações: Qualquer receita informada em uma moeda diferente será convertida automaticamente para a moeda preferida de sua organização, conforme definido em sua conta da Singular.
Para rastrear eventos de receita:
- Em sua conta do Google Tag Manager, clique em Tags > Novo.
- Na janela Configuração de tags, clique em Configuração de tags e, no menu Tipo de tag, selecione "Singular Web Tracking".
- Em Track Type (Tipo de rastreamento), selecione "Revenue Event" (Evento de receita).
- Em Event Name (Nome do evento), digite um nome para o evento ou digite uma variável do Google Tag Manager que você tenha definido anteriormente.
- Em Currency (Moeda), insira uma variável que represente um código de moeda ISO 4217 de três letras, como "USD", "EUR" ou "INR".
- Em Revenue (Receita), insira uma variável que contenha o valor da transação (pode ser passado como um valor decimal, por exemplo, 1,99).
- Clique em Triggering (Acionamento ) e adicione o evento de acionamento.
- Clique em Save (Salvar).
Opcional: Rastreamento entre subdomínios
Por padrão, o Singular Website SDK gera um Singular Device ID e o mantém usando o armazenamento do navegador. Como esse armazenamento não pode ser compartilhado entre subdomínios, o SDK acaba gerando uma nova ID para cada subdomínio.
Se quiser manter a ID do dispositivo Singular em todos os subdomínios, você pode usar uma das seguintes opções:
Método A: Persistência automática usando cookies
Você pode fazer com que o Singular SDK persista a ID do dispositivo Singular usando um cookie primário personalizado. Escolha a seguinte opção e defina o domínio principal que deseja rastrear.
Método B (Avançado): Ler o Singular Device ID para a variável GTM
Se não quiser que o Singular SDK mantenha o ID do dispositivo automaticamente, você pode manter o ID manualmente entre domínios - por exemplo, usando um cookie de domínio de nível superior ou um cookie do lado do servidor. O valor deve ser uma ID gerada anteriormente pela Singular no formato uuid4 válido.
Observação: você pode ler o ID do dispositivo Singular definindo uma variável JavaScript personalizada e chamando singularSdk.getSingularDeviceId() depois de chamar a tag Init track-type.
Mapeamento de dispositivo de ID de usuário personalizado
Importante: esse é um recurso avançado. Consulte um dos engenheiros de soluções da Singular antes de implementá-lo.
A Singular pode receber dados adicionais de rastreamento da Web por meio da integração de servidor para servidor. Para utilizar esse recurso, precisamos mapear o ID de usuário personalizado para o identificador de rastreamento da Web da Singular.
Observação: chame esse tipo de rastreamento assim que possível após a inicialização do SDK ou quando tiver o ID de usuário personalizado.
Para mapear o ID de usuário personalizado para o identificador de rastreamento da Web da Singular:
- Em sua conta do Google Tag Manager, clique em Tags > Novo.
- Na janela Configuração de tags, clique em Configuração de tags e, no menuTipo de tag, selecione "Singular Web Tracking".
- Em Track Type (Tipo de rastreamento), selecione "Set Device Custom User Id" (Definir ID de usuário personalizado do dispositivo).
- Em Custom User Id (ID do usuário personalizado), insira a variável do Google Tag Manager que contém o ID do usuário.
- Clique em Triggering (Acionamento) e adicione o evento de acionamento.
- Clique em Save (Salvar).