Passer au contenu principal
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