Singular SDK Site Web: Integração nativa

Seguir
Avatar
Jared Ornstead
Updated

 

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.

O Singular Website SDK permite atribuir atividades do website a pontos de contato de marketing e rastrear eventos de usuários em seu website. É também um componente-chave na solução de atribuição entre dispositivos da Singular, tornando possível analisar as jornadas dos usuários e calcular o LTV e o ROAS entre plataformas.

Para saber mais, consulte nossas Perguntas frequentes sobre atribuição entre dispositivose Perguntas frequentes sobre atribuição na Web.

Além da versão nativa em JavaScript descrita aqui, o Singular Website SDK também está disponível como um modelo do Google Tag Manager.

Compatibilidade com navegadores:

Chrome: 15+ Edge: 15+ Internet Explorer: 10+
Safari: 5.1+ Firefox: 6+ Opera: 15+

Como adicionar o script do SDK ao seu site

Use um dos métodos a seguir para configurar o SDK em seu site ou aplicativo da Web.

Link para o script no CDN da Singular

Nesse método, a Singular hospeda o código JavaScript do SDK no CDN da Singular.

Adicione o seguinte código dentro da tag <head> de cada página que você deseja rastrear:

<head>
      <!-- Usando a versão mais recente do SDK   -->
      <script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js">
      </script>
</head>

Observação: O código acima está vinculado à versão mais recente do SDK. Se você quiser usar uma versão específica do SDK, use o código a seguir:

<head>
      <!-- Uso de uma versão fixa do SDK   -->
      <script src="https://web-sdk-cdn.singular.net/singular-sdk/1.4.2/singular-sdk.js">
      </script>
</head>

Configuração usando o NPM

  1. Execute npm i singular-sdk no diretório raiz do seu projeto ou adicione "singular-sdk": "^1.4.1" à seção de dependências no seu arquivo package.json e, em seguida, execute npm install.
  2. Adicione o código a seguir nos scripts que você deseja usar o SDK.
import {singularSdk, SingularConfig} from "singular-sdk";

Inicialização do SDK

O código de inicialização do SDK deve ser chamado sempre que uma página for carregada. Ele é um pré-requisito para todas as funcionalidades de atribuição do Singular e também:

  • Cria uma nova sessão de usuário quando um usuário entra no site com novos dados de publicidade ou quando o tempo limite da sessão é ultrapassado.
  • Envia um novo evento de "visita à página" para a Singular

Os eventos de visitas à página e as sessões de usuário são usados para calcular a retenção de usuários e permitir a atribuição de reengajamento.

1. Construção do objeto SingularConfig

Antes de inicializar o SDK, você precisa criar um objeto SingularConfig. Esse objeto conterá:

  • SDK Key e SDK Secret: para encontrá-los, faça login em sua conta da Singular e vá para "Developer Tools > SDK Integration > SDK Keys".
  • Seu ID do produto: Um nome para seu site. Recomendamos usar a notação de DNS reverso de seu domínio principal da Web, por exemplo, "com.example". Isso 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.
  • Opcionalmente, quaisquer preferências de SDK que você queira definir (leia mais para obter detalhes).

Para criar um objeto SingularConfig básico, use este código:

const config = new SingularConfig(sdkKey, sdkSecret, productId);

No entanto, você provavelmente desejará adicionar configurações para habilitar vários recursos oferecidos pela Singular.

Para adicionar configurações, você usará os métodos ".with" do objeto SingularConfig. Por exemplo:

  // Configure o SDK para passar o ID do usuário para o Singular
  const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withCustomUserId(userId);

Referência do método SingularConfig

Aqui estão todos os métodos ".with" disponíveis.

Método Descrição Saiba mais
.withCustomUserId(customId) Enviar o ID do usuário para a Singular Definir a ID do usuário
.withProductName(productName) Um nome de exibição opcional para o produto  
.withLogLevel(logLevel) Configura o nível de registro: 0 - Nenhum (padrão); 1 - Warn; 2 - Info; 3 - Debug.  
.withSessionTimeoutInMinutes (timeout) Define o tempo limite da sessão em minutos (padrão: 30 minutos)

 
.withAutoPersistentSingularDeviceId (domain) Ativar o rastreamento automático entre subdomínios Auto-Persistência usando cookies

