Referencia del Web SDK

​

Configuración y depuración

​

init()

window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "ONESIGNAL_APP_ID",
  });
});

​

Parámetros de promptOptions

​

Parámetros de notifyButton

​

Parámetros de welcomeNotification

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "YOUR_APP_ID",
    notifyButton: {
      enable: true,
    },
    promptOptions: {
      slidedown: {
        prompts: [{
            type: "smsAndEmail",
            autoPrompt: false,
            text: {
              emailLabel: "Insert Email Address",
              smsLabel: "Insert Phone Number",
              acceptButton: "Submit",
              cancelButton: "No Thanks",
              actionMessage: "Receive the latest news, updates and offers as they happen.",
              updateMessage: "Update your push notification subscription preferences.",
              confirmMessage: "Thank You!",
              positiveUpdateButton: "Save Preferences",
              negativeUpdateButton: "Cancel",
            },
            delay: {
              pageViews: 1,
              timeDelay: 20
            },
          },
          {
            type: "category",
            autoPrompt: true,
            text: {
              actionMessage: "We'd like to show you notifications for the latest news and updates.",
              acceptButton: "Allow",
              cancelButton: "Cancel",

              /* CATEGORY SLIDEDOWN SPECIFIC TEXT */
              negativeUpdateButton: "Cancel",
              positiveUpdateButton: "Save Preferences",
              updateMessage: "Update your push notification subscription preferences.",
            },
            delay: {
              pageViews: 3,
              timeDelay: 20
            },
            categories: [{
                tag: "politics",
                label: "Politics"
              },
              {
                tag: "local_news",
                label: "Local News"
              },
              {
                tag: "world_news",
                label: "World News",
              },
              {
                tag: "culture",
                label: "Culture"
              },
            ]
          }
        ]
      }
    }
  });
});
</script>

​

setLogLevel()

  OneSignal.Debug.setLogLevel("trace");

• 'trace'
• 'debug'
• 'info'
• 'warn'
• 'error'

​

Identidad y propiedades del usuario

​

login(external_id)

• El SDK cambia a ese usuario existente.
  • Puedes ver un 409 Conflict en el registro de red del navegador o en la consola. Significa que el External ID ya existe en la aplicación; es esperado en este caso y normalmente no es un rechazo de promesa que debas manejar.
• El onesignal_id actual se descarta y se carga el onesignal_id existente de ese usuario.
• El dispositivo actual (Suscripción push web) se vincula al usuario existente.
• Los datos anónimos recopilados antes del login no se fusionan y se descartan. Esto incluye tags, datos de sesión, Suscripciones de email/SMS y otras propiedades locales del usuario.

• Se crea un nuevo usuario usando el onesignal_id actual.
• Se conservan todos los datos recopilados mientras el usuario era anónimo.
• El dispositivo (Suscripción push web) queda vinculado a este nuevo usuario.

• El SDK reintenta automáticamente la solicitud de login ante fallos de red o errores del servidor.
• No necesitas implementar tu propia lógica de reintento.

• Llama a login(external_id) en cada carga de página una vez que conozcas el ID del usuario (por ejemplo, después del inicio de sesión o la restauración de sesión).
• Llámalo de nuevo cada vez que cambie el usuario con sesión iniciada (cambio de cuenta).
• No llames a login antes de tener un identificador de usuario estable y conocido.

OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.login("external_id");
});

​

logout()

• Elimina el external_id de la Suscripción push web actual. No elimina el external_id de otras Suscripciones.
• Restablece el onesignal_id a un nuevo usuario anónimo.
• Cualquier dato nuevo (p. ej., tags, Suscripciones, datos de sesión, etc.) se establecerá ahora en el nuevo usuario anónimo hasta que se identifique con el método login.

OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.logout();
});

​

OneSignal.User.onesignalId

• Después de que el SDK de OneSignal termina de inicializarse
• Después de que un usuario es identificado con login(external_id)
• Después de cambiar de usuario o restaurar una sesión

• Rastrear usuarios anónimos antes de que se establezca un External ID
• Almacenar el OneSignal ID en tu backend para soporte o depuración
• Correlacionar usuarios de OneSignal con registros internos
• Mostrar el ID para solución de problemas o QA

const onesignalId = OneSignal.User.onesignalId;

​

OneSignal.User.externalId

  const externalId = OneSignal.User.externalId;

​

addEventListener() User State

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.addEventListener('change', function (event) {
      console.log('change', { event });
    });
  });

​

addAlias(), addAliases(), removeAlias(), removeAliases()

• Establece el external_id con login() antes de agregar alias. Los alias agregados a suscripciones sin external_id no se sincronizarán entre múltiples suscripciones.
• Consulta Alias para más detalles.

  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  OneSignal.User.addAliases({
    ALIAS_LABEL_01: "ALIAS_ID_01",
    ALIAS_LABEL_02: "ALIAS_ID_02",
    ALIAS_LABEL_03: "ALIAS_ID_03",
  });

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02", "ALIAS_LABEL_03"]);

​

