SDK Push Web 3.0

Intégration

Obtenez le SDK Push Web de Pushwoosh et décompressez-le. Vous devriez avoir les fichiers suivants :

pushwoosh-service-worker.js

Placez tous ces fichiers à la racine de premier niveau du répertoire de votre site web.

Initialisez le SDK :

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 Push Web et assurez-vous de mettre l’initialisation en file d’attente jusqu’à ce que le SDK soit complètement chargé.

<script type="text/javascript">
var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
    logLevel: 'info', // valeurs possibles : error, info, debug
    applicationCode: 'XXXXX-XXXXX', // votre code d'application depuis le Panneau de Contrôle Pushwoosh
    apiToken: 'XXXXXXX', // Jeton d'API d'appareil (Device API Token)
    safariWebsitePushID: 'web.com.example.domain', // chaîne de domaine inversée unique, obtenue dans votre portail de développeur Apple. Nécessaire uniquement si vous envoyez des notifications push au navigateur Safari
    defaultNotificationTitle: 'Pushwoosh', // définit un titre par défaut pour les notifications push
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL vers une image de notification personnalisée
    autoSubscribe: false, // ou true. Si true, invite un utilisateur à s'abonner aux notifications push lors de l'initialisation du SDK
    subscribeWidget: {
      enable: true
    },
    userId: 'user_id', // optionnel, définissez un ID utilisateur personnalisé
    tags: {
        'Name': 'John Smith'     // optionnel, définissez des Tags personnalisés
    }
}]);
</script>

Configuration

Pour 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 pas à pas :

Enregistrement du service worker dans une portée différente

Parfois, il n’est pas possible de 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 vers le fichier pushwoosh-service-worker.js.

Gestionnaires d’événements

Dans le SDK Push Web 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 :

// Événement de chargement (Load Event)
Pushwoosh.push(['onLoad', (api) => {
  console.log('Pushwoosh load!');
}]);

Pour suivre l’initialisation correcte du SDK Web, déclenchez l’événement onReady :

// Événement "prêt" (Ready Event)
Pushwoosh.push((api) => {
  console.log('Pushwoosh ready!');
});

Pour vous abonner ou vous désabonner de n’importe quel événement du SDK, utilisez les gestionnaires après le chargement du SDK :

Pushwoosh.push(['onLoad', (api) => {
  function onEventNameHandler() {
    console.log('Triggered event: event-name!');
  }

  // Pour s'abonner à un événement :
  Pushwoosh.addEventHandler('event-name', onEventNameHandler)

  // Pour se désabonner d'un événement :
  Pushwoosh.removeEventHandler('event-name', onEventNameHandler)
}]);

Événements du SDK

Exé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 (unsubscribe)

Exécuté après la désinscription d’un appareil des notifications.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('unsubscribe', (payload) => {
    console.log('Triggered event: unsubscribe');
  });
}]);

Suivre l’affichage d’un widget d’invite d’abonnement.

Pushwoosh.push(['onLoad', (api) => {
  // Exécuté lors de l'affichage du widget d'invite d'abonnement
  Pushwoosh.addEventHandler('show-subscription-widget', (payload) => {
    console.log('Triggered event: show-subscription-widget');
  });

  // Exécuté lors du masquage du widget d'invite d'abonnement
  Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => {
    console.log('Triggered event: hide-subscription-widget');
  });
}]);

Événements de la boîte de dialogue de permission de notification

Suivre l’affichage de la boîte de dialogue d’abonnement native.

Pushwoosh.push(['onLoad', function (api) {
  // Exécuté lors de l'affichage de la boîte de dialogue de permission
  Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => {
    console.log('Triggered event: show-notification-permission-dialog');
  });

  // Exécuté lors du masquage de la boîte de dialogue de permission avec l'un des trois statuts possibles :
  // 1. default - la boîte de dialogue est fermée
  // 2. granted - la permission est accordée
  // 3. denied - la permission est refusée
  Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => {
    console.log('Triggered event: hide-notification-permission-dialog', payload.permission);
  });
}]);

