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, enviar 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.
  • Completa el flujo de configuración del SDK Web de OneSignal hasta llegar al paso Añadir código al sitio. Si haces esto, tendrás:

​
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.
Necesitarás subir el archivo OneSignal Service Worker directamente a tu servidor. Puedes encontrar más detalles en la guía de OneSignal Service Worker.

​
2. Crea variables de GTM

Crea variables de GTM para los valores que puedas referenciar en las etiquetas de GTM. Usar variables evita codificar valores de forma fija y hace que tu configuración sea más fácil de mantener. Crea una variable de OneSignal App ID
  1. En GTM, ve a Variables > New.
  2. Elige Constant.
  3. Nómbrala os_app_id.
  4. Establece el valor como tu OneSignal App ID.
  5. Guarda.
Ahora puedes referenciar tu App ID en cualquier lugar de GTM usando {{os_app_id}}.
Crea una variable de 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)
Ejemplo: Data Layer Variable
  1. En GTM, ve a Variables > New.
  2. Elige Data Layer Variable.
  3. Nómbrala external_id.
  4. Establece el Data Layer Variable Name como external_id.
  5. No establezcas un valor predeterminado.
  6. Guarda.
Se proporcionará un ejemplo de cómo insertar el valor en el dataLayer en la siguiente sección.
Crea una variable de OneSignal ID (Opcional) Usa esta variable si deseas referenciar el OneSignal ID en GTM (por ejemplo, cuando no se ha establecido un External ID).
  1. En GTM, ve a Variables > New.
  2. Variable Type: Data Layer Variable.
  3. Nómbrala onesignal_id.
  4. Establece el Data Layer Variable Name como onesignal_id.
  5. No establezcas un valor predeterminado.
  6. Guarda.
Se proporcionará un ejemplo de cómo insertar el valor en el dataLayer en la siguiente sección.
El OneSignal ID se genera después de la suscripción. Si planeas poblar este valor, debes insertarlo explícitamente en el dataLayer desde un callback de OneSignal.
No asumas que onesignal_id está disponible inmediatamente al cargar la página. Solo existe después de que el usuario se suscriba y el SDK devuelva el valor.

​
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
HTML
<script>
  // Ensure dataLayer exists before pushing events
  window.dataLayer = window.dataLayer || [];

  // OneSignal v16 GTM-friendly loader + init
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  (function loadOneSignalSDK() {
    // Prevent double-loading if another tag/theme/plugin already loaded it
    if (window.OneSignal || document.getElementById('onesignal-sdk')) return;

    var s = document.createElement('script');
    s.id = 'onesignal-sdk';
    s.src = 'https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js';
    s.async = true;

    s.onload = function () {
      // Queue init after SDK loads
      window.OneSignalDeferred.push(function (OneSignal) {
        OneSignal.init({
          appId: "{{os_app_id}}"
        })
        .then(function () {
          // Optional: use this as a GTM trigger signal for dependent tags
          window.dataLayer.push({ event: "OneSignalInitialized" });
        })
        .catch(function (e) {
          // Avoid breaking other tags; log for debugging
          console.error("OneSignal initialization failed:", e);
          window.dataLayer.push({
            event: "OneSignalInitFailed",
            oneSignalError: (e && e.message) ? e.message : String(e)
          });
        });
      });
    };

    s.onerror = function () {
      window.dataLayer.push({ event: "OneSignalSdkLoadFailed" });
    };

    document.head.appendChild(s);
  })();
</script>
  1. Configura el tiempo en Advanced Settings > Tag firing options como Once per page.
  2. En Triggering, selecciona Initialization - All Pages.
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 en todos los dispositivos y sincronizar con tu backend.

​
Establece external_id y captura el onesignal_id

Usa esta etiqueta cuando quieras:
  • Identificar usuarios en OneSignal con tu propio ID de usuario (external_id)
  • Capturar el ID generado por OneSignal para análisis o uso posterior en GTM cuando no existe un external ID
Esto asume que estás insertando el external_id en el dataLayer y usando la variable {{external_id}} del paso 2 anterior. Por ejemplo:
HTML
<script>
  window.dataLayer = window.dataLayer || [];
  dataLayer.push({
    external_id: "user_12345"
  });
