Référence du SDK Web

​

Configuration et débogage

​

init()

window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "ONESIGNAL_APP_ID",
  });
});

​

Paramètres promptOptions

​

Paramètres notifyButton

​

Paramètres welcomeNotification

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "YOUR_APP_ID",
    notifyButton: {
      enable: true,
    },
    promptOptions: {
      slidedown: {
        prompts: [{
            type: "smsAndEmail",
            autoPrompt: false,
            text: {
              emailLabel: "Insert Email Address",
              smsLabel: "Insert Phone Number",
              acceptButton: "Submit",
              cancelButton: "No Thanks",
              actionMessage: "Receive the latest news, updates and offers as they happen.",
              updateMessage: "Update your push notification subscription preferences.",
              confirmMessage: "Thank You!",
              positiveUpdateButton: "Save Preferences",
              negativeUpdateButton: "Cancel",
            },
            delay: {
              pageViews: 1,
              timeDelay: 20
            },
          },
          {
            type: "category",
            autoPrompt: true,
            text: {
              actionMessage: "We'd like to show you notifications for the latest news and updates.",
              acceptButton: "Allow",
              cancelButton: "Cancel",

              /* CATEGORY SLIDEDOWN SPECIFIC TEXT */
              negativeUpdateButton: "Cancel",
              positiveUpdateButton: "Save Preferences",
              updateMessage: "Update your push notification subscription preferences.",
            },
            delay: {
              pageViews: 3,
              timeDelay: 20
            },
            categories: [{
                tag: "politics",
                label: "Politics"
              },
              {
                tag: "local_news",
                label: "Local News"
              },
              {
                tag: "world_news",
                label: "World News",
              },
              {
                tag: "culture",
                label: "Culture"
              },
            ]
          }
        ]
      }
    }
  });
});
</script>

​

setLogLevel()

  OneSignal.Debug.setLogLevel("trace");

• 'trace'
• 'debug'
• 'info'
• 'warn'
• 'error'

​

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

​

login(external_id)

• Le SDK bascule vers cet utilisateur existant.
  • Vous pouvez voir un 409 Conflict dans le journal réseau ou la console du navigateur. Cela signifie que l’External ID existe déjà dans l’application ; c’est attendu dans ce cas et il ne s’agit généralement pas d’un rejet de promesse que vous devez gérer.
• Le onesignal_id actuel est abandonné et le onesignal_id existant de cet utilisateur est chargé.
• L’appareil actuel (abonnement push web) est lié à l’utilisateur existant.
• Les données anonymes collectées avant la connexion ne sont pas fusionnées et sont supprimées. Cela inclut les tags, les données de session, les abonnements email/SMS et les autres propriétés utilisateur locales.

• Un nouvel utilisateur est créé avec le onesignal_id actuel.
• Toutes les données collectées lorsque l’utilisateur était anonyme sont conservées.
• L’appareil (abonnement push web) devient lié à ce nouvel utilisateur.

• Le SDK réessaie automatiquement la requête de connexion en cas d’échecs réseau ou d’erreurs serveur.
• Vous n’avez pas besoin d’implémenter votre propre logique de réessai.

• Appelez login(external_id) à chaque chargement de page une fois que vous connaissez l’ID de l’utilisateur (par exemple, après la connexion ou la restauration de session).
• Appelez-la à nouveau chaque fois que l’utilisateur connecté change (changement de compte).
• N’appelez pas login avant de disposer d’un identifiant utilisateur stable et connu.

OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.login("external_id");
});

​

logout()

• Supprime l’external_id de l’abonnement push web actuel. Ne supprime pas l’external_id des autres abonnements.
• Réinitialise le onesignal_id 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.

OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.logout();
});

​

OneSignal.User.onesignalId

• Après que le SDK OneSignal a terminé son initialisation
• Après qu’un utilisateur est identifié avec login(external_id)
• Après un changement d’utilisateur ou une restauration de session

• Suivre les utilisateurs anonymes avant qu’un External ID ne soit défini
• Stocker le OneSignal ID dans votre backend pour le support ou le débogage
• Corréler les utilisateurs OneSignal avec les journaux internes
• Afficher l’ID pour le dépannage ou l’assurance qualité