.withPersistentSingularDeviceId (singularDeviceId)

 Ativar o rastreamento manual entre subdomínios Definir manualmente o ID do dispositivo singular
.withInitFinishedCallback(callback) Invocar uma chamada de retorno quando a inicialização do SDK estiver concluída Invocação de uma função de retorno de chamada quando a inicialização estiverconcluída

2. Inicialização da Singular

Depois de criar o objeto SingularConfig, inicialize a Singular usando o método init, passando o objeto config.

O método init pode ser chamado em qualquer ponto do código, mas deve ser chamado antes que qualquer evento seja relatado. Recomendamos chamar init durante o carregamento de cada página que você deseja rastrear.

Método init
Descrição Inicializa o SDK com as opções de configuração definidas no objeto SingularConfig.
Assinatura init(config)
Exemplo de uso 
  function initSingular() {
      const config = new SingularConfig(sdkKey, 
        sdkSecret, productId);
      singularSdk.init(config);
  }

Importante: Para aplicativos de página única (SPAs), chame singularSdk.pageVisit() toda vez que for roteado para uma página diferente. Não chame singularSdk.pageVisit() na primeira página que for carregada, pois singularSdk.init já relata uma visita à página.

Invocação de uma função de retorno de chamada quando a inicialização estiver concluída

Para definir uma função de retorno de chamada a ser chamada quando a inicialização for concluída, use . withInitFinishedCallback(callback) no objeto SingularConfig.

Método withInitFinishedCallback
Descrição Define a chamada de retorno que será chamada quando o processo de inicialização for concluído.
Assinatura withInitFinishedCallback(callback)
Exemplo de uso 
  function initSingular() {      
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withInitFinishedCallback(initParams=> {
        // Essa chamada de retorno será chamada quando o método init for concluído
  
        // Você pode obter o ID do dispositivo Singular aqui
        const singularDeviceId = initParams.singularDeviceId;
      });
  singularSdk.init(config);
  }

Envio do ID de usuário para a Singular (opcional)

Você pode enviar seu ID de usuário interno para a Singular usando um método do SDK da Singular.

Observação: Se você usar a solução Cross-Device da Singular, deverá coletar o ID do usuário em todas as plataformas.

  • O ID do usuário pode ser qualquer identificador e não deve expor PII (Informações Pessoais Identificáveis). Por exemplo, você não deve usar o endereço de e-mail, nome de usuário ou número de telefone de um usuário. A Singular recomenda o uso de um valor hash exclusivo apenas para seus dados primários.
  • O valor do ID de usuário passado para a Singular também deve ser o mesmo ID de usuário interno que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
  • A Singular incluirá o ID de usuário nas exportações em nível de usuário, ETL e postbacks de BI interno (se configurado). O ID do usuário é um dado primário, e a Singular não o compartilha com terceiros.
  • O valor da ID de usuário, quando definido com o método Singular SDK, persistirá até que seja desfeito usando o método logout() ou até que o armazenamento local do navegador seja excluído. Fechar ou atualizar o site não cancela a definição da ID de usuário.
  • No modo privado/incógnito, o SDK não pode manter a ID de usuário porque o navegador exclui automaticamente o armazenamento local quando é fechado.

Para definir a ID de usuário, use o método login(). Para cancelar a definição (por exemplo, se o usuário fizer "logout" da conta), chame o método logout().

Observação: se vários usuários usarem um único dispositivo, recomendamos a implementação de um fluxo de logout para definir e cancelar a definição da ID de usuário para cada login e logout.

Se você já souber a ID do usuário quando o Singular SDK for inicializado no site, defina a ID do usuário no objeto de configuração. Dessa forma, a Singular pode ter a ID de usuário desde a primeira sessão. No entanto, a ID do usuário normalmente não está disponível até que o usuário se registre ou faça um login. Nesse caso, chame login() depois que o fluxo de registro for concluído.

Método login() do SingularSDK
Descrição Envia o ID do usuário para o Singular.
Assinatura login(customUserId)
Exemplo de uso 
singularSdk.login("custom_user_id");
Método logout() do SingularSDK
Descrição Desfaz a configuração do ID de usuário que foi enviado para a Singular.
Assinatura logout()
Exemplo de uso 
singularSdk.logout();

Opcional: Mapeamento de dispositivo de ID de usuário personalizado

