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

Para saber mais, consulte nossas Perguntas Frequentes sobre Atribuição entre Dispositivos e Perguntas Frequentes sobre Atribuição na Web.

Pré-requisitos

Antes de integrar o Singular Website SDK, certifique-se de que esses pré-requisitos sejam atendidos:

• O Google Tag Manager foi configurado no seu site.
• Você configurou os gatilhos do Google Tag Manager conforme necessário para os eventos que deseja enviar para o Singular (seu evento de conversão e quaisquer eventos personalizados).
• 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.

Tag 1 - Adicionando a biblioteca SDK

A biblioteca JavaScript do Singular deve ser carregada ou injetada no site antes que o SDK do Singular seja inicializado ou qualquer função do Singular seja acionada. Para garantir isso, a biblioteca será injetada usando a opção de tag HTML personalizada no Google Tag Manager (GTM).

Para manter a funcionalidade adequada, a biblioteca deve ser incluída em todas as páginas do site. Usaremos o acionador Window Loaded no GTM para controlar o tempo de injeção da biblioteca, garantindo que ela seja carregada depois que o conteúdo da página estiver totalmente carregado.

• Crie uma tag HTML personalizada para carregar a biblioteca SDK e adicione permissão para buscar dados de dicas do cliente.
• Nomeie a tag como"Singular - Carregador de SDK"
• Insira o seguinte código na janela HTML

  <script>
  (function() {
    // Check if singularSdk is already loaded
  
  
    if (window.singularSdk) {
      return; // SDK already loaded, no need to load again
  
  
    }
  
    // Inject the meta tag for client hints delegation
  
  
    var metaTag = document.createElement('meta');
    metaTag.setAttribute('http-equiv', 'delegate-ch');
    metaTag.setAttribute('content', 'sec-ch-ua-model https://sdk-api-v1.singular.net; sec-ch-ua-platform-version https://sdk-api-v1.singular.net; sec-ch-ua-full-version-list https://sdk-api-v1.singular.net');
    document.head.appendChild(metaTag);
    
    // Create and load the Singular SDK script
  
  
    var script = document.createElement('script');
    script.src = 'https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js';
    script.async = true;
  
    // Once the script is loaded, push to dataLayer
  
  
    script.addEventListener('load', function() {
      window.dataLayer = window.dataLayer || [];  // Ensure dataLayer is initialized
  
  
      window.dataLayer.push({
        event: 'singularSDKLibraryLoaded'
      });
    });
  
    // Append the script tag to the head of the document
  
  
    document.head.appendChild(script);
  })();
  </script>
  

• Em Configurações avançadas, defina a prioridade de disparo da tag como 99
• Na secção Triggering, adicione um Firing Trigger para"Window Loaded"
• Salve a tag

Tag 2 - Tag de inicialização do SDK

O código de inicialização do Singular SDK deve ser executado sempre que uma página for carregada, mas somente após o disparo da tag Singular - SDK Loader. Para garantir isso, usaremos o evento Data Layer criado pela tag Singular - SDK Loader como gatilho.

A inicialização do Singular SDK é um pré-requisito para todas as funcionalidades de atribuição do Singular. Ele serve a dois propósitos críticos:

• Criar uma nova sessão de utilizador quando um utilizador entra no site com novos dados de publicidade ou quando o tempo limite da sessão tiver expirado.
• Enviar um evento de "visita à página" para o Singular.

Esses eventos de "visita à página" e sessões de usuário são essenciais para calcular a retenção de usuários e permitir a atribuição de reengajamento.

// Configure the SDK to pass the user ID to Singular


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

Enviando o ID de usuário para a Singular (opcional)

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

• A ID de usuário pode ser qualquer identificador e não deve expor PII (Informações de identificação pessoal). Por exemplo, não deve utilizar o endereço de correio eletrónico, o nome de utilizador ou o número de telefone de um utilizador. A Singular recomenda o uso de um valor com hash exclusivo apenas para seus dados primários.
• O valor da ID de usuário passado para a Singular também deve ser a mesma ID de usuário interna que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
• A Singular incluirá o ID de utilizador nas exportações ao nível do utilizador, ETL e postbacks do BI interno (se configurado). O ID do usuário é um dado primário e a Singular não o compartilha com outras partes.
• O valor da ID de utilizador, quando definido com o método Singular SDK, persistirá até ser anulado utilizando o método logout() ou até que o armazenamento local do browser seja eliminado. Fechar ou atualizar o sítio Web não anula a definição do ID de utilizador.
• No modo privado/incógnito, o SDK não pode manter o ID de utilizador porque o browser elimina automaticamente o armazenamento local quando é fechado.

Para definir o ID de utilizador, utilize o método login(). Para o anular (por exemplo, se o Utilizador "sair" da conta), chame o método logout().

Se você já sabe a ID do usuário quando o Singular SDK é inicializado no site, defina a ID do usuário no objeto de configuração. Dessa forma, o Singular pode ter a ID de usuário desde a primeira sessão. No entanto, o ID de usuário normalmente não está disponível até que o usuário se registre ou faça um login. Nesse caso, chame login() após a conclusão do fluxo de registo. É recomendável enviar um evento de camada de dados quando um usuário executa um fluxo de autenticação que pode ser usado com um acionador de evento personalizado do GTM para disparar a função Login do Singular.

• Crie uma tag HTML personalizada para lidar com a autenticação
• Nomeie a tag como"Singular - Tag de autenticação"
• Insira o seguinte código na janela HTML

  <script>
  (function() {
    // Ensure sessionStorage is available
  
  
    if (typeof sessionStorage === 'undefined') {
      console.warn('sessionStorage is not supported in this environment.');
      return;
    }
  
    // Check if the event has already been triggered in this session
  
  
    if (sessionStorage.getItem('sng_login_triggered')) {
      console.log('Singular SDK event already triggered this session.');
      return; // Exit if the event was triggered before in this session
  
  
    }
  
    // Check if singularSdk is available and initialized
  
  
    if (window.singularSdk && typeof singularSdk.login === 'function' && typeof singularSdk.event === 'function') {
      
      // Dynamically fetch UserID if available (replace with actual method if applicable)
  
  
      var userID = window.userID || "User123456789"; // Example fallback value for userID
  
  
  
      try {
        // After Authentication, Pass the UserID as the Singular Custom User ID Value
  
  
        singularSdk.login(userID);
  
        // Send the Registration_Completed event (or similar event)
  
  
        singularSdk.event("sng_login");
  
        // Set a flag in sessionStorage to indicate that the event was triggered
  
  
        sessionStorage.setItem('sng_login_triggered', 'true');
  
        console.log('Singular SDK event triggered successfully.');
      } catch (error) {
        console.error('Error triggering Singular SDK event:', error);
      }
    } else {
      console.warn('Singular SDK is not loaded or required methods are unavailable.');
    }
  })();
  </script>
  

• Na secção Triggering, adicione um Firing Trigger para um evento personalizado.
• Nomeie o acionador:"singularAuthentication"
• Especifique o nome do evento do acionador correspondente ao nome do evento da camada de dados disponível após a autenticação de um utilizador no seu Web site.
• Salvar a tag