Skip to main content

Configuration et débogage

Vous remarquerez peut-être la nécessité d’envelopper vos appels OneSignal avec OneSignalDeferred.push(async function() { ... }) Vous pouvez ajouter autant de méthodes que souhaité dans la function(). Le SDK OneSignal est chargé avec l’attribut defer sur votre page. Par exemple : <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script> Cela signifie que le code OneSignal s’exécutera après que le document HTML ait été entièrement analysé, empêchant tout blocage du site par le SDK OneSignal. Cependant, cela présente un problème pour les scripts de page qui dépendent de l’existence de la variable OneSignalDeferred. Pour résoudre ce problème, lorsque vous ajoutez OneSignal à votre site, il doit commencer par : window.OneSignalDeferred = window.OneSignalDeferred || []; Cela crée une variable OneSignalDeferred, et si OneSignal est déjà chargé, elle est alors assignée à l’instance chargée. Sinon, la variable OneSignal est égale à un tableau vide - []. Tous les tableaux ont une fonction .push(), donc à ce stade, la variable OneSignalDeferred est simplement un tableau de fonctions que nous y poussons. Lorsque le SDK se charge finalement, le SDK traite toutes les fonctions poussées jusqu’à présent et redéfinit .push().

init()

Initialise le SDK OneSignal. Ceci devrait être appelé dans la balise <head> une fois sur chaque page de votre site. Le ONESIGNAL_APP_ID peut être trouvé dans Clés et ID.
Si vous souhaitez retarder l’initialisation du SDK OneSignal, nous recommandons d’utiliser nos méthodes de confidentialité.
Init options only work with Custom Code Setup. Otherwise, these are configured in the OneSignal dashboard.

promptOptions parameters

Use promptOptions to localize or customize the user permission prompts. All fields are optional.

notifyButton parameters

Configure the Subscription Bell (notify button) shown on the page.

welcomeNotification parameters

Customize the welcome notification sent after first-time subscription.
Example:

setLogLevel()

Set the logging to print additional logs to the console. See Debugging with Browser DevTools for more details.
JavaScript
Log levels:
  • 'trace'
  • 'debug'
  • 'info'
  • 'warn'
  • 'error'

Identité et propriétés de l’utilisateur

Lorsque vos utilisateurs s’abonnent aux notifications push sur votre site web, OneSignal crée automatiquement un ID OneSignal (niveau utilisateur) et un ID d’abonnement (niveau appareil). Vous pouvez associer plusieurs abonnements (par exemple, appareils, emails, numéros de téléphone) à un seul utilisateur en appelant login() avec votre identifiant utilisateur unique.
Consultez Utilisateurs et Alias pour plus de détails.

login(external_id)

Définit le contexte utilisateur sur l’external_id fourni. Garantit que tous les abonnements et propriétés associés à cet external_id sont unifiés sous un seul onesignal_id. Consultez Utilisateurs pour plus de détails. Comportements clés :
  • Si l’external_id existe déjà, le SDK bascule vers cet utilisateur. Les données anonymes collectées avant la connexion ne sont pas fusionnées et seront supprimées.
  • Si l’external_id n’existe pas, l’état local sera enregistré sous l’onesignal_id actuel. Toutes les données collectées lorsque l’utilisateur était anonyme seront conservées.
  • Le SDK réessaie automatiquement en cas d’échec réseau ou d’erreur serveur.
Appelez cette méthode chaque fois que l’utilisateur ouvre le site ou dans le listener de changement d’abonnement pour vous assurer que l’ID externe est défini et que l’abonnement est lié à l’utilisateur.

logout()

Dissocie l’utilisateur actuel de l’abonnement.
  • Supprime l’external_id de l’abonnement push actuel.
  • Réinitialise l’ID OneSignal vers un nouvel utilisateur anonyme.
  • Toutes les nouvelles données (par exemple tags, abonnements, données de session, etc.) seront désormais définies sur le nouvel utilisateur anonyme jusqu’à ce qu’il soit identifié avec la méthode login.
Utilisez ceci lorsqu’un utilisateur se déconnecte de votre application si vous souhaitez définir l’abonnement sur un nouvel utilisateur anonyme.
JavaScript

OneSignal.User.onesignalId