Événements de permission

Vérifier le statut de la permission des notifications push lors de l’initialisation du SDK ; suivre la mise à jour de ce statut chaque fois qu’elle a lieu.

Pushwoosh.push(['onLoad', (api) => {
  // Exécuté lors de l'initialisation du SDK si 'autoSubscribe: false' et/ou si un utilisateur ignore une invite de notification push.
  Pushwoosh.addEventHandler('permission-default', (payload) => {
    console.log('Triggered event: permission-default');
  });

  // Exécuté lors de l'initialisation du SDK si les notifications sont bloquées ou une fois qu'un utilisateur bloque les notifications push.
  Pushwoosh.addEventHandler('permission-denied', (payload) => {
    console.log('Triggered event: permission-denied');
  });

  // Exécuté lors de l'initialisation du SDK si les notifications sont autorisées ou une fois qu'un utilisateur autorise les notifications push.
  Pushwoosh.addEventHandler('permission-granted', (payload) => {
    console.log('Triggered event: permission-granted');
  });
}]);

Événement de réception de push (receive-push)

Suivre la livraison d’une notification push à un appareil.

Pushwoosh.push(['onLoad', (api) => {
  // Exécuté lorsqu'une notification push est affichée.
  Pushwoosh.addEventHandler('receive-push', (payload) => {
    console.log('Triggered event: receive-push', payload.notification);
  });
}]);

Événements de notification

Suivre si une notification push est ouverte ou fermée par un utilisateur.

Pushwoosh.push(['onLoad', (api) => {
  // Exécuté lorsqu'un utilisateur clique sur une notification.
  Pushwoosh.addEventHandler('open-notification', (payload) => {
    console.log('Triggered event: open-notification', payload.notification);
  });

  // Exécuté lorsqu'un utilisateur ferme une notification push.
  Pushwoosh.addEventHandler('hide-notification', (payload) => {
    console.log('Triggered event: hide-notification', payload.notification);
  });
}]);

Événements de la boîte de réception (Inbox)

Suivre les notifications envoyées à la boîte de réception (Inbox).

Pushwoosh.push(['onLoad', (api) => {
  // Exécuté par le ServiceWorker après la réception du message de la boîte de réception et son enregistrement dans indexedDB.
  Pushwoosh.addEventHandler('receive-inbox-message', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.message);
  });

  // Exécuté après la mise à jour automatique de la boîte de réception pendant le chargement de la page.
  Pushwoosh.addEventHandler('update-inbox-messages', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.messages);
  });
}]);

Événements de la fenêtre pop-up d’abonnement personnalisée

Pour plus de détails sur la gestion des événements de la fenêtre pop-up d’abonnement personnalisée, veuillez consulter le Guide des événements de la fenêtre pop-up d’abonnement personnalisée.

API

Une fois le SDK Push Web initialisé, vous pouvez effectuer les appels suivants à l’API Pushwoosh. Toutes les méthodes retournent des objets Promise.

Pushwoosh.push((api) => {
  // Définir des tags pour un utilisateur
  api.setTags({
    'Tag Name 1': 'value1',
    'Tag Name 2': 'value2'
  });

  // Obtenir les tags pour un utilisateur depuis le serveur
  api.getTags();

  // Enregistrer l'ID utilisateur
  api.registerUser('myUserID');

    // Enregistrer l'email de l'utilisateur
  api.registerEmail('<user_email>');

  // Publier un événement
  api.postEvent('myEventName', {attributeName: 'attributeValue'});

   //Se désinscrire des notifications
  api.unregisterDevice();
});

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

Pour incrémenter la valeur d’un Tag de type Nombre (Number), 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

Pour ajouter de nouvelles valeurs à un Tag de type Liste (List) existant, utilisez le paramètre operation avec la valeur ‘append’ comme suit :

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 3': {
      operation: 'append',
      value: ['Value3']
    }
  })
});

Supprimer une valeur de Tag

Pour supprimer une valeur d’un Tag de type Liste (List), 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

Pushwoosh.subscribe()

