SDK Web Push 3.0
Intégration
Anchor link toExemple d’intégration sur GitHub
Obtenez le SDK Web Push de Pushwoosh et décompressez-le. Vous devriez avoir les fichiers suivants :
Anchor link to- pushwoosh-service-worker.js
Placez tous ces fichiers à la racine de premier niveau du répertoire de votre site web.
Anchor link toInitialisez le SDK :
Anchor link to- Incluez le SDK depuis notre CDN de manière asynchrone.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>- Initialisez le SDK Web Push et assurez-vous de mettre l’initialisation en file d’attente jusqu’à ce que le SDK soit entièrement chargé.
<script type="text/javascript">var Pushwoosh = Pushwoosh || [];Pushwoosh.push(['init', { logLevel: 'info', // possible values: error, info, debug applicationCode: 'XXXXX-XXXXX', // you application code from Pushwoosh Control Panel apiToken: 'XXXXXXX', // Device API Token safariWebsitePushID: 'web.com.example.domain', // chaîne de domaine inversé unique, obtenue dans votre Apple Developer Portal. Utilisé uniquement si votre application dispose de la section Safari Configuration (voir Prérequis ci-dessus) defaultNotificationTitle: 'Pushwoosh', // sets a default title for push notifications defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL to custom custom notification image autoSubscribe: false, // or true. If true, prompts a user to subscribe for pushes upon SDK initialization subscribeWidget: { enable: true }, userId: 'user_id', // optional, set custom user ID tags: { 'Name': 'John Smith' // optional, set custom Tags }}]);</script>Pop-ups web
Anchor link toLes campagnes de pop-ups web se chargent par défaut — aucune entrée webPopups n’est requise dans votre objet init. N’en ajoutez une que pour vous désinscrire ou modifier les valeurs par défaut :
webPopups: { // enable: false, // optional, opt out entirely: the bundle is never loaded autoShow: true, // optional, set to false to load popups without displaying them automatically — see WebPopups methods below colorScheme: 'auto', // optional, 'auto' (default) | 'light' | 'dark'},Les campagnes de pop-ups web affichent des superpositions que vous configurez dans le panneau de contrôle, telles que des promotions, des annonces ou des formulaires de capture de prospects. Contrairement à la fenêtre contextuelle d’abonnement personnalisée (subscribePopup), qui ne gère que l’acceptation des notifications push web, les campagnes de pop-ups web peuvent afficher n’importe quel contenu que vous configurez.
Pour la configuration dans le panneau de contrôle, consultez Comprendre les pop-ups web.
colorScheme choisit la palette avec laquelle un pop-up configuré avec le mode sombre s’affiche :
'auto'(par défaut) : suit le thème de couleurs du système d’exploitation du visiteur (prefers-color-scheme).'light'ou'dark': affiche toujours cette palette, quel que soit le paramètre du système d’exploitation du visiteur.
Un pop-up sans mode sombre configuré dans l’éditeur s’affiche toujours en mode clair — colorScheme n’a aucun effet sur lui.
Pour un contrôle programmatique, consultez les méthodes WebPopups et les événements de pop-up web.
Bouton d’abonnement aux notifications push
Anchor link toPour inviter vos utilisateurs à s’abonner aux notifications push, nous vous recommandons d’implémenter un bouton d’abonnement aux notifications push sur votre site web. Améliorez l’expérience utilisateur et obtenez plus d’abonnés !
Configuration
Anchor link toPour terminer l’implémentation des notifications push sur votre site web, vous devez configurer les plateformes web dans votre panneau de contrôle Pushwoosh en suivant nos guides étape par étape :
Le même écran de configuration inclut également une carte Web SDK configuration.
Enregistrement du service worker dans une portée différente
Anchor link toParfois, vous ne pouvez pas placer le fichier du service worker dans le répertoire racine d’un site web, mais dans un sous-répertoire.
Dans ce cas, modifiez la configuration (étape 4.3) en ajoutant un paramètre
serviceWorkerUrl: “/push-notifications/pushwoosh-service-worker.js”
où /push-notifications/pushwoosh-service-worker.js est le chemin d’accès au fichier pushwoosh-service-worker.js.
Gestionnaires d’événements
Anchor link toDans le SDK Web Push 3.0 de Pushwoosh, vous pouvez vous abonner à certains événements pour les suivre**,** ou vous désabonner des événements si vous n’avez plus besoin de les suivre.
Pour suivre le chargement du SDK Web 3.0, déclenchez l’événement onLoad comme suit :
// Load EventPushwoosh.push(['onLoad', (api) => { console.log('Pushwoosh load!');}]);Pour suivre l’initialisation correcte du SDK Web, déclenchez l’événement onReady :
// Ready EventPushwoosh.push((api) => { console.log('Pushwoosh ready!');});Pour vous abonner ou vous désabonner de l’un des événements du SDK, utilisez les gestionnaires après le chargement du SDK :
Pushwoosh.push(['onLoad', (api) => { function onEventNameHandler() { console.log('Triggered event: event-name!'); }
// To subscribe to an event: Pushwoosh.addEventHandler('event-name', onEventNameHandler)
// To unsubscribe from an event: Pushwoosh.removeEventHandler('event-name', onEventNameHandler)}]);Événements du SDK
Anchor link toÉvénement d’abonnement
Anchor link toExécuté après qu’un utilisateur accepte de recevoir des notifications push.
Pushwoosh.push(['onLoad', (api) => { Pushwoosh.addEventHandler('subscribe', (payload) => { console.log('Triggered event: subscribe'); });}]);Événement de désabonnement
Anchor link toExécuté après qu’un appareil est désinscrit des notifications.
Pushwoosh.push(['onLoad', (api) => { Pushwoosh.addEventHandler('unsubscribe', (payload) => { console.log('Triggered event: unsubscribe'); });}]);Événements du widget d’abonnement
Anchor link toSuivre l’affichage d’un widget d’invite d’abonnement.
Pushwoosh.push(['onLoad', (api) => { // Executed on displaying of the Subscription Prompt widget Pushwoosh.addEventHandler('show-subscription-widget', (payload) => { console.log('Triggered event: show-subscription-widget'); });
// Executed on hiding of the Subscription Prompt widget Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => { console.log('Triggered event: hide-subscription-widget'); });}]);Événements de la boîte de dialogue d’autorisation de notification
Anchor link toSuivre l’affichage de la boîte de dialogue d’abonnement native.
Pushwoosh.push(['onLoad', function (api) { // Executed on permission dialog displaying Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => { console.log('Triggered event: show-notification-permission-dialog'); });
// Executed on hiding the permission dialog with one of three possible statuses: // 1. default - the dialog is closed // 2. granted - permission is granted // 3. denied - permission is denied Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => { console.log('Triggered event: hide-notification-permission-dialog', payload.permission); });}]);Événements d’autorisation
Anchor link toVérifier l’état de l’autorisation des notifications push lors de l’initialisation du SDK ; suivre la mise à jour de cet état chaque fois qu’elle a lieu.
Pushwoosh.push(['onLoad', (api) => { // Executed during the SDK initialization if 'autoSubscribe: false' or/and if a user ignores a push notification prompt. Pushwoosh.addEventHandler('permission-default', (payload) => { console.log('Triggered event: permission-default'); });
// Executed during the SDK initialization if notifications are blocked or once a user blocks push notifications. Pushwoosh.addEventHandler('permission-denied', (payload) => { console.log('Triggered event: permission-denied'); });
// Executed during the SDK initialization if notifications are allowed or once a user allows push notifications. Pushwoosh.addEventHandler('permission-granted', (payload) => { console.log('Triggered event: permission-granted'); });}]);Événement de réception de push
Anchor link toSuivre la livraison d’une notification push à un appareil.
Pushwoosh.push(['onLoad', (api) => { // Executed when a push notification is displayed. Pushwoosh.addEventHandler('receive-push', (payload) => { console.log('Triggered event: receive-push', payload.notification); });}]);Événements de notification
Anchor link toSuivre si une notification push est ouverte ou fermée par un utilisateur.
Pushwoosh.push(['onLoad', (api) => { // Executed when a user clicks on notification. Pushwoosh.addEventHandler('open-notification', (payload) => { console.log('Triggered event: open-notification', payload.notification); });
// Executed when a user closes a push notification. Pushwoosh.addEventHandler('hide-notification', (payload) => { console.log('Triggered event: hide-notification', payload.notification); });}]);Événements de la boîte de réception
Anchor link toSuivre les notifications envoyées à la boîte de réception.
Pushwoosh.push(['onLoad', (api) => { // Executed by ServiceWorker after the Inbox Message is received and saved to indexedDB. Pushwoosh.addEventHandler('receive-inbox-message', (payload) => { console.log('Triggered event: receive-inbox-message', payload.message); });
// Executed after the Inbox is updated automatically while the page is loading. Pushwoosh.addEventHandler('update-inbox-messages', (payload) => { console.log('Triggered event: receive-inbox-message', payload.messages); });}]);Événements de la fenêtre contextuelle d’abonnement personnalisée
Anchor link toPour plus de détails sur la gestion des événements de la fenêtre contextuelle d’abonnement personnalisée, veuillez consulter le Guide des événements de la fenêtre contextuelle d’abonnement personnalisée.
Événements de pop-up web
Anchor link toPushwoosh.push(['onLoad', (api) => { // Executed once web popups have loaded and the automatic display pipeline has run for the current page Pushwoosh.addEventHandler('web-popups-ready', () => { console.log('Triggered event: web-popups-ready'); });
// Executed when a web popup is shown, automatically or via webPopups.show() Pushwoosh.addEventHandler('show-web-popup', (payload) => { console.log('Triggered event: show-web-popup', payload.code, payload.trigger); // trigger: 'auto' | 'api' });
// Executed when a web popup is hidden Pushwoosh.addEventHandler('hide-web-popup', (payload) => { console.log('Triggered event: hide-web-popup', payload.code, payload.reason); // reason: 'user' | 'api' | 'preempted' });}]);Une fois le SDK Web Push initialisé, vous pouvez effectuer les appels suivants à l’API Pushwoosh. Toutes les méthodes renvoient des objets Promise.
Pushwoosh.push((api) => { // Set tags for a user api.setTags({ 'Tag Name 1': 'value1', 'Tag Name 2': 'value2' });
// Get tags for a user from server api.getTags();
// Register user ID api.registerUser('user123');
// Register user email api.registerEmail('user@example.com');
// Register SMS number api.registerSmsNumber('+15551234567');
// Register WhatsApp number api.registerWhatsappNumber('+1234567890');
// Post an Event api.postEvent('myEventName', {attributeName: 'attributeValue'});
//Unregister from notifications api.unregisterDevice();
// Set the device language (overrides the value in the "Language" Tag) api.setLanguage('es');
// Alternatively Multi-register user with devices and channels api.multiRegisterDevice({ user_id: 'user123', email: 'user@example.com', sms_phone_number: '+1234567890', tags: { 'UserType': { operation: TTagOperationSet, value: 'Premium' }, 'Interests': { operation: TTagOperationAppend, values: ['sports', 'technology'] } } });});multiRegisterDevice
Anchor link toMéthode d’enregistrement améliorée qui permet d’enregistrer un profil utilisateur avec plusieurs appareils et canaux de messagerie en un seul appel API. Cette méthode est particulièrement utile pour les applications multiplateformes ou lors de la mise en œuvre de stratégies de messagerie omnicanal.
Pushwoosh.push((api) => { api.multiRegisterDevice({ user_id: 'user123', // Optional: User identifier email: 'user@example.com', // Optional: Email for email messaging sms_phone_number: '+1234567890', // Optional: SMS phone number (E.164 format) whatsapp_phone_number: '+1234567890', // Optional: WhatsApp number (E.164 format) kakao_phone_number: '+1234567890', // Optional: KakaoTalk number (E.164 format) language: 'en', // Optional: Language code (ISO 639-1) timezone: 'America/New_York', // Optional: Timezone identifier city: 'New York', // Optional: City for targeting country: 'US', // Optional: Country for targeting state: 'NY', // Optional: State for targeting tags: { // Optional: Tag values with operations 'UserType': { operation: TTagOperationSet, // Set tag value (0) value: 'Premium' }, 'Interests': { operation: TTagOperationAppend, // Append to tag value (1) values: ['sports', 'technology'] }, 'LoginCount': { operation: TTagOperationIncrement, // Increment tag value (3) value: '1' } }, push_devices: [ // Optional: Array of push devices { hwid: 'web-device-456', platform: TPlatformChrome, // Chrome platform (11) push_token: 'fcm-token-here', app_version: '2.1.0', platformData: { public_key: 'web-push-public-key', auth_token: 'web-push-auth-token', browser: 'chrome' } } ] }) .then((response) => { console.log('Multi-registration successful:', response); }) .catch((error) => { console.error('Multi-registration failed:', error); });});Types de plateformes :
TPlatformSafari(10) : Plateforme Safari. Les applications sans la section Configuration de Safari enregistrent les appareils Safari en tant queTPlatformChrome(11).TPlatformChrome(11) : Plateforme ChromeTPlatformFirefox(12) : Plateforme Firefox
Types d’opérations sur les tags :
TTagOperationSet(0) : Définir la valeur du tag (remplace la valeur existante)TTagOperationAppend(1) : Ajouter à la valeur du tag (ajouter à la liste)TTagOperationRemove(2) : Supprimer la valeur du tag (supprimer de la liste)TTagOperationIncrement(3) : Incrémenter la valeur du tag (incrément numérique)
Avantages :
- Appel API unique : Enregistrez plusieurs appareils et canaux en une seule fois
- Opération atomique : Tous les enregistrements réussissent ou échouent ensemble
- Centré sur l’utilisateur : Associe tous les appareils à un seul profil utilisateur
- Tagging avancé : Prend en charge les opérations complexes sur les tags
- Multiplateforme : Gérez plusieurs plateformes simultanément
Exemple d’envoi de Tags à Pushwoosh :
Pushwoosh.push((api) => { var myCustomTags = { 'Tag 1': 123, 'Tag 2': 'some string' }; api.setTags(myCustomTags) .then((res) => { var skipped = res && res.skipped || []; if (!skipped.length) { console.log('success'); } else { console.warn('skipped tags:', skipped); } }) .catch((err) => { console.error('setTags error:', err); });});Incrémenter la valeur d’un Tag
Anchor link toPour incrémenter une valeur d’un Tag de type Nombre, utilisez le paramètre operation avec la valeur ‘increment’ comme suit :
Pushwoosh.push((api) => { api.setTags({ 'Tag 1': { operation: 'increment', value: 1 } })});Ajouter des valeurs à un Tag
Anchor link toPour ajouter de nouvelles valeurs à un Tag de type Liste existant, utilisez le paramètre operation avec la valeur ‘append’ comme suit :
Pushwoosh.push((api) => { api.setTags({ 'Tag 3': { operation: 'append', value: ['Value3'] } })});Supprimer la valeur d’un Tag
Anchor link toPour supprimer une valeur d’un Tag de type Liste, utilisez le paramètre operation avec la valeur ‘remove’ comme suit :
Pushwoosh.push((api) =>{ api.setTags({ 'Tag 3': { operation: 'remove', value: ['Value2'] } })});Méthodes publiques
Anchor link toPushwoosh.subscribe()
Cette méthode est utilisée pour demander l’autorisation d’un utilisateur pour les notifications push. Si un utilisateur est déjà abonné, la méthode arrêtera son exécution.
Si un utilisateur ne s’est pas encore abonné aux notifications push :
1. L’autorisation pour les notifications push est demandée.

2. Si un utilisateur autorise les notifications, l’événement onSubscribe est déclenché.
Pushwoosh.subscribe() est exécuté automatiquement si autoSubscribe: true. est défini lors de l’initialisation du SDK.
Appelez cette méthode si vous avez choisi d’inviter manuellement un utilisateur à s’abonner aux notifications push en utilisant le paramètre autoSubscribe: false lors de l’initialisation :
<button onclick="Pushwoosh.subscribe()">S'abonner</button><script> Pushwoosh.push(['onSubscribe', (api) => { console.log('User successfully subscribed'); }]);</script>Pushwoosh.unsubscribe()
- La méthode
/unregisterDeviceest exécutée. - L’événement
onUnsubscribeest déclenché.
<button onclick="Pushwoosh.unsubscribe()">Se désabonner</button><script type="text/javascript"> Pushwoosh.push(['onUnsubscribe', (api) => { console.log('User successfully unsubscribed'); }]);</script>Pushwoosh.isSubscribed()
Vérifie si un utilisateur est abonné et renvoie un drapeau vrai/faux.
Pushwoosh.isSubscribed().then((isSubscribed) => { console.log('isSubscribed', isSubscribed);});Pushwoosh.getHWID()
Renvoie le HWID de Pushwoosh.
Pushwoosh.getHWID().then((hwid) => { console.log('hwid:', hwid);});Pushwoosh.getPushToken()
Renvoie le jeton de notification push s’il est disponible.
Pushwoosh.getPushToken().then((pushToken) => { console.log('pushToken:', pushToken);});Pushwoosh.getUserId()
Renvoie l’ID utilisateur si disponible.
Pushwoosh.getUserId().then((userId) => { console.log('userId:', userId);});Pushwoosh.getParams()
Renvoie une liste des paramètres suivants :
Pushwoosh.getParams().then((params) => { params = params || {}; var hwid = params.hwid; var pushToken = params.pushToken; var userId = params.userId;});Pushwoosh.isAvailableNotifications()
Vérifie si un navigateur prend en charge le WebSDK 3.0 de Pushwoosh, renvoie ‘vrai’ ou ‘faux’.
Pushwoosh.isAvailableNotifications() // true/falseMéthodes InboxMessages
Anchor link tomessagesWithNoActionPerformedCount(): Promise<number>
Renvoie le nombre de messages ouverts.
Pushwoosh.pwinbox.messagesWithNoActionPerformedCount() .then((count) => { console.log(`${count} messages opened`); });unreadMessagesCount()
Renvoie le nombre de messages non lus.
Pushwoosh.pwinbox.unreadMessagesCount() .then((count) => { console.log(`${count} messages unread`); });messagesCount(): Promise<number>
Renvoie le nombre total de messages.
Pushwoosh.pwinbox.messagesCount() .then((count) => { console.log(`${count} messages`); });loadMessages(): Promise<Array>
Charge la liste des messages non supprimés.
Pushwoosh.pwinbox.loadMessages() .then(() => { console.log('Messages have been loaded'); });readMessagesWithCodes(codes: Array<string>): Promise<void>
Marque les messages comme lus par Inbox_Ids.
Pushwoosh.pwinbox.readMessagesWithCodes(codes) .then(() => { console.log('Messages have been read'); });performActionForMessageWithCode(code: string): Promise<void>
Exécute l’action assignée à un message et marque le message comme lu.
Pushwoosh.pwinbox.performActionForMessageWithCode(code) .then(() => { console.log('Action has been performed'); });deleteMessagesWithCodes(codes: Array<string>): Promise<void>
Marque les messages comme supprimés.
Pushwoosh.pwinbox.deleteMessagesWithCodes([code]) .then(() => { console.log('Messages have been deleted'); });syncMessages(): Promise<void>
Synchronise les messages avec le serveur.
Pushwoosh.pwinbox.syncMessages() .then(() => { console.log('Messages have been synchronized'); });Méthodes WebPopups
Anchor link toL’API programmatique des pop-ups web est disponible chaque fois que le widget est chargé, ce qui est le comportement par défaut (voir ci-dessus). Accédez-y via Pushwoosh.moduleRegistry.webPopups une fois que l’événement web-popups-ready a été déclenché.
show(code: string): Promise<boolean>
Affiche un pop-up immédiatement, en contournant toutes les conditions d’affichage (délai, règles de page, type d’appareil/visiteur, limitation de fréquence, type de déclencheur). Ferme un pop-up déjà visible pour faire de la place. Résout à false au lieu de rejeter lorsque le pop-up ne peut pas être affiché.
Pushwoosh.moduleRegistry.webPopups.show('popup_code') .then((shown) => console.log('Popup shown:', shown));hide(code?: string): boolean
Masque le pop-up visible. Si code est passé, ne le masque que s’il correspond au pop-up visible. Renvoie false si rien n’a été masqué.
Pushwoosh.moduleRegistry.webPopups.hide();hideAll(): boolean
Masque le pop-up visible et rejette tout ce qui est encore en attente pour le chargement de la page actuelle. show() continue de fonctionner par la suite.
Pushwoosh.moduleRegistry.webPopups.hideAll();isVisible(code?: string): boolean
Vérifie si un pop-up est actuellement visible. Sans code, vérifie si un pop-up est visible.
Pushwoosh.moduleRegistry.webPopups.isVisible('popup_code');getVisibleCode(): string | null
Renvoie le code du pop-up actuellement à l’écran, ou null si aucun n’est visible.
Pushwoosh.moduleRegistry.webPopups.getVisibleCode();getAvailableCodes(): Array<string>
Renvoie les codes de chaque pop-up que le serveur a renvoyé pour cet appareil.
Pushwoosh.moduleRegistry.webPopups.getAvailableCodes();getState(): object
Renvoie un instantané de l’état du pop-up web : visible (code à l’écran, ou null), queued (codes en attente de l’emplacement d’affichage), waiting (codes avec un minuteur de délai armé), et available (chaque code que le serveur a renvoyé).
Pushwoosh.moduleRegistry.webPopups.getState();Prise en charge des Progressive Web App
Anchor link toPour intégrer Pushwoosh dans votre Progressive Web Application (PWA), suivez les étapes décrites ci-dessous.
1. Copiez le chemin d’accès à votre fichier Service Worker :
if ('serviceWorker' in navigator) { window.addEventListener('load', () => { navigator.serviceWorker.register('/service-worker.js') // <- your service worker url });}Ensuite, utilisez le paramètre serviceWorkerUrl lors de l’initialisation du WebSDK comme suit :
var Pushwoosh = Pushwoosh || [];Pushwoosh.push(['init', { logLevel: 'error', applicationCode: 'XXXXX-XXXXX', safariWebsitePushID: 'web.com.example.domain', defaultNotificationTitle: 'Pushwoosh', defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', serviceWorkerUrl: '/service-worker.js', // <- your service worker url}]);Le WebSDK n’enregistre pas le nouveau Service Worker immédiatement ; un Service Worker est enregistré lorsque c’est nécessaire :
- lorsqu’un appareil reçoit un jeton de notification push (lors de l’enregistrement de l’appareil ou du réabonnement),
- lorsqu’un jeton de notification push est supprimé (lors de la suppression d’un appareil de la base d’utilisateurs).
Cela accélère le chargement de vos pages en réduisant le nombre de requêtes serveur.
Les navigateurs ne permettent pas d’enregistrer deux Service Workers différents en même temps (en savoir plus : https://github.com/w3c/ServiceWorker/issues/921), donc pour que votre PWA fonctionne correctement, un Service Worker commun doit être enregistré pour votre base de code et celle de Pushwoosh.
2. Ajoutez la chaîne suivante à votre Service Worker (au début ou à la fin, peu importe) :
importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);Ainsi, vous activez la réception et le traitement des notifications push envoyées via les services Pushwoosh pour votre Service Worker.
Installation depuis Google Tag Manager
Anchor link toUtilisez le code suivant dans votre Google Tag Manager pour initialiser le SDK Pushwoosh. Créez une balise HTML personnalisée et collez le code ci-dessous. Assurez-vous de modifier votre code d’application Pushwoosh, votre ID de site web Safari et l’URL de l’image de notification par défaut.
Définissez également une priorité de déclenchement de balise élevée (ex : 100) et déclenchez-la sur Toutes les pages. Voir la capture d’écran ci-dessous.Copier
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script><script type="text/javascript"> var Pushwoosh = Pushwoosh || []; Pushwoosh.push(['init', { logLevel: 'error', applicationCode: 'XXXXX-XXXXX', safariWebsitePushID: 'web.com.example.domain', defaultNotificationTitle: 'Pushwoosh', defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', autoSubscribe: true, subscribeWidget: { enable: false }, userId: 'user_id' }]);</script>