Référence de l'API JavaScript des messages intégrés

Ce guide couvre l’API JavaScript pour les messages intégrés HTML créés avec l’éditeur HTML OneSignal. Si vous recherchez des méthodes SDK pour définir des déclencheurs, gérer les événements de clic dans les messages intégrés ou gérer le cycle de vie des messages intégrés, consultez la référence du SDK mobile.

Exigences

Utiliser l’attribut `data-onesignal-unique-label` pour le suivi des clics

Tous les éléments cliquables doivent avoir un attribut data-onesignal-unique-label avec une valeur unique. Cela permet à OneSignal de :

Suivre les analyses de clics
Déclencher correctement les actions associées

HTML

<button id="tag-user-button" data-onesignal-unique-label="my-tag-user-button">
  Tag User
</button>

Si deux éléments partagent le même data-onesignal-unique-label, les clics peuvent être enregistrés incorrectement ou les actions peuvent ne pas se déclencher.

Attacher des écouteurs d’événements

Vous devez explicitement attacher des écouteurs d’événements JavaScript pour déclencher les actions de messages intégrés OneSignal.

JavaScript

document.getElementById("tag-user-button")
  .addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });

Exemple :

HTML

<button id="tag-user-button" data-onesignal-unique-label="my-tag-user-button">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>

Gestion du suivi des clics dans les messages intégrés HTML en bac à sable

Étant donné que les messages intégrés HTML s’exécutent dans une WebView en bac à sable, le suivi des clics et la navigation doivent se produire dans le même cadre. Les ancres standard (<a href="...">) et les appels window.open() ne sont pas suivis et peuvent déclencher des avertissements de console tels que :

SOAuthorizationCoordinator::tryAuthorize (2): Attempting to perform subframe navigation.

Correct : utiliser un bouton et les API OneSignal

HTML

<button id="shop-now" data-onesignal-unique-label="shop_now_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>

Incorrect : utiliser `<a>` ou `window.open()`

HTML

<a href="https://shop.example.com" target="_blank">
  Shop Now
</a>

Cette navigation se produit en dehors du bac à sable du message intégré, empêchant OneSignal d’enregistrer l’événement de clic.

Chaque élément cliquable doit avoir un data-onesignal-unique-label unique.
Appelez toujours OneSignalIamApi.trackClick(e) avant openUrl() ou toute autre méthode de l’API OneSignal.
Liez les écouteurs d’événements après DOMContentLoaded pour vous assurer que les éléments existent.
OneSignal suit automatiquement les clics uniquement pour les méthodes listées dans cette référence ; toute navigation personnalisée doit appeler trackClick() manuellement.

Problèmes courants

Clics non enregistrés : trackClick() n’a pas été appelé ou l’élément manque un data-onesignal-unique-label.
- Appelez trackClick(e) et assurez-vous que chaque élément a un label unique.
La console affiche “Attempting to perform subframe navigation” : Le code utilise window.open() ou un lien <a> au lieu de OneSignalIamApi.openUrl().
- Utilisez OneSignalIamApi.openUrl(e, "https://example.com/") dans le même gestionnaire de clic.
Le mauvais label apparaît dans les analyses : Plusieurs éléments partagent le même data-onesignal-unique-label.
- Donnez à chaque élément cliquable un label unique.

Fonctions disponibles

Toutes les actions de clic de l’éditeur de blocs sont également disponibles pour les messages intégrés HTML.

Invite de permission push

Affiche l’invite de permission de notification push native. Les événements de clic sont automatiquement suivis. Voir Inviter aux permissions push.

HTML

<button id="push-prompt-button" data-onesignal-unique-label="push-permission">
  Enable Push
</button>
<script>
  document.getElementById("push-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerPushPrompt(e);
  });
</script>

Invite de permission de localisation

Affiche l’invite de permission de localisation native. Les événements de clic sont automatiquement suivis. Voir Invites de permission de localisation.

HTML

<button id="location-prompt-button" data-onesignal-unique-label="location-permission">
  Enable Location
</button>
<script>
  document.getElementById("location-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerLocationPrompt(e);
  });
</script>

Fermer le message intégré

Ferme le message intégré actuel. Les événements de clic sont automatiquement suivis.

html

<button id="close-button" data-onesignal-unique-label="close-message">
  Close
</button>
<script>
  document.getElementById("close-button").addEventListener("click", function(e) {
    OneSignalIamApi.close(e);
  });
</script>

Taguer l’utilisateur

Définit un tag. Les événements de clic sont automatiquement suivis.

HTML

<button id="tag-user-button" data-onesignal-unique-label="tag-user">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>

Ouvrir une URL

Ouvre une URL dans le navigateur de l’appareil et ferme le message intégré. Les événements de clic sont automatiquement suivis. Prend en charge les liens profonds.

HTML