</script>
Configuración de etiqueta
  • Tag name: OneSignal – Set External ID or Get OneSignal ID
  • Tag type: Custom HTML
  • Tag firing options: Once per page (recomendado)
  • Trigger: Usar con el evento OneSignalInitialized (establecido en la etiqueta OneSignal - Init anterior)
HTML
<script>
  window.dataLayer = window.dataLayer || [];
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  // Helper function to validate the external ID
  function isValidExternalId(val) {
    if (val == null) return false;
    var s = String(val).trim().toLowerCase();
    if (!s) return false;
    return s !== "undefined" && s !== "null" && s !== "(not set)";
  }

  // Push Subscription Change Listener
  function pushSubscriptionChangeListener(event) {
    console.log("subscription ID", event.current.id);
    console.log("event.current.optedIn", event.current.optedIn);
    // Save the OneSignal ID to the dataLayer
    var oneSignalId = OneSignal.User && OneSignal.User.onesignalId;
    if (oneSignalId && event.current.optedIn) {
      console.log("oneSignalId: ", oneSignalId);
      dataLayer.push({
        event: "OneSignalIdAvailable",
        onesignal_id: oneSignalId
      });
    }
  }

  OneSignalDeferred.push(function (OneSignal) {
    // Save the external ID to the dataLayer
    var externalId = "{{external_id}}";
    if (isValidExternalId(externalId)) {
      console.log("externalId: ", externalId);
      OneSignal.login(String(externalId).trim())
        .then(function () {
          dataLayer.push({
            event: "OneSignalExternalIdSet",
            external_id: String(externalId).trim()
          });
        })
        .catch(function () {
          dataLayer.push({ event: "OneSignalExternalIdSetFailed" });
        });
    }

    // Set up Subscription Change Listener
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });
</script>

​
Establece etiquetas de datos

Este paso envía etiquetas de datos de usuario a OneSignal usando el SDK Web. Configuración de etiqueta
  • Name: OneSignal - Add Tags.
  • Tag Type: Custom HTML.
  • Tag firing options: Once per page (recomendado)
  • Trigger:
    • Usar con el evento OneSignalInitialized (establecido en la etiqueta OneSignal - Init anterior)
    • Tu condición para que se active la etiqueta (p. ej., “Inicio de sesión exitoso”, “Página de perfil”, “Compra”, etc.)
Pega este código y reemplaza el TAG y VALUE de ejemplo.
HTML
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.addTags({
      "TAG_1": "VALUE_1",
      "TAG_2": "VALUE_2"
    });
  });
</script>
Envía etiquetas solo cuando tengas los datos del usuario disponibles (p. ej., después del inicio de sesión, después de que se cargue 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 UE/Reino Unido), o
  • Inmediatamente (común donde el almacenamiento “funcional” está permitido por defecto).
GTM admite un activador de Consent Initialization y controles de consentimiento a nivel de etiqueta para gestionar 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 conservaste el push del evento).
  3. Suscríbete a tu sitio web. Consulta Solicitudes de permiso web para obtener detalles sobre las solicitudes.
  4. En el panel de OneSignal, ve a Audience > Subscriptions y confirma que aparece una suscripción después de que te suscribas. También deberías ver un External ID si configuraste uno.
  5. Envía un push de prueba desde Messages > New Push.
Si la inicialización funciona, verás el SDK cargado en la página y las suscripciones apareciendo en OneSignal después de la suscripción.

​
Solución de problemas

  • La etiqueta Init se activa, pero el SDK nunca se carga
    • Verifica si hay una Content Security Policy (CSP) bloqueando https://cdn.onesignal.com.
    • Verifica bloqueadores de anuncios/bloqueadores de scripts.
  • Errores de dataLayer
    • Asegúrate de que window.dataLayer = window.dataLayer || [] esté establecido antes de cualquier llamada a dataLayer.push().
  • Solicitudes duplicadas / carga duplicada del SDK
    • Asegúrate de que no estás 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 a OneSignalInitialized.
    • Confirma que tu activador de acción de usuario realmente se activa.
    • 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