Descripción general

Esta guía explica cómo implementar el SDK web de Singular utilizando Google Tag Manager (GTM). Este método es ideal para equipos que no tienen acceso directo al código del sitio web o que desean gestionar el seguimiento a través de GTM.

Requisitos previos

Antes de empezar, asegúrese de que dispone de:

• Clave SDK y secreto SDK: 
  • Dónde encontrarlos: Inicie sesión en su cuenta de Singular y vaya a Herramientas para desarrolladores > Integración del SDK > Claves del SDK.
• ID del producto:
  • Qué es: un nombre único para su sitio web, idealmente utilizando el formato DNS inverso (por ejemplo, com.website-name).
  • Por qué es importante: este ID asocia el sitio web como una aplicación en Singular y debe coincidir con el ID del paquete de la aplicación web que aparece en su página de aplicaciones en Singular. 
• Google Tag Managerse ha configurado en tu sitio.
• Permiso en GTM para editar las etiquetas, los activadores y las variables de tu sitio web. Dependiendo de la personalización, es posible que necesites saber cómo crear etiquetas personalizadas y configurar la secuencia de etiquetas. 
• Si no tiene permiso para publicar cambios en Google Tag Manager, deberá pedirle a alguien que publique los cambios después de la prueba.
• Conocimientos sobre cómo previsualizar y depurar contenedores y etiquetas en GTM. 
• Una lista de los eventos que desea rastrear. Consulte nuestra lista completa de eventos estándar de Singular y los eventos recomendados por sector para obtener ideas.

Pasos de implementación

Paso 1: Añada las plantillas de seguimiento web de Singular a su contenedor GTM

1. Inicie sesión en su cuenta de Google Tag Manager y seleccione el contenedor de su sitio web.
2. Vaya a Etiquetas > Nuevo.
3. Asigne un nombre a la etiqueta: «Etiqueta de inicio de Singular».
4. Haga clic en el cuadro Configuración de etiqueta para comenzar la configuración de la etiqueta.
5. Elija Tipo de etiqueta: y seleccione «Descubra más tipos de etiquetas en la galería de plantillas de la comunidad».
6. Busque «Singular» y seleccione «Singular Web Tracking». Haga clic en el botón «Añadir al espacio de trabajo».

Paso 2: Inicializar el SDK

1. Rellene los campos del formulario con lo siguiente:
   • Establezca el tipo de seguimiento en Inicialización
   • Introduzca su clave SDK real en el campo «Clave API»
   • Introduce tu SDK Secret real en el campo Secret .

   • Introduzca su ID de producto real. Debe tener el siguiente aspecto : com.website-name y debe coincidir con el valor BundleID de la página Apps de la plataforma Singular.

     ¡CONSEJO! Utilice un ID de producto específico para las pruebas com.website-name.dev y actualícelo antes de enviarlo a producción. De este modo, todos sus datos de prueba se mantendrán separados de la aplicación de producción en los informes de Singular.

   • Opcional:
     • Nivel de registro: la configuración del registro de depuración del SDK en la consola. El valor predeterminado es ninguno.
     • Deduplicación de eventos
     • Configuración de propiedades globales
     • Habilitar banners inteligentes (solo para empresas)
     • Configuración del ID de usuario del cliente
     • Tiempo de espera de la sesión: tiempo que el usuario debe permanecer inactivo antes de que el SDK cree una nueva sesión. Singular envía las sesiones de los usuarios para calcular la retención de usuarios y habilitar la atribución de reenganche. El valor predeterminado es 30 minutos.
     • Seguimiento entre subdominios
2. Seleccione Activación para configurar un activador que haga que esta etiqueta funcione.
3. Seleccione Nuevo y asigne un nombre al activador: «Singular Init Trigger».
4. Haga clic en «Configuración del activador » y seleccione«Vista de página - Ventana cargada» y haga clic en«Guardar».
5. Haga clic en«Guardar» de nuevo para guardar la etiqueta.
6. Haga clic en«Vista previa» en la página Etiqueta y compruebe que la etiqueta de inicialización de Singular se activa.
   
   

Paso 3: Seguimiento de eventos

