Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

Esta guía cubre la API de JavaScript para mensajes HTML dentro de la aplicación creados con el Editor HTML de OneSignal. Si estás buscando métodos SDK para configurar disparadores, manejar eventos de clic dentro de la aplicación o gestionar el ciclo de vida dentro de la aplicación, consulta la Referencia del SDK Móvil.

​
Requisitos

​
Usar el atributo data-onesignal-unique-label para rastreo de clics

Todos los elementos clicables deben tener un atributo data-onesignal-unique-label con un valor único. Esto permite a OneSignal:
  • Rastrear análisis de clics
  • Disparar correctamente acciones asociadas
HTML
<button id="tag-user-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Tag User
</button>
Si dos elementos comparten el mismo data-onesignal-unique-label, los clics pueden registrarse incorrectamente o las acciones pueden no dispararse.

​
Adjuntar detectores de eventos

Debes adjuntar explícitamente detectores de eventos de JavaScript para disparar acciones dentro de la aplicación de OneSignal.
JavaScript
document.getElementById("tag-user-button")
  .addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
Ejemplo:
HTML
<button id="tag-user-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>

​
Manejo del rastreo de clics en mensajes HTML dentro de la aplicación en entorno aislado

Debido a que los mensajes HTML dentro de la aplicación se ejecutan en un WebView aislado, el rastreo de clics y la navegación deben ocurrir dentro del mismo marco. Los anclajes estándar (<a href="...">) y las llamadas window.open() no se rastrean y pueden desencadenar advertencias en la consola como: 
SOAuthorizationCoordinator::tryAuthorize (2): Attempting to perform subframe navigation.

​
Correcto: usar un botón y APIs de OneSignal

HTML
<button id="shop-now" data-onesignal-unique-label="your-unique-label-for-this-button">
  Shop Now
</button>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    const btn = document.getElementById("shop-now");
    btn.addEventListener("click", function(e) {
      OneSignalIamApi.trackClick(e);
      OneSignalIamApi.openUrl(e, "https://shop.example.com/");
    });
  });
</script>

​
Incorrecto: usar <a> o window.open()

HTML
<a href="https://shop.example.com" target="_blank">
  Shop Now
</a>
Esta navegación ocurre fuera del entorno aislado dentro de la aplicación, impidiendo que OneSignal registre el evento de clic.
  • Cada elemento clicable debe tener un data-onesignal-unique-label único.
  • Siempre llama a OneSignalIamApi.trackClick(e) antes de openUrl() o cualquier otro método de API de OneSignal.
  • Vincula detectores de eventos después de DOMContentLoaded para asegurar que los elementos existan.
  • OneSignal rastrea automáticamente clics solo para los métodos listados en esta referencia; cualquier navegación personalizada debe llamar trackClick() manualmente.

​
Problemas comunes

  • Clics no registrados: No se llamó a trackClick() o al elemento le falta un data-onesignal-unique-label.
    • Llama a trackClick(e) y asegúrate de que cada elemento tenga una etiqueta única.
  • La consola muestra “Attempting to perform subframe navigation”: El código usa window.open() o un enlace <a> en lugar de OneSignalIamApi.openUrl().
    • Usa OneSignalIamApi.openUrl(e, "https://example.com/") dentro del mismo manejador de clics.
  • Aparece la etiqueta incorrecta en los análisis: Múltiples elementos comparten el mismo data-onesignal-unique-label.
    • Da a cada elemento clicable una etiqueta única.

​
Funciones disponibles

Todas las acciones de clic del Editor de Bloques también están disponibles para mensajes HTML dentro de la aplicación.

​
Solicitud de permiso de push

Muestra la solicitud de permiso de notificación push nativa. Los eventos de clic se rastrean automáticamente. Ve Solicitar permisos de push.
HTML
<button id="push-prompt-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Enable Push
</button>
<script>
  document.getElementById("push-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerPushPrompt(e);
  });
</script>

​
Solicitud de permiso de ubicación