Importante: esse recurso avançado da Enterprise só está disponível em casos excepcionais. Consulte um dos engenheiros de soluções da Singular antes de implementá-lo.

A Singular pode receber dados adicionais de rastreamento de eventos móveis por meio de uma integração de servidor para servidor. Para utilizar esse recurso, você deve mapear o ID do usuário para o identificador de rastreamento de dispositivos móveis da Singular.

Observação: chame esse método o mais rápido possível após a inicialização do SDK da Singular ou assim que tiver o ID do usuário.

Método setDeviceCustomUserId do SingularSDK
Descrição Define o ID de usuário personalizado igual ao login e o mapeia para o identificador de rastreamento da Singular.
Assinatura singularSdk.setDeviceCustomUserId(userId)
Exemplo de uso 
singularSdk.setDeviceCustomUserId("customUserId");

Opcional: Rastreamento de eventos e receita

Rastreamento de eventos (não receita)

A Singular pode coletar dados sobre eventos de usuários no 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ção:

  • É 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.
evento Método
Descrição Relata um evento de usuário à Singular com ou sem informações adicionais.
Assinatura

singularSdk.event(eventName, args)

Observação: "args" é um objeto JavaScript com pares de valores chave. Se você não quiser passar nenhum args adicional, chame o método event apenas com o nome do evento.
Exemplo de uso 
  // Enviar um evento Registration_Completed sem argumentos
  singularSdk.event("Registration_Completed");

  // Envie um evento chamado "Registration_Completed" (Registro_Concluído) com propriedades adicionais
  singularSdk.event("Registration_Completed",
  {key1: 'value1',
  key2: 'value2'});

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 log e postbacks.

Use o método de receita para relatar eventos. A receita permite que você passe um nome de evento personalizado, de modo 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.

receita Método
Descrição Envia um evento de receita para a Singular com informações adicionais opcionais.
Assinatura

singularSdk.revenue(eventName, currency, amount, args)

Observação:

  • Passe currency como um código de moeda ISO 4217 de três letras, como "USD", "EUR" ou "INR".
  • O valor do montante pode ser passado como um valor decimal.
Exemplo de uso 
  // Enviar um evento de receita para a Singular 
  singularSdk.revenue("Item_Purchased","USD", 5.50);

  // Enviar um evento de receita para o Singular com argumentos adicionais
  singularSdk.revenue("Item_Purchased","USD", 5.50,
  {key1: 'value1',
   key2: 'value2');

Opcional: Rastreamento entre subdomínios

Por padrão, o Singular Website SDK gera uma ID de dispositivo Singular e a 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 personalizado de primeira parte. Use o método a seguir e defina o domínio principal que deseja rastrear.

Método withAutoPersistentSingularDeviceId
Descrição Inicializa o SDK com opções de configuração, incluindo o domínio principal para persistir automaticamente o Singular Device Id.
Assinatura withAutoPersistentSingularDeviceId(domain)
Exemplo de uso 
  function initSingular() {
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withAutoPersistentSingularDeviceId(“example.com”);
    singularSdk.init(config);
  }

Método B (Avançado): Definir manualmente o ID de dispositivo singular

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 a ID do dispositivo Singular usando singularSdk.getSingularDeviceId() depois de chamar o método init ou usar InitFinishedCallback.

Método withPersistentSingularDeviceId

Descrição

Inicializa o SDK com opções de configuração, incluindo o Singular Device Id que você deseja manter.
Assinatura withPersistentSingularDeviceId(singularDeviceId)
Exemplo de uso 
  function initSingular() {
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withPersistentSingularDeviceId(singularDeviceId);
    singularSdk.init(config);
  }

Opcional: Obter ID de correspondência

Importante: esse é um recurso avançado. Consulte um dos engenheiros de soluções da Singular antes de implementá-lo.

A Singular pode atribuir instalações de servidor para servidor a partir de plataformas de PC e console com base em um Match ID exclusivo e determinístico por usuário. Para utilizar esse recurso, recupere o Match ID do Web SDK da Singular após a inicialização.

getMatchID Método
Descrição Obtém o Match ID exclusivo para essa sessão da Web
Assinatura singularSdk.getMatchID()
Exemplo de uso 
  // Obtém a ID de correspondência do usuário a ser incluída na primeira sessão de outras plataformas
  singularSdk.getMatchID()