Récupère l’ID OneSignal de l’utilisateur actuel enregistré localement dans le navigateur. Peut être null si appelé avant l’initialisation de l’état utilisateur. À la place, utilisez User State addObserver() pour écouter les changements d’état utilisateur.
JavaScript

OneSignal.User.externalId

Récupère l’ID externe de l’utilisateur actuel enregistré localement dans le navigateur. Peut être null si non défini via la méthode login ou appelé avant l’initialisation de l’état utilisateur. À la place, utilisez User State addObserver() pour écouter les changements d’état utilisateur.
JavaScript

addEventListener() État utilisateur

Écoute les changements dans le contexte utilisateur (par exemple, connexion, déconnexion, attribution d’ID).
JavaScript

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

Les alias sont des identifiants alternatifs (comme des noms d’utilisateur ou des ID CRM).
  • Définissez l’external_id avec login() avant d’ajouter des alias. Les alias ajoutés aux abonnements sans external_id ne se synchroniseront pas sur plusieurs abonnements.
  • Consultez Alias pour plus de détails.
JavaScript

getLanguage(), setLanguage()

Obtenez et/ou remplacez la langue auto-détectée de l’utilisateur. Consultez Messagerie multilingue pour une liste des codes de langue disponibles.
JavaScript

Événements personnalisés

Déclenchez des Journeys et activation de l’étape Wait Until via un événement personnalisé.
Les événements personnalisés nécessitent le SDK Web 160500+Un utilisateur doit être connecté pour que les événements personnalisés soient suivis.
Suivez et envoyez un événement personnalisé effectué par l’utilisateur actuel.
  • name - Requis. Le nom de l’événement sous forme de chaîne.
  • properties - Optionnel. Paires clé-valeur à ajouter à l’événement. Le dictionnaire ou la carte des propriétés doit être sérialisable en un objet JSON valide. Prend en charge les valeurs imbriquées.
Le SDK inclut automatiquement les données spécifiques à l’application dans le payload des propriétés sous la clé réservée os_sdk qui sera disponible à la consommation. Par exemple, pour cibler les événements par type d’abonnement, vous accéderiez à os_sdk.type.
json

trackEvent()

JavaScript

Tags de données

Les tags sont des paires personnalisées clé : valeur de données chaîne que vous définissez sur les utilisateurs en fonction d’événements ou de propriétés utilisateur. Consultez Tags de données pour plus de détails.

addTag(), addTags()

Définissez un ou plusieurs tags sur l’utilisateur actuel.
  • Les valeurs seront remplacées si la clé existe déjà.
  • Dépasser la limite de tags de votre plan entraînera l’échec silencieux des opérations.
JavaScript

removeTag(), removeTags()

Supprimez un ou plusieurs tags de l’utilisateur actuel.
JavaScript

getTags()

Renvoie la copie locale des tags de l’utilisateur. Les tags sont mis à jour depuis le serveur pendant login() ou les nouvelles sessions d’application.
JavaScript

Confidentialité

setConsentRequired()

Impose le consentement de l’utilisateur avant le début de la collecte de données. Doit être appelé avant l’initialisation du SDK. Cette méthode est identique à l’ajout de requiresUserPrivacyConsent: true à la méthode init.
JavaScript

setConsentGiven()

Accorde ou révoque le consentement de l’utilisateur pour la collecte de données. Sans consentement, aucune donnée n’est envoyée à OneSignal et aucun abonnement n’est créé.
  • Si setConsentRequired() ou requiresUserPrivacyConsent est défini sur true, notre SDK ne sera pas complètement activé jusqu’à ce que setConsentGiven soit appelé avec true.
  • Si setConsentGiven est défini sur true et qu’un abonnement est créé, puis qu’il est ensuite défini sur false, cet abonnement ne recevra plus de mises à jour. Les données actuelles de cet abonnement restent inchangées jusqu’à ce que setConsentGiven soit à nouveau défini sur true.
  • Si vous souhaitez supprimer les données utilisateur et/ou d’abonnement, utilisez nos API Delete user ou Delete subscription.
JavaScript

Abonnements

Consultez Abonnements pour plus de détails.

User.PushSubscription.id

Récupère l’ID d’abonnement push de l’utilisateur actuel enregistré localement dans le navigateur. Peut renvoyer null si appelé trop tôt. Il est recommandé d’obtenir ces données dans l’observateur d’abonnement pour réagir aux changements.
JavaScript

