Web SDK - Resolución de problemas y buenas prácticas

Seguir
Avatar
Jared Ornstead
Updated
Documento

Visión general

Esta guía cubre problemas comunes de implementación, mejores prácticas y soluciones para ayudarle a evitar problemas de seguimiento y garantizar la exactitud de los datos.

Errores comunes de implementación

Error 1: Implementación duplicada (Nativo + GTM)

Problema: el error más común consiste en implementar simultáneamente el SDK de JavaScript nativo y el SDK de Google Tag Manager. Esto provoca que cada sesión y evento se rastree dos veces, inflando todas las métricas en un 200%.

¡IMPORTANTE! Singular no deduplica eventos automáticamente. El uso de ambos métodos de implementación duplicará todos sus datos.

Cómo identificar este problema:

  • Compruebe el código fuente de su sitio web para el script Singular SDK
  • Busque etiquetas de Singular en Google Tag Manager
  • En las herramientas de desarrollo del navegador, filtre las solicitudes de red por singular y cuente cuántas solicitudes se disparan al cargar la página (debería ser 1, no 2)

Solución:

  1. Decida qué método de implementación desea utilizar(se recomienda Native JS)
  2. Elimine completamente la otra implementación
  3. Realice pruebas para verificar que sólo se produce una solicitud por evento
  4. Controle sus datos durante 24-48 horas para asegurarse de que las métricas vuelven a la normalidad.

Error 2: Formato de ID de producto incorrecto

Problema: Uso de un formato incorrecto para su ID de producto. El ID de producto debe ser consistente para la Web App en todos los subdominios.

Errores comunes:

  • Utilizar una URL de sitio web: www.mycompany.com ❌
  • Uso de guiones: my-company-store ❌
  • Uso de DNS de reenvío: mycompany.com.store ❌
  • Uso de espacios: my company store ❌

Formato correcto (notación DNS inversa):

  • com.mycompany ✓

CONSEJO. Piensa en tu ID de producto como un identificador de paquete de aplicación móvil. Utiliza letras minúsculas, empieza por tu dominio en inverso y utiliza puntos para separar los componentes.

Cómo identificar este problema:

  • Compruebe las solicitudes de red en las herramientas para desarrolladores: busque errores 400 o 403.
  • Compruebe el parámetro i en la carga útil de la solicitud desde las herramientas de desarrollo del navegador.
  • Compruebe si hay errores en la consola del navegador

Solución:

  1. Obtenga el valor correcto de su página de Singular Apps (BundleId)
  2. Actualice su implementación con el formato correcto
  3. Pruebe y verifique los códigos de estado 200 en las solicitudes de red

Error 3: Los eventos se disparan varias veces

Problema: Los eventos se disparan varias veces debido a recargas de página, clics rápidos del usuario o falta de lógica de deduplicación. Esto infla los recuentos de eventos y los números de conversión.

Causas comunes:

  • El usuario hace clic en un botón varias veces rápidamente
  • El código de eventos se ejecuta en cada renderización de la página (aplicaciones React, Vue, Angular)
  • Envíos de formularios que no evitan el comportamiento predeterminado
  • Actualizaciones de página o navegación con el botón Atrás
  • Google Tag Manager dispara varias veces

IMPORTANTE A diferencia de algunas plataformas de análisis, Singular no deduplica eventos automáticamente. Es su responsabilidad implementar mecanismos de seguridad para evitar el seguimiento duplicado.

Estrategias de solución:

Revise las estrategias en las guías de implementación para más detalles. JS nativo, GTM

Error 4: SDK no se carga

Problema: El script de Singular SDK no se carga, lo que impide cualquier seguimiento.

Causas comunes:

  • Script bloqueado por bloqueadores de anuncios (afecta principalmente a GTM)
  • Restricciones de la política de seguridad de contenidos (CSP)
  • Script colocado en una ubicación incorrecta de la página
  • Errores de sintaxis en el código de implementación
  • Problemas de conectividad de red

Cómo diagnosticar:

  1. Abra la pestaña Consola de las herramientas de desarrollo del navegador
  2. Busque errores que mencionen "singular" o "sdk".
  3. Escriba typeof singularSdk en la consola: debería devolver "function", no "undefined".
  4. Comprueba en la pestaña Red si se han producido errores en la carga de scripts.
  5. Desactiva los bloqueadores de anuncios y vuelve a probar

Solución:

  • Bloqueadores de anuncios: Cambie a la implementación nativa de JavaScript (es menos probable que se bloquee).
  • Problemas de CSP: Añada dominios singulares a su política de seguridad de contenidos.
  • Ubicación del script: Asegúrese de que el script SDK está en la etiqueta <head>
  • Errores de sintaxis: Valide su código JavaScript

Configuración de la política de seguridad de contenidos

Si su sitio web utiliza cabeceras CSP, añada estas directivas:

Content-Security-Policy: 
  script-src 'self' https://web-sdk-v1.singular.net;
  connect-src 'self' https://sdk-api-v1.singular.net;

Mejores prácticas

Gestión de ID de producto

  • Utilice un ID de producto por sitio web o aplicación web
  • Mantenga los ID de producto coherentes en todas las páginas y subdominios.
  • Documente sus ID de producto en la base de conocimientos de su equipo.
  • Utilice identificadores de producto distintos para los entornos de desarrollo, preparación y producción.

Convenciones de nomenclatura de eventos

