Singular Website SDK le permite atribuir las actividades del sitio web a los puntos de contacto de marketing y realizar un seguimiento de los eventos de usuario dentro de su sitio web. También es un componente clave en la solución de atribución entre dispositivos de Singular, que permite analizar los recorridos de los usuarios y calcular el LTV y el ROAS entre plataformas.

Para obtener más información, consulte nuestras preguntas frecuentes sobre atribución entre dispositivos y atribución web.

Requisitos previos

Antes de integrar Singular Website SDK, asegúrese de que se cumplen estos requisitos previos:

• Se ha configuradoGoogle Tag Manager en su sitio.
• Ha configurado los disparadores de Google Tag Manager según sea necesario para los eventos que desea enviar a Singular (su evento de conversión y cualquier evento personalizado).
• Ha configurado las variables de Google Tag Manager necesarias para los eventos que desea enviar a Singular. Por ejemplo, si desea enviar eventos de transacción e incluir los ingresos de la transacción, debe configurar variables para la suma de la transacción y la divisa.

Etiqueta 1 - Añadir la biblioteca SDK

La biblioteca JavaScript de Singular debe cargarse o inyectarse en el sitio antes de que se inicialice el SDK de Singular o se active cualquier función de Singular. Para garantizar esto, la biblioteca se inyectará utilizando la opción de etiqueta HTML personalizada en Google Tag Manager (GTM).

Para mantener una funcionalidad adecuada, la biblioteca debe incluirse en todas las páginas del sitio. Utilizaremos el activador Window Loaded (Ventana cargada) de GTM para controlar el momento de la inyección de la biblioteca y garantizar que se cargue después de que el contenido de la página se haya cargado por completo.

• Cree una etiqueta HTML personalizada para cargar la biblioteca SDK y agregar permiso para obtener datos de sugerencias del cliente.
• Nombre la etiqueta"Singular - SDK Loader".
• Inserte el siguiente código en la ventana 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>
  

• En Configuración avanzada, establezca la prioridad de disparo de la etiqueta en 99.
• En la sección Triggering, añada un Firing Trigger para"Window Loaded".
• Guarde la etiqueta

Etiqueta 2 - Etiqueta de Inicialización SDK

El código de inicialización de Singular SDK debe ejecutarse cada vez que se carga una página, pero sólo después de que se haya disparado la etiqueta Singular - SDK Loader. Para asegurar esto, utilizaremos el evento Data Layer creado por la etiqueta Singular - SDK Loader como disparador.

La inicialización de Singular SDK es un requisito previo para todas las funciones de atribución de Singular. Sirve para dos propósitos críticos:

• Crear una nueva sesión de usuario cuando un usuario entra en el sitio con nuevos datos publicitarios o cuando ha transcurrido el tiempo de espera de la sesión.
• Enviar un evento de "visita de página" a Singular.

Estos eventos de "visita de página" y sesiones de usuario son esenciales para calcular la retención de usuarios y permitir la atribución de reenganche.

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


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

Envío del ID de usuario a Singular (opcional)

Puede enviar su ID de usuario interno a Singular utilizando un método de Singular SDK.

• El ID de usuario puede ser cualquier identificador y no debe exponer PII (Personally Identifiable Information). Por ejemplo, no debe utilizar la dirección de correo electrónico, el nombre de usuario o el número de teléfono del usuario. Singular recomienda utilizar un valor hash único sólo para sus datos de origen.
• El valor de ID de usuario que se pasa a Singular también debe ser el mismo ID de usuario interno que se captura en todas las plataformas (Web/Móvil/PC/Consola/Offline).
• Singular incluirá el ID de usuario en las exportaciones a nivel de usuario, ETL y devoluciones internas de BI (si está configurado). El ID de usuario es un dato de origen y Singular no lo comparte con terceros.
• El valor del ID de usuario, cuando se establece con el método Singular SDK, persistirá hasta que se desactive utilizando el método logout() o hasta que se elimine el almacenamiento local del navegador. Cerrar o actualizar el sitio web no elimina el ID de usuario.
• En modo privado/incógnito, el SDK no puede mantener el ID de usuario porque el navegador borra automáticamente el almacenamiento local cuando se cierra.

Para establecer el ID de usuario, utilice el método login(). Para desestablecerlo (por ejemplo, si el Usuario "sale" de la cuenta), llame al método logout().

Si ya conoce el ID de usuario cuando se inicializa Singular SDK en el sitio web, establezca el ID de usuario en el objeto config. De esta forma, Singular puede tener el ID de usuario desde la primera sesión. Sin embargo, el ID de usuario no suele estar disponible hasta que el usuario se registra o realiza un inicio de sesión. En ese caso, llame a login() una vez finalizado el flujo de registro. Se recomienda enviar un evento de capa de datos cuando un usuario realiza un flujo de autenticación que se puede utilizar con un activador de eventos personalizados GTM para activar la función de inicio de sesión de Singular.

• Cree una etiqueta HTML personalizada para gestionar la autenticación
• Nombre la etiqueta"Singular - Etiqueta de autenticación".
• Inserte el siguiente código en la ventana 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>
  

• En la sección Activación, añada una activación de disparo para un evento personalizado.
• Nombre el Trigger"singularAutenticación"
• Especifique el nombre del evento de activación correspondiente al nombre del evento de la capa de datos disponible después de que un usuario se autentique en su sitio web.
• Guarde la etiqueta