User.PushSubscription.token

Renvoie le token d’abonnement push actuel. Peut renvoyer null si appelé trop tôt. Il est recommandé d’obtenir ces données dans l’observateur d’abonnement pour réagir aux changements.
JavaScript

addEventListener() changements d’abonnement push

Utilisez cette méthode pour répondre aux changements d’abonnement push comme :
  • L’appareil reçoit un nouveau token push de Google (FCM) ou Apple (APNs)
  • OneSignal attribue un ID d’abonnement
  • La valeur optedIn change (par exemple appelé optIn() ou optOut())
  • L’utilisateur bascule la permission push dans les paramètres système, puis ouvre l’application
Lorsque cela se produit, le SDK déclenche l’événement onPushSubscriptionChange. Votre listener reçoit un objet d’état avec les valeurs previous et current afin que vous puissiez détecter exactement ce qui a changé. Pour arrêter d’écouter les mises à jour, appelez la méthode removeObserver() ou removeEventListener() associée.
JavaScript

optOut(), optIn(), optedIn

Contrôle le statut d’abonnement (subscribed ou unsubscribed) de l’abonnement push actuel. Utilisez ces méthodes pour contrôler le statut d’abonnement push sur votre site. Cas d’utilisation courants : 1) Empêcher l’envoi de push aux utilisateurs qui se déconnectent. 2) Implémenter un centre de préférences de notification au sein de votre site.
  • optOut() : Définit le statut d’abonnement push actuel sur désabonné (même si l’utilisateur a un token push valide).
  • optIn() : Effectue l’une des trois actions suivantes :
    1. Si l’abonnement dispose d’un token push valide, il définit le statut d’abonnement push actuel sur subscribed.
    2. Si l’abonnement ne dispose pas d’un token push valide, il tente d’afficher l’invite de permission push.
  • optedIn : Renvoie true si le statut d’abonnement push actuel est abonné, sinon false. Si le token push est valide mais que optOut() a été appelé, cela renverra false.
JavaScript

addEmail(), removeEmail()

Ajoute ou supprime un abonnement email (adresse email) à/de l’utilisateur actuel. Appelez addEmail après login() pour définir le bon contexte utilisateur. Compatible avec la Vérification d’identité.
JavaScript

addSms(), removeSms()

Ajoute ou supprime un abonnement SMS (numéro de téléphone) à/de l’utilisateur actuel. Nécessite le format E.164. Appelez addSms après login() pour définir le bon contexte utilisateur. Compatible avec la Vérification d’identité.
JavaScript

Invites déroulantes

Affichez les diverses invites déroulantes sur vos sites. Consultez Invites de permission web pour plus de détails.
  • Si rejetée, les futurs appels seront ignorés pendant au moins trois jours. D’autres refus allongeront le temps nécessaire avant de solliciter à nouveau l’utilisateur.
  • Pour contourner le comportement de back-off, passez {force: true} à la méthode. Cependant, pour offrir une bonne expérience utilisateur, liez l’action à un événement initié par l’interface utilisateur comme un clic de bouton.
Cela ne remplace pas l’invite native du navigateur requise pour l’abonnement. Vous devez obtenir les permissions en utilisant l’invite native du navigateur.

promptPush()

Affiche l’invite déroulante régulière pour les notifications push.
JavaScript

promptPushCategories()

Affiche l’invite déroulante de catégorie, permettant aux utilisateurs de mettre à jour leurs tags. Déclenche également l’invite native de permission de notification si l’utilisateur n’a pas déjà accordé la permission.
  • Si vous n’utilisez pas de catégories, appelez plutôt promptPush().
  • Soumis à la logique de back-off définie par OneSignal. Consultez Invites de permission web pour plus de détails.
JavaScript

promptSms()

Affiche l’invite d’abonnement SMS.
JavaScript

promptEmail()

Affiche l’invite d’abonnement email.
JavaScript

promptSmsAndEmail()

Affiche simultanément les invites d’abonnement SMS et email.
JavaScript

addEventListener() Slidedown

Ajoutez un callback pour détecter l’événement d’affichage de l’invite Slidedown.
JavaScript

Notifications push

requestPermission()

Demande la permission de notifications push via l’invite native du navigateur. Soumis à la logique de back-off définie par le navigateur. Consultez Invites de permission web pour plus de détails.
JavaScript