getLanguage(), setLanguage()

  // Get the language of the currently logged-in user
  OneSignal.User.getLanguage();

  // Set the language of the currently logged-in user
  OneSignal.User.setLanguage("en");

​

Eventos personalizados

• name - Obligatorio. El nombre del evento como string.
• properties - Opcional. Pares clave-valor para agregar al evento. El diccionario o mapa de propiedades debe ser serializable en un objeto JSON válido. Admite valores anidados.

{ 
  "os_sdk": {
    "device_os": "138",
    "type": "ChromePush",
    "device_model": "MacIntel",
    "sdk": "160500"
  }
}

​

trackEvent()

OneSignalDeferred.push(async function (OneSignal) {
  await OneSignal.init({ appId: "ONESIGNAL_APP_ID" });

  const properties = {
    promo_code: "NEW50",
    membership_details: {
      vip: true,
      products_viewed_count: 15,
    },
  };
  OneSignal.User.trackEvent("started_free_trial", properties);

  // Event name only (no properties)
  OneSignal.User.trackEvent("my_event_name");
});

​

Tags

​

addTag(), addTags()

• Los valores se reemplazarán si la clave ya existe.
• Exceder el límite de tags de tu plan hará que las operaciones fallen silenciosamente.

  // Add a single tag
  OneSignal.User.addTag('tag_key', 'tag_value');

  // Add multiple tags
  OneSignal.User.addTags({
   KEY_01: "VALUE_01",
   KEY_02: "VALUE_02",
   KEY_03: "VALUE_03"
  });

​

removeTag(), removeTags()

  // Delete a single tag
  OneSignal.User.removeTag("KEY");

  OneSignal.User.removeTags(['KEY_01', 'KEY_02', 'KEY_03']);

​

getTags()

  const tags = OneSignal.User.getTags()

​

Privacidad

​

setConsentRequired()

  OneSignal.setConsentRequired(true);

​

setConsentGiven()

• Si setConsentRequired() o requiresUserPrivacyConsent se establece en true, nuestro SDK no estará completamente habilitado hasta que se llame a setConsentGiven con true.
• Si setConsentGiven se establece en true y se crea una Suscripción, y luego se establece en false, esa Suscripción ya no recibirá actualizaciones. Los datos actuales de esa Suscripción permanecen sin cambios hasta que setConsentGiven se establezca en true nuevamente.
• Si quieres eliminar los datos del Usuario y/o de la Suscripción, usa nuestras APIs Delete user o Delete subscription.

  OneSignal.setConsentGiven(true);

​

Suscripciones

​

User.PushSubscription.id

  const subscription_id = OneSignal.User.PushSubscription.id;

​

User.PushSubscription.token

  OneSignal.User.PushSubscription.token;

​

addEventListener() Push Subscription Changes

• El dispositivo recibe un nuevo token push de Google (FCM) o Apple (APNs)
• OneSignal asigna un subscription ID
• El valor de optedIn cambia (p. ej., se llamó a optIn() u optOut())
• El usuario cambia el permiso de push en la configuración del navegador o del sistema operativo y luego regresa a tu sitio

  function pushSubscriptionChangeListener(event) {
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

  function pushSubscriptionChangeListener(event) {
    if (!event.current.token || event.previous.token) {
      return;
    }
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "onesignal_push_subscribed",
      onesignal_subscription_id: event.current.id,
    });
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

​

optOut(), optIn(), optedIn

• optOut(): Establece el estado de la suscripción push actual en no suscrito (incluso si el usuario tiene un token push válido).
• optIn(): Hace una de las siguientes acciones:
  1. Si la Suscripción tiene un token push válido, establece el estado de la suscripción push actual en subscribed.
  2. Si la Suscripción no tiene un token push válido, intenta mostrar el prompt de permiso de push.
• optedIn: Devuelve true si el estado de la suscripción push actual es suscrito; de lo contrario, false. Si el token push es válido pero se llamó a optOut(), devolverá false.

  OneSignal.User.PushSubscription.optOut();

  OneSignal.User.PushSubscription.optIn();

  var optedIn = OneSignal.User.PushSubscription.optedIn;

​

addEmail(), removeEmail()

• La dirección de email se convierte en una Suscripción de email para el usuario actual.
• El email puede crearse o reasignarse.
• La misma dirección de email no puede existir varias veces en la misma aplicación de OneSignal. Si ves direcciones de email duplicadas, revisa tus solicitudes a la REST API y contacta a soporte si es necesario.

• La Suscripción de email se elimina del usuario actual.
• El External ID actual se elimina de la Suscripción de email.
• Se asigna un nuevo OneSignal ID a la Suscripción de email.
• Las demás Suscripciones (push, SMS, otros emails) no se ven afectadas.

• Llama primero a login() y luego a addEmail(). De lo contrario, el email puede quedar asociado a un usuario anónimo.
• Usa una dirección de email estable y verificada.
• Sigue las mejores prácticas de reputación de email.

  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");

​

addSms(), removeSms()