const onesignalId = OneSignal.User.onesignalId;

​

OneSignal.User.externalId

  const externalId = OneSignal.User.externalId;

​

addEventListener() État utilisateur

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.addEventListener('change', function (event) {
      console.log('change', { event });
    });
  });

​

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

• 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.

  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  OneSignal.User.addAliases({
    ALIAS_LABEL_01: "ALIAS_ID_01",
    ALIAS_LABEL_02: "ALIAS_ID_02",
    ALIAS_LABEL_03: "ALIAS_ID_03",
  });

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02", "ALIAS_LABEL_03"]);

​

getLanguage(), setLanguage()

  // Get the language of the currently logged-in user
  OneSignal.User.getLanguage();

  // Set the language of the currently logged-in user
  OneSignal.User.setLanguage("en");

​

Événements personnalisés

• 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": {
    "device_os": "138",
    "type": "ChromePush",
    "device_model": "MacIntel",
    "sdk": "160500"
  }
}

​

trackEvent()

OneSignalDeferred.push(async function (OneSignal) {
  await OneSignal.init({ appId: "ONESIGNAL_APP_ID" });

  const properties = {
    promo_code: "NEW50",
    membership_details: {
      vip: true,
      products_viewed_count: 15,
    },
  };
  OneSignal.User.trackEvent("started_free_trial", properties);

  // Event name only (no properties)
  OneSignal.User.trackEvent("my_event_name");
});

​

Tags

​

addTag(), addTags()

• 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.

  // Add a single tag
  OneSignal.User.addTag('tag_key', 'tag_value');

  // Add multiple tags
  OneSignal.User.addTags({
   KEY_01: "VALUE_01",
   KEY_02: "VALUE_02",
   KEY_03: "VALUE_03"
  });

​

removeTag(), removeTags()

  // Delete a single tag
  OneSignal.User.removeTag("KEY");

  OneSignal.User.removeTags(['KEY_01', 'KEY_02', 'KEY_03']);

​

getTags()

  const tags = OneSignal.User.getTags()

​

Confidentialité

​

setConsentRequired()

  OneSignal.setConsentRequired(true);

​

setConsentGiven()

• 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.

  OneSignal.setConsentGiven(true);

​

Abonnements

​

User.PushSubscription.id

  const subscription_id = OneSignal.User.PushSubscription.id;

​

User.PushSubscription.token

  OneSignal.User.PushSubscription.token;

​

addEventListener() Changements d’abonnement push

• 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 après un appel à optIn() ou optOut())
• L’utilisateur bascule la permission push dans les paramètres du navigateur ou du système d’exploitation, puis revient sur votre site

  function pushSubscriptionChangeListener(event) {
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

  function pushSubscriptionChangeListener(event) {
    if (!event.current.token || event.previous.token) {
      return;
    }
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "onesignal_push_subscribed",
      onesignal_subscription_id: event.current.id,
    });
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

​

optOut(), optIn(), optedIn

• 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 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.

  OneSignal.User.PushSubscription.optOut();

  OneSignal.User.PushSubscription.optIn();

  var optedIn = OneSignal.User.PushSubscription.optedIn;

​

addEmail(), removeEmail()

• L’adresse email devient un abonnement email pour l’utilisateur actuel.
• L’email peut être créé ou réattribué.
• La même adresse email ne peut pas exister plusieurs fois dans la même application OneSignal. Si vous voyez des adresses email en double, vérifiez vos requêtes API REST et contactez le support si nécessaire.

• L’abonnement email est supprimé de l’utilisateur actuel.
• L’External ID actuel est supprimé de l’abonnement email.
• Un nouveau OneSignal ID est attribué à l’abonnement email.
• Les autres abonnements (push, SMS, autres emails) ne sont pas affectés.

• Appelez d’abord login(), puis appelez addEmail(). Sinon, l’email peut être rattaché à un utilisateur anonyme.
• Utilisez une adresse email stable et vérifiée.
• Suivez les Bonnes pratiques de réputation email.

  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");

​

addSms(), removeSms()