isPushSupported()

Renvoie true si le navigateur actuel prend en charge le push web.
JavaScript

OneSignal.Notifications.permission

Renvoie un booléen indiquant la permission actuelle du site pour afficher des notifications.
  • true : L’utilisateur a accordé la permission d’afficher des notifications.
  • false : L’utilisateur a soit refusé, soit n’a pas encore accordé la permission d’afficher des notifications.
Ceci est juste la permission du site, ne prend pas en compte le statut optOut de OneSignal ou l’existence de l’ID d’abonnement et du token push, consultez OneSignal.User.PushSubscription pour ceux-ci. Pour écouter les changements de permission, utilisez l’événement permissionChange.
JavaScript

addEventListener() notifications

Vous pouvez vous connecter au cycle de vie des notifications en attachant vos gestionnaires d’événements à un événement de notification. Appeler addEventListener vous permet d’ajouter un nombre arbitraire de gestionnaires d’événements pour les événements de notification. Pour arrêter d’écouter les événements, appelez la méthode removeEventListener() associée.
JavaScript

permissionChange

Cet événement se produit lorsque l’utilisateur clique sur Autoriser ou Bloquer ou rejette la demande de permission native du navigateur.
JavaScript

permissionPromptDisplay

Cet événement se produit lorsque la demande de permission native du navigateur vient d’être affichée.
JavaScript

click

Cet événement se déclenchera lorsque le corps/titre de la notification ou les boutons d’action sont cliqués.
JavaScript

foregroundWillDisplay

Cet événement se produit avant qu’une notification ne s’affiche. Cet événement est déclenché sur votre page. Si plusieurs onglets de navigateur sont ouverts sur votre site, cet événement sera déclenché sur toutes les pages sur lesquelles OneSignal est actif.
JavaScript

dismiss

Cet événement se produit lorsque :
  • Un utilisateur rejette intentionnellement la notification sans cliquer sur le corps de la notification ou les boutons d’action
  • Sur Chrome sur Android, un utilisateur rejette toutes les notifications push web (cet événement sera déclenché pour chaque notification push web que nous affichons)
  • Une notification expire d’elle-même et disparaît
Cet événement ne se produit pas si un utilisateur clique sur le corps de la notification ou sur l’un des boutons d’action. Cela est considéré comme un événement click de notification.
JavaScript

setDefaultUrl()

Définit l’URL par défaut pour les notifications. Si vous n’avez pas défini d’URL par défaut, votre notification s’ouvrira à la racine de votre site par défaut.
JavaScript
Pour définir l’URL par défaut des notifications, fournissez une URL valide que vous souhaitez lancer lorsque la notification est cliquée. Cette URL par défaut sera utilisée si aucune autre URL n’est spécifiée lors de la création d’une notification. Si vous spécifiez une URL lors de la création d’une notification, l’URL par défaut sera remplacée. Dans le cas de Safari, l’URL de l’icône de notification par défaut sera définie sur l’URL du site que vous avez spécifiée dans vos paramètres Safari, car cette fonction n’est pas disponible.

setDefaultTitle()

Définit le titre par défaut à afficher sur les notifications.
JavaScript
Si une notification est créée avec un titre, le titre spécifié remplace toujours ce titre par défaut. Le titre d’une notification est par défaut le titre de la dernière page visitée par l’utilisateur. Si les titres de vos pages varient d’une page à l’autre, cette incohérence peut être indésirable. Appelez ceci pour standardiser les titres de page sur les notifications, tant qu’un titre de notification n’est pas spécifié.

Résultats

sendOutcome()

Déclenche un résultat qui peut être consulté dans le tableau de bord OneSignal. Accepte un nom de résultat (string, requis) et une valeur (number, optionnel). Chaque fois que la méthode sendOutcome est invoquée avec le même nom de résultat transmis, le nombre de résultats augmentera, et la valeur du résultat sera augmentée du montant transmis (s’il est inclus). Consultez Résultats personnalisés pour plus de détails.
JavaScript

sendUniqueOutcome()

Déclenche un résultat qui peut être consulté dans le tableau de bord OneSignal. Accepte uniquement le nom du résultat (string, requis). sendUniqueOutcome augmentera le nombre pour ce résultat une seule fois par utilisateur. Consultez Résultats personnalisés pour plus de détails.
JavaScript