Después de inicializar el SDK, puede rastrear eventos personalizados cuando los usuarios realizan acciones importantes en su sitio web.

Basic EventConversion EventRevenue Event

Seguimiento básico de eventos

Realice un seguimiento de un evento simple o añada atributos personalizados utilizando JSON válido para proporcionar más contexto sobre el evento:

1. Cree una nueva etiqueta para su evento personalizado utilizando la plantilla de seguimiento web de Singular. .

2. Asigne un nombre a la etiqueta del evento.

3. Elija Tipo de seguimiento = Evento personalizado

4. Ajuste el campo «Nombre del evento» o establezca la variable adecuada.

5. Ajuste el campo «ID de usuario personalizado» o establezca la variable adecuada .

6. Ajuste los «Atributos» si lo desea para pasar pares clave/valor en el evento.

7. Configure un activador adecuado para disparar la etiqueta solo cuando sea necesario.

8. Guarde el activador y la etiqueta, y pruébelos en la vista previa.

Seguimiento de eventos de conversión

Realice un seguimiento de un evento de conversión:

1. Cree una nueva etiqueta para su evento personalizado utilizando la plantilla de seguimiento web de Singular. Web Tracking.

2. Asigne un nombre a la etiqueta del evento de conversión.

3. Elija Tipo de seguimiento = Evento de conversión

4. Ajuste el campo «Nombre del evento» o establezca la variable adecuada.

5. Ajuste el campo «ID de usuario personalizado» o establezca la variable adecuada .

6. Ajuste los «Atributos» si lo desea para pasar pares clave/valor en el evento.

7. Configure un activador adecuado para disparar la etiqueta solo cuando sea necesario.

8. Guarde el activador y la etiqueta, y pruébelos en la vista previa.

Seguimiento de eventos de ingresos

Realice un seguimiento de los eventos de conversión con información sobre ingresos y añada atributos opcionales para obtener más contexto:

1. Cree una nueva etiqueta para su evento personalizado utilizando la plantilla de seguimiento web de Singular. Web Tracking.

2. Asigne un nombre a la etiqueta de evento de ingresos.

3. Elija Tipo de seguimiento = Evento de ingresos

4. Ajuste el campo «Nombre del evento» o establezca la variable adecuada.

5. Ajuste el campo «ID de usuario personalizado» o establezca la variable adecuada .

6. Ajuste el campo «Moneda» o establezca la variable adecuada. Pase la moneda de los ingresos como un código de moneda ISO 4217 de tres letras, como «USD», «EUR» o «INR».

7. Ajuste el campo «Ingresos» o establezca la variable adecuada. Los ingresos deben representarse en la moneda indicada.

8. Ajuste los «Atributos» si lo desea para pasar pares clave/valor en el evento.

9. Configure un desencadenador adecuado para activar la etiqueta solo cuando sea necesario.

10. Guarde el desencadenador y la etiqueta, y pruébelos en la vista previa.

Patrones comunes de implementación de eventos

Paso 4: Configuración del ID de usuario del cliente

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

Siempre que el usuario realice acciones en su sitio web sin haber iniciado sesión , los eventos se envían a Singular con un ID de usuario generado por Singular. Pero después de que el usuario se registre o inicie sesión, puede enviar eventos a Singular junto con el ID de usuario que se utiliza en su sitio web, por ejemplo, una dirección de correo electrónico con hash.

Singular utiliza el ID de usuario en las exportaciones de datos a nivel de usuario (consulte Exportación de registros de atribución) , así como en los postbacks de BI internos, si los tiene configurados (consulte Configuración de postbacks de BI internos).

Hay dos formas de enviar el ID de usuario a Singular:

• Recomendado: si conoce el ID de usuario cuando se abre el sitio web , establezca el ID de usuario en el tipo de seguimiento Inicialización al inicializar el SDK. Esto hace que el ID de usuario esté disponible para Singular desde la primera visita a la página.
• Alternativamente, puede activar una etiqueta con el tipo de seguimiento = Inicio de sesión en cualquier momento, normalmente después de que se produzca una autenticación . Recomendamos llamarla tan pronto como el ID de usuario esté disponible. Nota: llamar a esta etiqueta no activa un evento. ¡Solo establece el ID de usuario para que se añada a cualquier activador de eventos en el futuro!