Cette méthode est utilisée pour demander la permission d’un utilisateur pour les notifications push. Si un utilisateur est déjà abonné, l’exécution de la méthode s’arrêtera.

Si un utilisateur ne s’est pas encore abonné aux notifications push :

1. La permission 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()">Subscribe</button>
<script>
  Pushwoosh.push(['onSubscribe', (api) => {
    console.log('Utilisateur abonné avec succès');
  }]);
</script>

Pushwoosh.unsubscribe()

La méthode /unregisterDevice est exécutée.
L’événement onUnsubscribe est déclenché.

<button onclick="Pushwoosh.unsubscribe()">Unsubscribe</button>
<script type="text/javascript">
  Pushwoosh.push(['onUnsubscribe', (api) => {
    console.log('Utilisateur désabonné avec succès');
  }]);
</script>

Pushwoosh.isSubscribed()

Vérifie si un utilisateur est abonné et retourne un drapeau (flag) true/false.

Pushwoosh.isSubscribed().then((isSubscribed) => {
  console.log('isSubscribed', isSubscribed);
});

Pushwoosh.getHWID()

Retourne le HWID de Pushwoosh.

Pushwoosh.getHWID().then((hwid) => {
  console.log('hwid:', hwid);
});

Pushwoosh.getPushToken()

Retourne le jeton (token) de push s’il est disponible.

Pushwoosh.getPushToken().then((pushToken) => {
  console.log('pushToken:', pushToken);
});

Pushwoosh.getUserId()

Retourne l’ID Utilisateur s’il est disponible.

Pushwoosh.getUserId().then((userId) => {
  console.log('userId:', userId);
});

Pushwoosh.getParams()

Retourne 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, retourne ‘true’ ou ‘false’.

Pushwoosh.isAvailableNotifications() // true/false

Méthodes InboxMessages

messagesWithNoActionPerformedCount(): Promise<number>

Retourne le nombre de messages ouverts.

Pushwoosh.pwinbox.messagesWithNoActionPerformedCount()
  .then((count) => {
    console.log(`${count} messages ouverts`);
  });

unreadMessagesCount()

Retourne le nombre de messages non lus.

Pushwoosh.pwinbox.unreadMessagesCount()
  .then((count) => {
    console.log(`${count} messages non lus`);
  });

messagesCount(): Promise<number>

Retourne 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('Les messages ont été chargés');
  });

readMessagesWithCodes(codes: Array<string>): Promise<void>

Marque les messages comme lus par leurs Inbox_Ids.

Pushwoosh.pwinbox.readMessagesWithCodes(codes)
  .then(() => {
    console.log('Les messages ont été lus');
  });

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('L'action a été exécutée');
  });

deleteMessagesWithCodes(codes: Array<string>): Promise<void>

Marque les messages comme supprimés.

Pushwoosh.pwinbox.deleteMessagesWithCodes([code])
  .then(() => {
    console.log('Les messages ont été supprimés');
  });

syncMessages(): Promise<void>

Synchronise les messages avec le serveur.

Pushwoosh.pwinbox.syncMessages()
  .then(() => {
    console.log('Les messages ont été synchronisés');
  });

Prise en charge des Progressive Web Apps (PWA)

Pour intégrer Pushwoosh dans votre Progressive Web Application (PWA), suivez les étapes décrites ci-dessous.

1. Copiez le chemin vers votre fichier Service Worker :

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js') // <- l'URL de votre service worker
  });
}

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', // <- l'URL de votre service worker
}]);

Le WebSDK n’enregistre pas le nouveau Service Worker immédiatement ; un Service Worker est enregistré lorsqu’il est nécessaire :

lorsqu’un appareil reçoit un jeton de push (lors de l’enregistrement de l’appareil ou du réabonnement),
lorsqu’un jeton de 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 au 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, cela n’a pas d’importance) :

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

Utilisez 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 votre image de notification par défaut.
Définissez également une priorité de déclenchement de balise élevée (par ex. : 100) et déclenchez-la sur Toutes les pages. Voir la capture d’écran ci-dessous.

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