Muestra la solicitud de permiso de ubicación nativa. Los eventos de clic se rastrean automáticamente. Ve Solicitudes de permiso de ubicación.
HTML
<button id="location-prompt-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Enable Location
</button>
<script>
  document.getElementById("location-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerLocationPrompt(e);
  });
</script>

​
Cerrar mensaje dentro de la aplicación

Descarta el mensaje dentro de la aplicación actual. Los eventos de clic se rastrean automáticamente.
html
<button id="close-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Close
</button>
<script>
  document.getElementById("close-button").addEventListener("click", function(e) {
    OneSignalIamApi.close(e);
  });
</script>

​
Etiquetar usuario

Establece una Etiqueta. Los eventos de clic se rastrean automáticamente.
HTML
<button id="tag-user-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>

​
Abrir URL

Abre una URL en el navegador del dispositivo y cierra el mensaje dentro de la aplicación. Los eventos de clic se rastrean automáticamente. Soporta Enlace Profundo.
HTML
<button id="open-url-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Visit Site
</button>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    OneSignalIamApi.openUrl(e, "https://example.com");
  });
</script>

​
Nombre de clic

Asigna un nombre de clic que puede leerse en el detector de clics de mensajes dentro de la aplicación. Los eventos de clic se rastrean automáticamente. Soporta Enlace Profundo.
HTML
<button id="click-name-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Click Me
</button>
<script>
  document.getElementById("click-name-button").addEventListener("click", function(e) {
    OneSignalIamApi.addClickName(e, "test_click_name");
  });
</script>

​
Rastrear clic

Rastrea un evento de clic cuando no estás usando otros métodos de API clicables.
HTML
<button id="track-click-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Track Click
</button>
<script>
  document.getElementById("track-click-button").addEventListener("click", function(e) {
    OneSignalIamApi.trackClick(e);
  });
</script>

​
Enviar Outcome

Rastrea un Outcome Personalizado no atribuido y establece una Etiqueta en el usuario en el formato nombre del outcome : true. Los eventos de clic se rastrean automáticamente.
html
<button id="send-outcome-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Claim Bonus
</button>
<script>
  document.getElementById("send-outcome-button").addEventListener("click", function(e) {
    OneSignalIamApi.sendOutcome(e, "bonus_claimed");
  });
</script>

​
Personalizar mensajes HTML dentro de la aplicación

Puedes usar sustitución de etiquetas en mensajes HTML dentro de la aplicación al igual que en el Editor de Bloques.
La sustitución de etiquetas no funciona dentro de etiquetas <script>.
La sustitución de etiquetas funciona para:
  • Texto en línea (<h1>, <p>, <li>, etc.)
  • Reglas <style>:
    CSS
    body { background-color: "{{ favorite_color | default: '#fff' }}"; }
  • Atributos con URLs:
    • href
    • src
    • <form action>
    • <object data>

​
Usar etiquetas en openUrl() y addClickName()

Dado que las etiquetas <script> no soportan sustitución, usa uno de estos métodos: 1. Acceder a todas las etiquetas con liquidPlayerTags Este objeto global se vuelve disponible después de DOMContentLoaded.
HTML
<div class="my-tags">--test checking all tags--</div>
<button id="open-url-button" data-onesignal-unique-label="promo-link">
  Personalized Offer
</button>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    if (liquidPlayerTags) {
      document.querySelector(".my-tags").innerHTML = JSON.stringify(liquidPlayerTags);
    }
  });
  document.addEventListener("DOMContentLoaded", function() {
    document.getElementById("open-url-button").addEventListener("click", function(e) {
      OneSignalIamApi.openUrl(e, "https://shop.com?coupon=" + liquidPlayerTags["coupon"]);
    });
  });
</script>
2. Almacenar una etiqueta en el atributo href
HTML
<a
  id="open-url-button"
  href="app://deeplink?code={{ coupon | default: '10OFF' }}"
  data-onesignal-unique-label="promo-link"
>
  Redeem Offer
</a>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    e.preventDefault();
    OneSignalIamApi.openUrl(e, e.currentTarget.href);
  });
</script>

​
Próximos pasos