Para establecer el ID de usuario con Singular, añada una etiqueta Singular con el tipo de seguimiento «Inicio de sesión»:

1. En su cuenta de Google Tag Manager, haga clic en Etiquetas > Nuevo.
2. En la ventana Configuración de etiquetas, haga clic en Configuración de etiquetas y, en el menú Tipo de etiqueta , seleccione «Seguimiento web de Singular».
3. En Tipo de seguimiento, seleccione «Inicio de sesión».
4. En ID de usuario personalizado, introduzca la variable de Google Tag Manager que contiene el ID de usuario.
5. Haga clic en Activación y añada el evento de activación: inicio de sesión o registro del usuario.
6. Haga clic en Guardar.

Para desactivar el ID de usuario, añada una etiqueta con el tipo de seguimiento «Cierre de sesión »:

1. En su cuenta de Google Tag Manager, haga clic en Etiquetas > Nuevo.
2. En la ventana Configuración de etiquetas, haga clic en Configuración de etiquetas y, en el menú Tipo de etiqueta , seleccione «Seguimiento web singular».
3. En Tipo de seguimiento, seleccione «Cierre de sesión».
4. Haga clic en Activación y añada el evento de activación: cierre de sesión del usuario.
5. Haga clic en Guardar.

Paso 5: Desduplicación de eventos (opcional)

Deduplicación de eventos en Google Tag Manager

Por qué se producen duplicados en GTM

GTM puede evaluar y activar etiquetas varias veces para la misma acción del usuario (por ejemplo, condiciones de activación repetidas o múltiples detectores de eventos), lo que puede dar lugar a duplicados en las exportaciones de eventos de Singular.

Método de deduplicación de GTM (recomendado)

Deduplicación de eventos del SDK de Singular: habilite la deduplicación en la plantilla GTM del SDK web de Singular para eliminar los eventos duplicados que coincidan con los mismos parámetros de deduplicación dentro de un intervalo de tiempo configurable.

Pasos de implementación

Habilitar la deduplicación de eventos: en la etiqueta/plantilla de inicialización del SDK web de Singular , habilite la opción de deduplicación de eventos.

Establecer el intervalo de tiempo (opcional): Configure el intervalo de tiempo máximo (en milisegundos) que se utiliza para considerar que dos eventos son duplicados (por defecto: 1000 ms / 1 segundo).

Cómo funciona la deduplicación

Cuando está habilitada, el SDK suprime los eventos (excepto las visitas a la página) cuando el mismo evento se repite dentro del intervalo de tiempo utilizando un hash de estos parámetros: EventName , EventProductName, IsRevenueEvent , CustomUserId, GlobalProperties , MatchId y WebUrl (además de la carga útil «extra» del evento, como los ingresos y los argumentos personalizados).

Paso 6: Prueba de la implementación de GTM

1. Abra el modo de vista previa de GTM y cargue su sitio web.
2. Compruebe que:

• El SDK se carga (solicitud de red a singular-sdk.js)
• Los eventos se activan según lo esperado y solo una vez por acción
• No hay errores en la consola del navegador relacionados con singular
• Las solicitudes de red se envían a sdk-api-v1.singular.net

3. Utilice la pestaña Red en las herramientas de desarrollo del navegador para verificar que se envía la carga útil correcta

Paso 7: Implementar el reenvío de Web a aplicación

Reenvío de atribución de web a aplicación

Utilice el SDK web de Singular para realizar un seguimiento de los recorridos de los usuarios desde su sitio web hasta su aplicación móvil , lo que permite una atribución precisa de las campañas web a las instalaciones de aplicaciones móviles y las reactivaciones. Siga estos pasos para configurar el reenvío de web a aplicación, incluida la compatibilidad con códigos QR para usuarios de escritorio.

1. Siga nuestra Guía de reenvío de atribución de sitio web a aplicación móvil para configurar el SDK web de Singular para la atribución web móvil.
2. Para el seguimiento de la web móvil a la aplicación:
   • Añada la etiqueta «Abrir aplicación » y configure el disparador en el botón para abrir o instalar su aplicación.

     1. Al configurar la etiqueta Abrir aplicación, especifique su enlace base de la web móvil a la aplicación desde la página Administrar enlaces de Singular.

        