<button id="open-url-button" data-onesignal-unique-label="open-website">
  Visit Site
</button>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    OneSignalIamApi.openUrl(e, "https://example.com");
  });
</script>

Nom de clic

Attribue un nom de clic qui peut être lu dans l’écouteur de clic de message intégré. Les événements de clic sont automatiquement suivis. Prend en charge les liens profonds.

HTML

<button id="click-name-button" data-onesignal-unique-label="named-click">
  Click Me
</button>
<script>
  document.getElementById("click-name-button").addEventListener("click", function(e) {
    OneSignalIamApi.addClickName(e, "test_click_name");
  });
</script>

Suivre le clic

Suit un événement de clic lorsque vous n’utilisez pas d’autres méthodes d’API cliquables.

html

<button id="track-click-button" data-onesignal-unique-label="custom-track">
  Track Click
</button>
<script>
  document.getElementById("track-click-button").addEventListener("click", function(e) {
    OneSignalIamApi.trackClick(e);
  });
</script>

Envoyer un résultat

Suit un résultat personnalisé non attribué et définit un tag sur l’utilisateur au format nom du résultat : true. Les événements de clic sont automatiquement suivis.

html

<button id="send-outcome-button" data-onesignal-unique-label="bonus-claim">
  Claim Bonus
</button>
<script>
  document.getElementById("send-outcome-button").addEventListener("click", function(e) {
    OneSignalIamApi.sendOutcome(e, "bonus_claimed");
  });
</script>

Personnalisation des messages intégrés HTML

Vous pouvez utiliser la substitution de tags dans les messages intégrés HTML tout comme dans l’éditeur de blocs.

La substitution de tags ne fonctionne pas à l’intérieur des balises <script>.

La substitution de tags fonctionne pour :

Texte en ligne (<h1>, <p>, <li>, etc.)

Règles <style> :

CSS

body { background-color: "{{ favorite_color | default: '#fff' }}"; }

Attributs avec des URL :
- href
- src
- <form action>
- <object data>

Utilisation des tags dans `openUrl()` et `addClickName()`

Étant donné que les balises <script> ne prennent pas en charge la substitution, utilisez l’une de ces méthodes : 1. Accéder à tous les tags avec liquidPlayerTags Cet objet global devient disponible après 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. Stocker un tag dans l’attribut 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>

Prochaines étapes

En savoir plus sur l’utilisation de la syntaxe liquid pour la substitution de tags
Explorer les liens profonds pour la gestion des URL
Concevoir des messages intégrés avec HTML

Premiers pas et paramètres

Canaux de messagerie

Journeys

Audience et événements personnalisés

Analyses et intégrations

Confidentialité et sécurité

Référence de l'API JavaScript des messages intégrés

Exigences

Utiliser l’attribut `data-onesignal-unique-label` pour le suivi des clics

Attacher des écouteurs d’événements

Gestion du suivi des clics dans les messages intégrés HTML en bac à sable

Correct : utiliser un bouton et les API OneSignal

Incorrect : utiliser `<a>` ou `window.open()`

Problèmes courants

Fonctions disponibles

Invite de permission push

Invite de permission de localisation

Fermer le message intégré

Taguer l’utilisateur

Ouvrir une URL

Nom de clic

Suivre le clic

Envoyer un résultat

Personnalisation des messages intégrés HTML

Utilisation des tags dans `openUrl()` et `addClickName()`

Prochaines étapes

​Exigences

​Utiliser l’attribut data-onesignal-unique-label pour le suivi des clics

​Attacher des écouteurs d’événements

​Gestion du suivi des clics dans les messages intégrés HTML en bac à sable

​Correct : utiliser un bouton et les API OneSignal

​Incorrect : utiliser <a> ou window.open()

​Problèmes courants

​Fonctions disponibles

​Invite de permission push

​Invite de permission de localisation

​Fermer le message intégré

​Taguer l’utilisateur

​Ouvrir une URL

​Nom de clic

​Suivre le clic

​Envoyer un résultat

​Personnalisation des messages intégrés HTML

​Utilisation des tags dans openUrl() et addClickName()

​Prochaines étapes

Exigences

Utiliser l’attribut `data-onesignal-unique-label` pour le suivi des clics

Attacher des écouteurs d’événements

Gestion du suivi des clics dans les messages intégrés HTML en bac à sable

Correct : utiliser un bouton et les API OneSignal

Incorrect : utiliser `<a>` ou `window.open()`

Problèmes courants

Fonctions disponibles

Invite de permission push

Invite de permission de localisation

Fermer le message intégré

Taguer l’utilisateur

Ouvrir une URL

Nom de clic

Suivre le clic

Envoyer un résultat

Personnalisation des messages intégrés HTML

Utilisation des tags dans `openUrl()` et `addClickName()`

Prochaines étapes