• Le numéro de téléphone devient un abonnement SMS pour l’utilisateur actuel.
• Le numéro peut être créé ou réattribué.
• Le même numéro de téléphone ne peut pas exister plusieurs fois dans la même application OneSignal. Si vous voyez des numéros de téléphone en double, vérifiez vos requêtes API REST et contactez le support si nécessaire.

• L’abonnement SMS est supprimé de l’utilisateur actuel.
• L’External ID actuel est supprimé de l’abonnement SMS.
• Un nouveau OneSignal ID est attribué à l’abonnement SMS.
• Les autres abonnements (push, email, autres SMS) ne sont pas affectés.

• Appelez d’abord login(), puis appelez addSms(). Sinon, l’abonnement SMS peut être rattaché à un utilisateur anonyme.
• Validez et normalisez toujours les numéros de téléphone au format E.164 avant l’envoi.
• Suivez les Exigences d’enregistrement SMS.

  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");

​

Invites slidedown

• 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()

• Si vous utilisez des catégories, appelez plutôt promptPushCategories().
• Soumis à la logique de back-off définie par OneSignal. Consultez Invites d’autorisation web pour plus de détails.

  OneSignal.Slidedown.promptPush();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPush({force: true});

​

promptPushCategories()

• Si vous n’utilisez pas de catégories, appelez plutôt promptPush().
• Soumis à la logique de back-off définie par OneSignal. Consultez Invites d’autorisation web pour plus de détails.

  OneSignal.Slidedown.promptPushCategories();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPushCategories({force: true});

​

promptSms()

• Soumis à la logique de back-off définie par OneSignal. Consultez Invites d’autorisation web pour plus de détails.

  OneSignal.Slidedown.promptSms();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSms({force: true});

​

promptEmail()

• Soumis à la logique de back-off définie par OneSignal. Consultez Invites d’autorisation web pour plus de détails.

  OneSignal.Slidedown.promptEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptEmail({force: true});

​

promptSmsAndEmail()

• Soumis à la logique de back-off définie par OneSignal. Consultez Invites d’autorisation web pour plus de détails.

  OneSignal.Slidedown.promptSmsAndEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSmsAndEmail({force: true});

​

addEventListener() Slidedown

  OneSignalDeferred.push(function(OneSignal) {

    OneSignal.Slidedown.addEventListener('slidedownShown', function (event) {
      console.log('slidedownShown', { event });
    });

  });

​

Notifications push

​

requestPermission()

  OneSignal.Notifications.requestPermission();

​

isPushSupported()

  const isSupported = OneSignal.Notifications.isPushSupported();

​

OneSignal.Notifications.permission

• 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.

  let permission = OneSignal.Notifications.permission;

​

addEventListener() Notifications

  function onClick(event) {
    console.log("click", event);
  }

  OneSignal.Notifications.addEventListener("click", onClick);
  OneSignal.Notifications.removeEventListener("click", onClick);

​

permissionChange

  function permissionChangeListener(permission) {
    if (permission) {
      console.log(`permission accepted!`);
    }
  }

  OneSignal.Notifications.addEventListener("permissionChange", permissionChangeListener);

​

permissionPromptDisplay

  function promptListener(event) {
    console.log("permission prompt displayed", event);
  }

  OneSignal.Notifications.addEventListener("permissionPromptDisplay", promptListener);

​

click

  function clickEventListener(event) {
    console.log(`click event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("click", clickEventListener);

​

foregroundWillDisplay

  function foregroundWillDisplayListener(event) {
    console.log("notification will display", event);
  }

  OneSignal.Notifications.addEventListener("foregroundWillDisplay", foregroundWillDisplayListener);

​

dismiss

• 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

  function notificationDismissedListener(event) {
    console.log(`dismiss event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("dismiss", notificationDismissedListener);

​

setDefaultUrl()

  OneSignal.Notifications.setDefaultUrl("https://onesignal.com");

​

setDefaultTitle()

  OneSignal.Notifications.setDefaultTitle("Powered by OneSignal!");

​

Résultats

​

sendOutcome()

  OneSignal.Session.sendOutcome('outcome name', 19.84);

​

sendUniqueOutcome()

  OneSignal.Session.sendUniqueOutcome('outcome name');