Saltar al contenido principal
Esta guía te muestra cómo cargar e inicializar el SDK Web de OneSignal usando Google Tag Manager (GTM) y, opcionalmente, establecer el External ID y las etiquetas de OneSignal después de la inicialización.

Requisitos previos

  • Un sitio que soporte HTTPS.
  • Puedes publicar cambios en GTM para el contenedor del sitio.
  • Has completado el flujo de configuración del SDK Web de OneSignal hasta Añadir código al sitio. Esto te proporciona:

Configuración

1. Configura tu aplicación web de OneSignal

Sigue la configuración del SDK Web hasta llegar al paso Añadir código al sitio. Aquí es donde obtendrás el OneSignal App ID.
Paso Añadir código al sitio en el panel de configuración del SDK Web de OneSignal

Una vez que llegues a este paso, necesitarás hacer algunos ajustes al código para que funcione con Google Tag Manager.

Debes subir el archivo OneSignal Service Worker directamente a tu servidor. Consulta OneSignal Service Worker.

2. Crea variables de GTM

Crea variables de GTM para los valores que referencias en las etiquetas. Esto evita codificar valores de forma fija y hace que tu configuración sea más fácil de mantener. Crea una variable ONESIGNAL_APP_ID
  1. En GTM, ve a Variables > New.
  2. Elige Constant.
  3. Nómbrala ONESIGNAL_APP_ID
  4. Establece el valor como tu OneSignal App ID.
  5. Guarda
Creando una variable de OneSignal App ID en Google Tag Manager

Creando una variable de OneSignal App ID

Ahora puedes referenciar tu App ID en cualquier lugar de GTM usando {{ ONESIGNAL_APP_ID }}.
Crea una variable ONESIGNAL_EXTERNAL_ID (Recomendado) Usa esta variable si asocias usuarios con un identificador externo (por ejemplo, un ID de usuario de tu base de datos o sistema de autenticación). Elige el tipo de variable según cómo esté disponible el valor en tu sitio. Opciones comunes:
  • Data Layer Variable (recomendado)
  • First-Party Cookie
  • DOM Variable (avanzado)

3. Crea la etiqueta de inicialización de OneSignal

  1. En GTM, ve a Tags > New
  2. Nombra la etiqueta: OneSignal - Init
  3. Tag Type: Custom HTML
  4. Pega el código a continuación.
  5. En Advanced Settings > Tag firing options, establece Once per page.
  6. En Triggering, selecciona Initialization - All Pages.
HTML
Configurando la etiqueta OneSignal - Init en Google Tag Manager

Configurando la etiqueta OneSignal - Init

Si usas un banner de consentimiento / CMP, consulta las opciones de Consent Mode y consideraciones de privacidad a continuación.

4. Establece External ID y etiquetas

Establecer el External ID es opcional pero recomendado porque te permite identificar usuarios entre dispositivos y sincronizar con tu backend. Enviar ONESIGNAL_EXTERNAL_ID al dataLayer Este ejemplo muestra cómo puedes enviar un ID de usuario al dataLayer para que GTM pueda leerlo a través de la variable ONESIGNAL_EXTERNAL_ID (creada en el paso 2).
HTML
Crea una etiqueta GTM para establecer el External ID Configuración de etiqueta:
  • Nombre de etiqueta: OneSignal – Set External ID
  • Tipo de etiqueta: Custom HTML
  • Tag firing options: Once per page
  • Trigger:
    • Crea un activador de evento personalizado para OneSignalInitialized (establecido en la etiqueta OneSignal - Init anterior) y
    • Opcionalmente si sabes que el ID de usuario está disponible en la carga de la página.
El método requerido para establecer el External ID es OneSignal.login(externalId) donde externalId es una cadena.Si {{ONESIGNAL_EXTERNAL_ID}} está vacío (o GTM sustituye “undefined” / “null”), la llamada a login se omitirá y el External ID no se establecerá. Este es un problema de tiempo común de GTM.

Establecer etiquetas

Esto envía Etiquetas de OneSignal usando nuestro SDK Web. Configuración de etiqueta:
  • Nombre: OneSignal - Add Tags
  • Tag Type: Custom HTML
  • Tag firing options: Once per page
  • Trigger:
    • OneSignalInitialized, y
    • Tu condición para cuando los datos de la etiqueta estén disponibles (por ejemplo: después del inicio de sesión, en una página de perfil, después de una compra).
Pega este código y reemplaza el TAG y VALUE de ejemplo.
HTML
Solo envía etiquetas cuando tengas los datos de usuario disponibles (por ejemplo, después del inicio de sesión, después de que se carga un perfil o después de un evento de conversión conocido).
Si tu sitio usa Consent Mode / un CMP, decide si OneSignal debe cargarse:
  • Solo después del consentimiento (común para EU/UK), o
  • Inmediatamente (común donde el almacenamiento “funcional” está permitido por defecto).
GTM admite un activador de inicialización de consentimiento y controles de consentimiento a nivel de etiqueta para administrar el comportamiento de las etiquetas según el consentimiento del usuario. Sin embargo, OneSignal también proporciona métodos de consentimiento de privacidad para controlar cuándo se carga el SDK.

Pruebas

  1. En GTM, abre el modo Preview.
  2. Carga tu sitio y confirma:
    • OneSignal - Init se activa una vez.
    • OneSignalInitialized aparece en la línea de tiempo de eventos de GTM (si mantuviste el evento push).
  3. Suscríbete a tu sitio web. Consulta Solicitudes de permisos web para obtener detalles sobre las solicitudes.
  4. En el panel de OneSignal, ve a Audience > Subscriptions y confirma:
    • Una suscripción aparece después de aceptar.
    • Un External ID es visible si estableciste uno.
  5. Envía un push de prueba desde Messages > New Push.
Si la inicialización está funcionando, verás las suscripciones apareciendo en OneSignal después de aceptar.

Solución de problemas

  • La etiqueta Init se activa, pero el SDK nunca se carga
    • Verifica si la Content Security Policy (CSP) está bloqueando https://cdn.onesignal.com.
    • Verifica los bloqueadores de anuncios/bloqueadores de scripts.
  • Errores de dataLayer
    • Asegúrate de que window.dataLayer = window.dataLayer || [] esté configurado antes de cualquier llamada dataLayer.push().
  • Avisos duplicados / carga duplicada del SDK
    • Asegúrate de no estar cargando OneSignal también a través del código del sitio, un plugin de CMS u otra etiqueta de GTM.
  • Add Tags se ejecuta pero no aparece en OneSignal
    • Confirma que el Trigger Group espera OneSignalInitialized.
    • Confirma que tu activador de acción de usuario se activa realmente.
    • Confirma que las etiquetas son pares clave/valor válidos y están dentro de los límites del plan.
Si aún necesitas ayuda, consulta Solución de problemas del SDK Web para correcciones comunes.

Próximos pasos