• El número de teléfono se convierte en una Suscripción de SMS para el usuario actual.
• El número puede crearse o reasignarse.
• El mismo número de teléfono no puede existir varias veces en la misma aplicación de OneSignal. Si ves números de teléfono duplicados, revisa tus solicitudes a la REST API y contacta a soporte si es necesario.

• La Suscripción de SMS se elimina del usuario actual.
• El External ID actual se elimina de la Suscripción de SMS.
• Se asigna un nuevo OneSignal ID a la Suscripción de SMS.
• Las demás Suscripciones (push, email, otros SMS) no se ven afectadas.

• Llama primero a login() y luego a addSms(). De lo contrario, la Suscripción de SMS puede quedar asociada a un usuario anónimo.
• Valida y normaliza siempre los números de teléfono al formato E.164 antes de enviarlos.
• Sigue los requisitos de registro de SMS.

  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");

​

Prompts de Slidedown

• Si se descarta, las llamadas futuras se ignorarán durante al menos tres días. Rechazos adicionales alargarán el tiempo que debe transcurrir antes de volver a mostrar el prompt al usuario.
• Para anular el comportamiento de espera (back-off), pasa {force: true} al método. Sin embargo, para brindar una buena experiencia de usuario, vincula la acción a un evento iniciado por la interfaz, como un clic en un botón.

​

promptPush()

• Si usas categorías, llama a promptPushCategories() en su lugar.
• Sujeto a la lógica de espera (backoff) establecida por OneSignal. Consulta Prompts de permiso web para más detalles.

  OneSignal.Slidedown.promptPush();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPush({force: true});

​

promptPushCategories()

• Si no usas categorías, llama a promptPush() en su lugar.
• Sujeto a la lógica de espera (backoff) establecida por OneSignal. Consulta Prompts de permiso web para más detalles.

  OneSignal.Slidedown.promptPushCategories();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPushCategories({force: true});

​

promptSms()

• Sujeto a la lógica de espera (backoff) establecida por OneSignal. Consulta Prompts de permiso web para más detalles.

  OneSignal.Slidedown.promptSms();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSms({force: true});

​

promptEmail()

• Sujeto a la lógica de espera (backoff) establecida por OneSignal. Consulta Prompts de permiso web para más detalles.

  OneSignal.Slidedown.promptEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptEmail({force: true});

​

promptSmsAndEmail()

• Sujeto a la lógica de espera (backoff) establecida por OneSignal. Consulta Prompts de permiso web para más detalles.

  OneSignal.Slidedown.promptSmsAndEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSmsAndEmail({force: true});

​

addEventListener() Slidedown

  OneSignalDeferred.push(function(OneSignal) {

    OneSignal.Slidedown.addEventListener('slidedownShown', function (event) {
      console.log('slidedownShown', { event });
    });

  });

​

Notificaciones push

​

requestPermission()

  OneSignal.Notifications.requestPermission();

​

isPushSupported()

  const isSupported = OneSignal.Notifications.isPushSupported();

​

OneSignal.Notifications.permission

• true: El usuario ha otorgado permiso para mostrar notificaciones.
• false: El usuario ha denegado el permiso o aún no lo ha otorgado.

  let permission = OneSignal.Notifications.permission;

​

addEventListener() Notifications

  function onClick(event) {
    console.log("click", event);
  }

  OneSignal.Notifications.addEventListener("click", onClick);
  OneSignal.Notifications.removeEventListener("click", onClick);

​

permissionChange

  function permissionChangeListener(permission) {
    if (permission) {
      console.log(`permission accepted!`);
    }
  }

  OneSignal.Notifications.addEventListener("permissionChange", permissionChangeListener);

​

permissionPromptDisplay

  function promptListener(event) {
    console.log("permission prompt displayed", event);
  }

  OneSignal.Notifications.addEventListener("permissionPromptDisplay", promptListener);

​

click

  function clickEventListener(event) {
    console.log(`click event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("click", clickEventListener);

​

foregroundWillDisplay

  function foregroundWillDisplayListener(event) {
    console.log("notification will display", event);
  }

  OneSignal.Notifications.addEventListener("foregroundWillDisplay", foregroundWillDisplayListener);

​

dismiss

• Un usuario descarta deliberadamente la notificación sin hacer clic en el cuerpo de la notificación ni en los botones de acción
• En Chrome en Android, un usuario descarta todas las notificaciones push web (este evento se disparará por cada notificación push web que mostremos)
• Una notificación expira por sí sola y desaparece

  function notificationDismissedListener(event) {
    console.log(`dismiss event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("dismiss", notificationDismissedListener);

​

setDefaultUrl()

  OneSignal.Notifications.setDefaultUrl("https://onesignal.com");

​

setDefaultTitle()

  OneSignal.Notifications.setDefaultTitle("Powered by OneSignal!");

​

Outcomes

​

sendOutcome()

  OneSignal.Session.sendOutcome('outcome name', 19.84);

​

sendUniqueOutcome()

  OneSignal.Session.sendUniqueOutcome('outcome name');