Configuration et débogage
Vous remarquerez peut-être la nécessité d’envelopper vos appels OneSignal avecOneSignalDeferred.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é.
| Parameter | Type | Description |
|---|---|---|
appId | String | Required: Your OneSignal App ID found in Keys & IDs. |
requiresUserPrivacyConsent | Boolean | Delays SDK initialization until the user provides privacy consent. Must call setConsentGiven() to complete setup. |
safari_web_id | String | The Safari Web ID for your uploaded Safari .p12 certificate. Web Quickstart. |
promptOptions | Object | Customize the permission prompts. Details below. |
notifyButton | Object | Enable and configure the Subscription Bell. Details below. |
welcomeNotification | Object | Customize or disable the welcome notification. Details below. |
persistNotification | Boolean | Chrome (desktop only) - true: notification persists until clicked, false: disappears after a short time. Firefox/Safari ignore this setting. |
webhooks | Object | Configure event callbacks. See Webhooks. |
autoResubscribe | Boolean | Recommended: Auto-resubscribes users who clear browser cache or migrate to OneSignal. Overrides dashboard setting if used in code. |
notificationClickHandlerMatch | String | "exact" (default): focuses tab with an exact URL match. "origin": focuses any tab with the same domain. |
notificationClickHandlerAction | String | "navigate" (default): navigates to launchURL. "focus": focuses existing tab (only used with "origin" match). |
serviceWorkerParam | Object | Set the scope of the service worker. Must be different from other service worker’s scope if applicable. Example:{ scope: "/myPath/myCustomScope/" } |
serviceWorkerPath | String | Set the location of the OneSignal service worker file. Example:"myPath/OneSignalSDKWorker.js" |
promptOptions parameters
Use promptOptions to localize or customize the user permission prompts. All fields are optional.
| Parameter | Type | Description |
|---|---|---|
slidedown | Object | Contains an array of prompts with configuration options. |
prompts | Array of Objects | An array of prompt configurations. Example:"slidedown": { "prompts": [{...}, {...}] } |
type | String | Prompt types:
|
autoPrompt | Boolean |
|
delay | Object | Controls when auto-prompt is shown:{ pageViews: 3, timeDelay: 20 } = Show after 3rd pageview and 20s wait. |
text | Object | Custom text options:
|
categories | Array of Objects | Only for type: category. Each object includes:tag: internal keylabel: user-visible nameExample: [ {tag: "local_news", label: "Local News"} ]. See Data Tags. |
notifyButton parameters
Configure the Subscription Bell (notify button) shown on the page.
| Parameter | Type | Description |
|---|---|---|
enable | Boolean | Enables the Subscription Bell. Disabled by default. |
displayPredicate | Function | Custom function (or Promise) that returns true or false to show/hide the Bell. Evaluated once when shown. |
size | String | 'small', 'medium', or 'large'. Shrinks to 'small' after subscription. |
position | String | 'bottom-left' or 'bottom-right'. |
offset | Object | CSS pixel offsets: { bottom: '50px', left: '10px' } |
prenotify | Boolean | If true, shows a “1 unread” icon and custom hover text. |
showCredit | Boolean | Set to false to hide “Powered by OneSignal” in the popup. |
text | Object | Custom text for the bell UI. |
welcomeNotification parameters
Customize the welcome notification sent after first-time subscription.
| Parameter | Type | Description |
|---|---|---|
disable | Boolean | Disable welcome notification. |
message | String | Required: Notification message. Defaults to 'Thanks for subscribing!' if blank. |
title | String | Notification title. Defaults to site title. Use ' ' (space) to remove (not recommended). |
url | URL | Optional URL to open when the user clicks the notification. Typically not needed. |
Example:
setLogLevel()
Set the logging to print additional logs to the console. See Debugging with Browser DevTools for more details.
JavaScript
'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 appelantlogin() 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_idexiste 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_idn’existe pas, l’état local sera enregistré sous l’onesignal_idactuel. 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_idde 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_idaveclogin()avant d’ajouter des alias. Les alias ajoutés aux abonnements sansexternal_idne 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.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.
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éesclé : 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()ourequiresUserPrivacyConsentest défini surtrue, notre SDK ne sera pas complètement activé jusqu’à ce quesetConsentGivensoit appelé avectrue. - Si
setConsentGivenest défini surtrueet qu’un abonnement est créé, puis qu’il est ensuite défini surfalse, cet abonnement ne recevra plus de mises à jour. Les données actuelles de cet abonnement restent inchangées jusqu’à ce quesetConsentGivensoit à nouveau défini surtrue. - 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
optedInchange (par exemple appeléoptIn()ouoptOut()) - L’utilisateur bascule la permission push dans les paramètres système, puis ouvre l’application
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 :- Si l’abonnement dispose d’un token push valide, il définit le statut d’abonnement push actuel sur
subscribed. - Si l’abonnement ne dispose pas d’un token push valide, il tente d’afficher l’invite de permission push.
- Si l’abonnement dispose d’un token push valide, il définit le statut d’abonnement push actuel sur
optedIn: Renvoietruesi le statut d’abonnement push actuel est abonné, sinonfalse. Si le token push est valide mais queoptOut()a été appelé, cela renverrafalse.
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.
promptPush()
Affiche l’invite déroulante régulière pour les notifications push.
- Si vous utilisez des catégories, appelez plutôt
promptPushCategories(). - Soumis à la logique de back-off définie par OneSignal. Consultez Invites de permission web pour plus de détails.
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.
- Soumis à la logique de back-off définie par OneSignal. Consultez Invites de permission web pour plus de détails.
JavaScript
promptEmail()
Affiche l’invite d’abonnement email.
- Soumis à la logique de back-off définie par OneSignal. Consultez Invites de permission web pour plus de détails.
JavaScript
promptSmsAndEmail()
Affiche simultanément les invites d’abonnement SMS et email.
- Soumis à la logique de back-off définie par OneSignal. Consultez Invites de permission web pour plus de détails.
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.
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
setDefaultTitle()
Définit le titre par défaut à afficher sur les notifications.
JavaScript
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