Singular Website SDK es una función empresarial. Si está interesado en utilizar esta función, póngase en contacto con su Customer Success Manager.
El SDK de Singular Website le permite atribuir las actividades del sitio web a los puntos de contacto de marketing y realizar un seguimiento de los eventos de los usuarios 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 frecuentessobre atribución entre dispositivos y atribución web.
Además de la versión nativa de JavaScript descrita aquí, el SDK de Singular Website también está disponible como plantilla de Google Tag Manager.
Compatibilidad con navegadores:
Chrome: 15+ | Edge: 15+ | Internet Explorer: 10+ |
Safari 5.1+ | Firefox 6+ | Opera: 15+ |
Cómo añadir el script del SDK a su sitio web
Utilice uno de los siguientes métodos para configurar el SDK en su sitio web o aplicación web.
Enlace al script en la CDN de Singular
En este método, Singular aloja el código JavaScript del SDK en la CDN de Singular.
Añada el siguiente código dentro de la etiqueta <head> de cada página que desee rastrear:
<head>
<!-- Uso de la última versión del SDK -->
<script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js">
</script>
</head>
Nota: El código anterior enlaza con la última versión del SDK. Si desea utilizar una versión específica del SDK, utilice el siguiente código en su lugar:
<head>
<!-- Utilización de una versión fija del SDK -->
<script src="https://web-sdk-cdn.singular.net/singular-sdk/1.4.2/singular-sdk.js">
</script>
</head>
Configuración mediante NPM
- Ejecute npm i singular-sdk en el directorio raíz de su proyecto, o añada "singular-sdk": " ^1.4.1" a la sección de dependencias de su archivo package.json y, a continuación, ejecute npm install.
- Añade el siguiente código en los scripts que quieras que utilicen el SDK.
import {singularSdk, SingularConfig} from "singular-sdk";
Inicialización del SDK
El código de inicialización del SDK debe invocarse cada vez que se carga una página. Es un prerrequisito para toda la funcionalidad de atribución de Singular, y también:
- Crea una nueva sesión de usuario cuando un usuario entra en el sitio con nuevos datos publicitarios o cuando ha pasado el tiempo de espera de la sesión.
- Envía un nuevo evento de "visita de página" aSingular.
Los eventos de visitas a páginas y las sesiones de usuario se utilizan para calcular la retención de usuarios y permitir la atribución de reenganche.
1. Construcción del objeto SingularConfig
Antes de inicializar el SDK, debe crear un objeto SingularConfig. Este objeto contendrá
- SDK Key y SDK Secret: Para encontrarlos, inicie sesión en su cuenta de Singular y vaya a "Developer Tools > SDK Integration > SDK Keys".
- Su ID de producto: Un nombre para su sitio web. Recomendamos utilizar la notación DNS inversa de su dominio web principal, por ejemplo, "com.ejemplo". Se utilizará para identificar su sitio web en toda la plataforma Singular. Este valor también debe coincidir con el bundleID de la aplicación en la página de aplicaciones de la plataforma Singular.
- Opcionalmente, cualquier preferencia SDK que desee establecer (siga leyendo para más detalles).
Para crear un objeto SingularConfig básico, utilice este código:
const config = new SingularConfig(sdkKey, sdkSecret, productId);
Sin embargo, es probable que desee añadir ajustes para habilitar diversas capacidades ofrecidas por Singular.
Para ello, utilice los métodos ".with" del objeto SingularConfig. Por ejemplo
// Configure el SDK para pasar el ID de usuario a Singular
const config = new SingularConfig(sdkKey, sdkSecret, productId)
.withCustomUserId(userId);
Referencia de métodos SingularConfig
Estos son todos los métodos ".with" disponibles.
Método | Descripción | Más información |
.withCustomUserId(customId) | Enviar el ID de usuario a Singular | Establecer el ID de usuario |
.withProductName(productName) | Un nombre opcional para el producto | |
.withLogLevel(logLevel) | Configura el nivel de registro: 0 - Ninguno (por defecto); 1 - Advertencia; 2 - Información; 3 - Depuración. | |
.withSessionTimeoutInMinutes(timeout) | Configura el tiempo de espera de la sesión en minutos (por defecto: 30 minutos). |
|
.withAutoPersistentSingularDeviceId (domain) | Habilitar el seguimiento automático entre subdominios | Persistencia automática mediante cookies |
.withPersistentSingularDeviceId (singularDeviceId) |
Activar el seguimiento manual entre subdominios | Establecer manualmente el ID de dispositivo singular |
.withInitFinishedCallback(callback) | Invocar una función callback cuando finaliza la inicialización del SDK | Invocar una función callback cuando la inicialización ha finalizado |
2. Inicialización de Singular
Tras crear el objeto SingularConfig, inicialice Singular mediante el método init, pasándole el objeto config.
El método init puede invocarse en cualquier punto del código, pero debe invocarse antes de que se notifique cualquier evento. Se recomienda invocar init durante la carga de cada página de la que se desee realizar un seguimiento.
Método init | |
---|---|
Descripción | Inicializa el SDK con las opciones de configuración establecidas en el objeto SingularConfig. |
Firma | init(config) |
Ejemplo de uso |
|
Importante: Para aplicaciones de una sola página (SPA), llame a singularSdk.pageVisit() cada vez que se dirija a una página diferente. No llame a singularSdk. pageVisit () en la primera página que se carga, ya que singularSdk.init ya informa de una visita a una página.
Invocación de una función de devolución de llamada una vez finalizada la inicialización
Para establecer una función de devolución de llamada que se invocará una vez finalizada la inicialización, utilice . withInitFinishedCallback(callback) en el objeto SingularConfig.
Método withInitFinishedCallback | |
---|---|
Descripción | Establece la llamada de retorno que se invocará una vez finalizado el proceso de inicialización. |
Firma | withInitFinishedCallback(callback) |
Ejemplo de uso |
|
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.
Nota: Si utiliza la solución multidispositivo de Singular, debe recopilar el ID de usuario en todas las plataformas.
- 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 de un 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 "cierra sesión" en la cuenta), llame al método logout().
Nota: Si varios usuarios utilizan un único dispositivo, recomendamos implementar un flujo de cierre de sesión para establecer y desestablecer el ID de usuario para cada inicio y cierre de sesión.
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.
Método SingularSDK login() | |
---|---|
Descripción | Envía el ID de usuario a Singular. |
Firma | login(customUserId) |
Ejemplo de uso |
|
Método SingularSDK logout() | |
Descripción | Desconecta el ID de usuario que se ha enviado a Singular. |
Firma | cerrar sesión() |
Ejemplo de uso |
|
Importante: Esta función Enterprise avanzada sólo está disponible en casos excepcionales. Por favor, consulte con uno de los Ingenieros de Soluciones de Singular antes de implementarla.
Singular puede recibir datos adicionales de seguimiento de eventos móviles a través de una integración de servidor a servidor. Para utilizar esta función, debe asignar el ID de usuario al identificador de seguimiento de dispositivos móviles de Singular.
Nota: Llame a este método tan pronto como sea posible después de inicializar el SDK Singular o una vez que tenga el ID de usuario.
Método setDeviceCustomUserId de SingularSDK | |
---|---|
Descripción | Establece el Id. de usuario personalizado igual que el inicio de sesión y lo asigna al identificador de seguimiento de Singular. |
Firma | singularSdk.setDeviceCustomUserId(userId) |
Ejemplo de uso |
|
Opcional: Seguimiento de eventos e ingresos
Seguimiento de eventos (no ingresos)
Singular puede recopilar datos sobre los eventos de los usuarios dentro del sitio para ayudar a analizar el rendimiento de sus campañas y medir los KPI. Por ejemplo, es posible que su organización desee recopilar datos sobre inicios de sesión, registros o finalización de tutoriales por parte de los usuarios.
Puede enviar eventos a Singular utilizando el método de eventos.
Nota:
- Recomendamos encarecidamente pasar los nombres y atributos de los eventos en inglés para garantizar la compatibilidad con socios y soluciones de análisis de terceros si tiene previsto utilizarlos.
- Los nombres de eventos están limitados a 32 caracteres ASCII. Las cadenas en caracteres no ASCII deben tener menos de 32 bytes una vez convertidas a UTF-8.
- Los atributos y valores están limitados a 500 caracteres ASCII.
event Método | |
---|---|
Descripción | Notifica un evento de usuario a Singular con o sin información adicional. |
Firma |
singularSdk.event(eventName, args) Nota: 'args' es un objeto JavaScript con pares clave-valor. Si no desea pasar ningún argumento adicional, llame al método event sólo con el nombre del evento. |
Ejemplo de uso |
|
Seguimiento de ingresos
Singular puede recopilar datos sobre los ingresos obtenidos a través del sitio web para ayudar a analizar el rendimiento y el ROI de sus campañas. Singular pondrá los datos a su disposición en informes, exportaciones de registros y postbacks.
Utilice el método de ingresos para informar de los eventos. Ingresos le permite pasar un nombre de evento personalizado, de modo que podrá ver los ingresos en los informes de Singular desglosados por los diferentes tipos de eventos de ingresos.
Notas: Cualquier ingreso notificado en una divisa diferente se convertirá automáticamente a la divisa preferida de su organización, según lo establecido en su cuenta de Singular.
ingresos Método | |
---|---|
Descripción | Envía un evento de ingresos a Singular con información adicional opcional. |
Firma |
singularSdk.revenue(eventName, currency, amount, args) Nota:
|
Ejemplo de uso |
|
Opcional: Seguimiento entre subdominios
Por defecto, el SDK de Singular Website genera un identificador de dispositivo Singular y lo guarda utilizando el almacenamiento del navegador. Dado que este almacenamiento no puede compartirse entre subdominios, el SDK acaba generando un nuevo ID para cada subdominio.
Si desea mantener el ID de dispositivo singular en todos los subdominios, puede utilizar una de las siguientes opciones:
Método A: Autopersistencia mediante cookies
Puede hacer que Singular SDK mantenga el ID de dispositivo singular utilizando una cookie personalizada de origen. Utilice el siguiente método y establezca el dominio principal que desea rastrear.
Método withAutoPersistentSingularDeviceId | |
---|---|
Descripción | Inicializa el SDK con las opciones de configuración, incluido el dominio principal para la persistencia automática del Id. de dispositivo singular. |
Firma | withAutoPersistentSingularDeviceId(domain) |
Ejemplo de uso |
|
Método B (Avanzado): Establecimiento manual del Id. de dispositivo singular
Si no desea que Singular SDK persista el ID de dispositivo automáticamente, puede persistir el ID manualmente a través de dominios - por ejemplo, utilizando una cookie de dominio de nivel superior o una cookie del lado del servidor. El valor debe ser un ID generado previamente por Singular, en formato uuid4 válido.
Nota: Puede leer el ID del dispositivo Singular utilizando singularSdk.getSingularDeviceId() después de llamar al método init o utilizando InitFinishedCallback.
Método withPersistentSingularDeviceId | |
---|---|
Descripción |
Inicializa el SDK con las opciones de configuración, incluido el Id. de dispositivo singular que desea conservar. |
Firma | withPersistentSingularDeviceId(singularDeviceId) |
Ejemplo de uso |
|
Opcional: Obtener ID de coincidencia
Importante: Se trata de una función avanzada. Consulte con uno de los ingenieros de soluciones de Singular antes de implementarla.
Singular puede atribuir instalaciones de servidor a servidor desde plataformas de PC y consola basándose en un Match ID determinista y único por usuario. Para utilizar esta función, recupere el Match ID del Web SDK de Singular después de la inicialización.
Método getMatchID | |
---|---|
Descripción | Obtiene el identificador de coincidencia único para esta sesión web. |
Firma | singularSdk.getMatchID() |
Ejemplo de uso |
|