Buenas prácticas de nomenclatura:

  • Utilice nombres claros y descriptivos: Purchase Signup_Completed , Video_Play
  • Utilice mayúsculas y minúsculas de forma coherente (recomiende Title_Case)
  • Utilice guiones bajos en lugar de espacios
  • Los nombres deben tener menos de 32 caracteres
  • Evite caracteres especiales y emojis

Malos ejemplos:

  • Purchase!!!🎉 (caracteres especiales y emojis)
  • user clicked the purchase button on the checkout page (demasiado largo, espacios)
  • evt_123 (no descriptivo)

CONSEJO Cree un documento de nomenclatura de eventos compartido por los equipos de marketing, producto e ingeniería para mantener la coherencia.

Mejores prácticas para los parámetros de eventos

  • Ingresos: Enviar siempre como un número, no como una cadena: revenue: 49.99 no revenue: "$49.99"
  • Divisa: Utilice códigos de moneda ISO de 3 letras: USD, EUR, GBP
  • IDs: Enviar como cadenas aunque sean numéricos: product_id: "12345"
  • Nombres de parámetros: Utilizar snake_case por coherencia
  • Valores: Mantenga los valores de cadena por debajo de 100 caracteres

Estrategia de pruebas

Siga esta lista de comprobación antes del lanzamiento:

Tabla

Prueba Cómo verificar Resultado esperado
El SDK se carga Consola: typeof singularSdk Devuelve "function"
Init/PageVisit rastreado Ficha Red: Filtro "__PAGE_VISIT__" 1 petición al cargar la página con estado 200
Eventos disparados Activar evento, comprobar pestaña Red, validar nombre de evento (parámetro "n") en carga útil. Nueva solicitud por evento con estado 200
ID de producto correcto Compruebe la carga útil de la solicitud, valide el nombre del evento (parámetro "i") en la carga útil. Formato DNS inverso
Sin duplicados Activar el mismo evento 3 veces rápidamente Sólo se envía 1 solicitud
Seguimiento de ingresos Comprobar la carga útil del evento de compra Los ingresos aparecen como un número
Múltiples páginas Navegar a diferentes páginas El seguimiento funciona en todas las páginas
Dispositivos móviles Prueba en navegadores iOS y Android El seguimiento funciona en móviles

Optimización del rendimiento

  • Coloque el script SDK en la etiqueta <head> para una carga temprana
  • Minimizar el número de eventos rastreados por página (centrarse en acciones significativas, eventos de marketing)
  • Evite el seguimiento de cada pulsación de tecla (utilice debouncing)

Privacidad y cumplimiento

Divulgación de cookies

Si activa el seguimiento de subdominios cruzados en su configuración, Singular establece una cookie de origen. Debe informar de ello en su política de privacidad.

Lenguaje recomendado para la política de privacidad:

Utilizamos cookies para rastrear el comportamiento del usuario y mejorar su experiencia en el sitio web. En concreto, utilizamos las siguientes cookies:

singular_device_id - Esta cookie asigna un ID único a los usuarios que visitan nuestro sitio web. Este ID nos ayuda a rastrear las actividades e interacciones del usuario durante su visita sin recopilar información personal. Nos permite diferenciar entre usuarios y monitorizar el comportamiento de los visitantes en diferentes sesiones.

  • Duración: 1 año
  • Tipo de cookie Cookie de origen
  • Proveedor: Singular (https://www.singular.net/privacy-policy/)

Cumplimiento del GDPR y privacidad

Para el cumplimiento de GDPR:

  • Establecer persistentIdentifier: false por defecto
  • Habilite las cookies sólo con el consentimiento del usuario
  • Ofrezca a los usuarios la posibilidad de rechazar el seguimiento
  • Incluya Singular en su banner de consentimiento de cookies

Herramientas y técnicas de depuración

Herramientas de desarrollo del navegador

Comandos de consola para depuración:

// Check if SDK is loaded
typeof singularSdk
// Should return: "function"

// Test firing an event manually
window.singularSdk.event("test");

Lista de comprobación de la migración

Si se traslada desde otra plataforma de análisis o actualiza su implementación:

  1. Audite la implementación actual
    • Documente todos los eventos actualmente rastreados
    • Identifique todas las páginas con código de seguimiento
    • Anote cualquier parámetro personalizado o ID de usuario
  2. Planificar la nueva implementación
    • Asignar nombres de eventos antiguos a la nueva convención de nomenclatura
    • Decidir entre Native JS y GTM
    • Crear un plan de pruebas
  3. Implementación por etapas
    • Empezar con un entorno de pruebas
    • Pruebas exhaustivas (mínimo 1 semana)
    • Despliegue en producción durante un periodo de poco tráfico
    • Funcione en paralelo con el sistema antiguo durante 1-2 semanas
  4. Validar los datos
    • Compare las métricas entre los sistemas antiguo y nuevo
    • Comprobación de duplicados de seguimiento
    • Verificar que todos los eventos se disparan correctamente
    • Seguimiento durante 2-4 semanas
  5. Retire el sistema antiguo
    • Eliminar el código de seguimiento antiguo
    • Actualizar la documentación
    • Formar al equipo en el nuevo sistema

Obtener ayuda

Si se encuentra con problemas no cubiertos en esta guía:

  • Póngase en contacto con su Customer Success Manager de Singular.
  • Envíe un ticket de soporte a través del panel de control de Singular.
  • Incluya los registros de la consola del navegador y capturas de pantalla de la solicitud de red.
  • Proporcione la URL de su sitio web y los pasos detallados para reproducir cualquier problema.

Artículos relacionados