3. Para el seguimiento de Web a aplicación en ordenadores de sobremesa:
   • Cree una etiqueta de limpieza del generador de códigos QR
     1. Vaya a Etiquetas > Nuevo en GTM y seleccione HTML personalizado.
     2. Añada el código a:
        • Inyecte la biblioteca QRCode que elija
        • Recuperar el enlace web a aplicación desde window.singularSdk.buildWebToAppLink(baselink);
        • Genere el código QR a partir del enlace devuelto.
        • Actualice la imagen del código QR en la página.
     3. Asigne un nombre a la etiqueta: «Singular - Generador de códigos QR (Limpieza)».
     4. No se necesita ningún activador: las etiquetas de limpieza heredan los activadores de la etiqueta principal
     5. Configure su etiqueta Singular Init:
        • Haga clic en Configuración de etiquetas
        • Vaya a Configuración avanzada > Secuenciación de etiquetas
        • Marque «Activar una etiqueta de limpieza después de que se active [Etiqueta Singular Init]»
        • Seleccione su etiqueta Generador de códigos QR en el menú desplegable
        • Guarde la etiqueta y pruébela en modo Vista previa.

Temas avanzados

Banners de Singular

Añadir propiedades globales

Track Type: setGlobalProperties
propertyKey: user_type
value: premium

Track Type: getGlobalProperties

Track Type: unsetGlobalProperty
propertyKey: user_type

Track Type: clearGlobalProperties

Seguimiento de búsquedas orgánicas

<script>
(function() {
    // singular-web-organic-search-tracking: setupOrganicSearchTracking.js
    // Tracks organic search referrals by appending wpsrc and wpcn to the URL if no campaign parameters exist and the referrer is a search engine.

    // Configuration for debugging (set to true to enable logs)
    var debug = true;

    // List of campaign parameters to check for exclusion
    var campaignParams = [
        'gclid', 'fbclid', 'ttclid', 'msclkid', 'twclid', 'li_fat_id',
        'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'wpsrc'
    ];

    // Whitelist of legitimate search engine domains (prevents false positives)
    var legitimateSearchEngines = new Set([
        // Google domains
        'google.com', 'google.co.uk', 'google.ca', 'google.com.au', 'google.de', 
        'google.fr', 'google.it', 'google.es', 'google.co.jp', 'google.co.kr',
        'google.com.br', 'google.com.mx', 'google.co.in', 'google.ru', 'google.com.sg',
        
        // Bing domains  
        'bing.com', 'bing.co.uk', 'bing.ca', 'bing.com.au', 'bing.de',
        
        // Yahoo domains
        'yahoo.com', 'yahoo.co.uk', 'yahoo.ca', 'yahoo.com.au', 'yahoo.de',
        'yahoo.fr', 'yahoo.it', 'yahoo.es', 'yahoo.co.jp',
        
        // Other search engines
        'baidu.com', 'duckduckgo.com', 'yandex.com', 'yandex.ru',
        'ask.com', 'aol.com', 'ecosia.org', 'startpage.com', 
        'qwant.com', 'seznam.cz', 'naver.com', 'daum.net'
    ]);

    // Extract main domain from hostname (removes subdomains)
    function getMainDomain(hostname) {
        if (!hostname) return '';
        
        var lowerHost = hostname.toLowerCase();
        
        // Handle special cases for known search engines with country codes
        var searchEnginePatterns = {
            'google': function(host) {
                // Match google.TLD patterns more precisely
                if (host.indexOf('google.co.') !== -1 || host.indexOf('google.com') !== -1) {
                    var parts = host.split('.');
                    for (var i = 0; i < parts.length - 1; i++) {
                        if (parts[i] === 'google') {
                            return parts.slice(i).join('.');
                        }
                    }
                }
                return null;
            },
            'bing': function(host) {
                if (host.indexOf('bing.co') !== -1 || host.indexOf('bing.com') !== -1) {
                    var parts = host.split('.');
                    for (var i = 0; i < parts.length - 1; i++) {
                        if (parts[i] === 'bing') {
                            return parts.slice(i).join('.');
                        }
                    }
                }
                return null;
            },
            'yahoo': function(host) {
                if (host.indexOf('yahoo.co') !== -1 || host.indexOf('yahoo.com') !== -1) {
                    var parts = host.split('.');
                    for (var i = 0; i < parts.length - 1; i++) {
                        if (parts[i] === 'yahoo') {
                            return parts.slice(i).join('.');
                        }
                    }
                }
                return null;
            }
        };
        
        // Try specific patterns for major search engines
        for (var engine in searchEnginePatterns) {
            if (lowerHost.indexOf(engine) !== -1) {
                var result = searchEnginePatterns[engine](lowerHost);
                if (result) return result;
            }
        }
        
        // Handle other known engines with simple mapping
        var otherEngines = {
            'baidu.com': 'baidu.com',
            'duckduckgo.com': 'duckduckgo.com', 
            'yandex.ru': 'yandex.ru',
            'yandex.com': 'yandex.com',
            'ask.com': 'ask.com',
            'aol.com': 'aol.com',
            'ecosia.org': 'ecosia.org',
            'startpage.com': 'startpage.com',
            'qwant.com': 'qwant.com',
            'seznam.cz': 'seznam.cz',
            'naver.com': 'naver.com',
            'daum.net': 'daum.net'
        };
        
        for (var domain in otherEngines) {
            if (lowerHost.indexOf(domain) !== -1) {
                return otherEngines[domain];
            }
        }
        
        // Fallback: Extract main domain by taking last 2 parts (for unknown domains)
        var parts = hostname.split('.');
        if (parts.length >= 2) {
            return parts[parts.length - 2] + '.' + parts[parts.length - 1];
        }
        
        return hostname;
    }

    // Get query parameter by name, using URL.searchParams with regex fallback for IE11
    function getParameterByName(name, url) {
        if (!url) url = window.location.href;
        try {
            return new URL(url).searchParams.get(name) || null;
        } catch (e) {
            if (debug) console.warn('URL API not supported, falling back to regex:', e);
            name = name.replace(/[\[\]]/g, '\\$&');
            var regex = new RegExp('[?&]' + name + '(=([^&#]*)|&|#|$)');
            var results = regex.exec(url);
            if (!results) return null;
            if (!results[2]) return '';
            return decodeURIComponent(results[2].replace(/\+/g, ' '));
        }
    }

    // Check if any campaign parameters exist in the URL
    function hasAnyParameter(url, params) {
        for (var i = 0; i < params.length; i++) {
            if (getParameterByName(params[i], url) !== null) {
                return true;
            }
        }
        return false;
    }

    // Improved search engine detection - only checks hostname, uses whitelist
    function isSearchEngineReferrer(referrer) {
        if (!referrer) return false;
        
        var hostname = '';
        try {
            hostname = new URL(referrer).hostname.toLowerCase();
        } catch (e) {
            // Fallback regex for hostname extraction (IE11 compatibility)
            var match = referrer.match(/^(?:https?:\/\/)?([^\/\?#]+)/i);
            hostname = match ? match[1].toLowerCase() : '';
        }
        
        if (!hostname) return false;
        
        // First check: exact match against whitelist
        if (legitimateSearchEngines.has(hostname)) {
            if (debug) console.log('Exact match found for:', hostname);
            return true;
        }
        
        // Second check: subdomain of legitimate search engine
        var hostParts = hostname.split('.');
        if (hostParts.length >= 3) {
            // Try domain.tld combination (e.g., google.com from www.google.com)
            var mainDomain = hostParts[hostParts.length - 2] + '.' + hostParts[hostParts.length - 1];
            if (legitimateSearchEngines.has(mainDomain)) {
                if (debug) console.log('Subdomain match found for:', hostname, '-> main domain:', mainDomain);
                return true;
            }
            
            // Try last 3 parts for country codes (e.g., google.co.uk from www.google.co.uk)
            if (hostParts.length >= 3) {
                var ccDomain = hostParts[hostParts.length - 3] + '.' + hostParts[hostParts.length - 2] + '.' + hostParts[hostParts.length - 1];
                if (legitimateSearchEngines.has(ccDomain)) {
                    if (debug) console.log('Country code domain match found for:', hostname, '-> cc domain:', ccDomain);
                    return true;
                }
            }
        }
        
        if (debug) {
            console.log('Hostname not recognized as legitimate search engine:', hostname);
        }
        
        return false;
    }

    // Main function to update URL with organic search tracking parameters
    function setupOrganicSearchTracking() {
        var url = window.location.href;
        var referrer = document.referrer || '';

        // Store URL and referrer in localStorage
        try {
            localStorage.setItem('sng_url', url);
            localStorage.setItem('sng_ref', referrer);
        } catch (e) {
            if (debug) console.warn('localStorage not available:', e);
        }

        if (debug) {
            console.log('Current URL:', url);
            console.log('Referrer:', referrer);
        }

        // Skip if campaign parameters exist or referrer is not a search engine
        var hasCampaignParams = hasAnyParameter(url, campaignParams);
        if (hasCampaignParams || !isSearchEngineReferrer(referrer)) {
            if (debug) console.log('Skipping URL update: Campaign params exist or referrer is not a legitimate search engine');
            return;
        }

        // Extract and validate referrer hostname
        var referrerHostname = '';
        try {
            referrerHostname = new URL(referrer).hostname;
        } catch (e) {
            if (debug) console.warn('Invalid referrer URL, falling back to regex:', e);
            var match = referrer.match(/^(?:https?:\/\/)?([^\/]+)/i);
            referrerHostname = match ? match[1] : '';
        }

        // Extract main domain from hostname
        var mainDomain = getMainDomain(referrerHostname);
        
        if (debug) {
            console.log('Full hostname:', referrerHostname);
            console.log('Main domain:', mainDomain);
        }

        // Only proceed if main domain is valid and contains safe characters
        if (!mainDomain || !/^[a-zA-Z0-9.-]+$/.test(mainDomain)) {
            if (debug) console.log('Skipping URL update: Invalid or unsafe main domain');
            return;
        }

        // Update URL with wpsrc and wpcn parameters
        var urlObj;
        try {
            urlObj = new URL(url);
        } catch (e) {
            if (debug) console.warn('URL API not supported, cannot modify URL:', e);
            return;
        }
        
        // Set wpsrc to the main domain (e.g., google.com instead of tagassistant.google.com)
        urlObj.searchParams.set('wpsrc', mainDomain);
        
        // Set wpcn to 'Organic Search' to identify the campaign type
        urlObj.searchParams.set('wpcn', 'Organic Search');

        // Update the URL without reloading (check if history API is available)
        if (window.history && window.history.replaceState) {
            try {
                window.history.replaceState({}, '', urlObj.toString());
                if (debug) console.log('Updated URL with organic search tracking:', urlObj.toString());
            } catch (e) {
                if (debug) console.warn('Failed to update URL:', e);
            }
        } else {
            if (debug) console.warn('History API not supported, cannot update URL');
        }
    }

    // Execute the function
    setupOrganicSearchTracking();
})();
</script>

Seguimiento entre subdominios

De forma predeterminada, el SDK del sitio web de Singular genera un ID de dispositivo Singular y lo mantiene utilizando el almacenamiento del navegador. Dado que este almacenamiento no se puede compartir entre subdominios, el SDK termina generando un nuevo ID para cada subdominio.

Si desea conservar el ID de dispositivo Singular en todos los subdominios, puede utilizar una de las siguientes opciones:

Problemas comunes de implementación de GTM

Prácticas recomendadas

• Mantenga GTM organizado: nombre las etiquetas y los activadores de forma clara y documente su finalidad.
• Audite regularmente las etiquetas no utilizadas o heredadas.
• Minimice el número de activadores para reducir el riesgo de eventos duplicados.
• Después de los cambios, siempre prueba a fondo en el modo de vista previa de GTM antes de ponerlo en vivo.
• Si utiliza el seguimiento basado en cookies (seguimiento entre subdominios), actualice su política de privacidad en consecuencia.

Artículos relacionados

• Guía de implementación de JavaScript nativo
• Guía de implementación de Google Tag Manager
• Solución de problemas y prácticas recomendadas
• Preguntas frecuentes sobre atribución web