Cet article donne aux développeurs des informations pour configurer les sites web à recevoir des notifications Push Web envoyées depuis la plateforme Emarsys.
Introduction
La notification Push Web est un message push que les contacts reçoivent dans le navigateur de bureau ou mobile. Le message de notification push apparaîtra sur le navigateur actif ou bien sur le bureau si le navigateur est réduit. Si le navigateur est fermé, le message sera mis en attente jusqu'à ce que le navigateur soit activé. Les notifications de navigateur sont utiles principalement pour interagir avec les contacts même quand ils ne se trouvent pas sur le site du client. Les notifications Push Web sont aussi parfois appelées Notifications Push de navigateur. Les notifications Push Web fonctionnent sur les navigateurs mobile Android mais pas sur les iPhones en raison des limites introduites par Apple.
Les notifications Push Web sont différentes des notifications push mobile puisque les messages Push Web sont envoyés au navigateur, tandis que les notifications push mobile sont envoyées à l'app mobile. Si les notifications push d'app mobile vous intéressent, veuillez consulter notre documentation Mobile Engage.
Navigateurs pris en charge
Vous trouverez confirmée ci-dessous la liste des navigateurs sur lesquels le SDK web Emarsys prend en charge les notifications Push Web
Desktop
- Chrome v53+
- Firefox v22+
- Opera v39+
- Safari v11+
- Microsoft Edge v26+
Mobile
- Firefox Android v26+
- Chrome Android v53+
- Opera Android v41+
Les 2 types de mécanisme d'envoi de notifications Push Web pris en charge sont VAPID (Voluntary Application Server Identity) et APNS (Apple Push Notification Service). La plupart des navigateurs prend maintenant en charge l'authentification VAPID, y-compris Chrome, Firefox, Opera et Edge, mais pas seulement. Pour le moment, les navigateurs Safari ne prennent pas en charge VAPID et utilisent APNS à la place.
Il n'est pas possible d'utiliser les notifications Push Web en mode incognito ou invité.
Les notifications Push Web ne fonctionnent pas sur les appareils iOS en raison des limites introduites par Apple.
Vous devez accéder au répertoire racine de la page Web correspondante pour mettre en œuvre les notifications Push Web. Pour plus d'informations, voir Service Worker.
Étapes d'implémentation standard
Les étapes détaillées ci-dessous servent à implémenter et activer la fonctionnalité Push Web. P our aider à l'implémentation, vous trouverez ci-dessous un exemple de fichier index auquel vous pouvez vous référer quand vous implémentez.
Configurer le domaine dans Emarsys
Pour permettre au SDK web de se connecter à Emarsys, le domaine doit être ajouté au compte Emarsys. Veuillez vous connecter au compte Emarsys et naviguer jusqu'à Canaux > Push Web > Onglet de domaines.
Cliquez sur le bouton Créer un domaine tout en haut à droite de l'écran.
Saisissez le Nom de domaine et la Langue par défaut :
- Nom de domaine - Le nom du l'app indiqué à la section précédente.
- Langue par défaut - La langue par défaut de l'app.
Cliquez sur Enregistrer.
Notez le Code de domaine car il sera utilisé plus tard dans l'intégration.
Ajoutez la clé VAPID (pour les navigateurs Chrome, Firefox etc.) en cliquant sur Ajouter VAPID à la section Plateforme. Puis saisissez les clés Privé et Publique, avant d' Enregistrer.
Il est recommandé de générer une nouvelle clé VAPID, même on en utilisait déjà une avec l'ancien fournisseur. Il existe de nombreux outils en ligne pour les générer. Nous ne recommandons aucun générateur de clé VAPID en particulier.
Ajoutez le certificat APNS (pour Safari) en cliquant sur Ajouter APNS. Chargez ensuite le fichier .p12, saisissez la phrase de passe utilisée au moment de générer le fichier .p12 et cliquez sur Enregistrer.
Il est recommandé de générer une nouvelle clé APNS, même on en utilisait déjà une avec l'ancien fournisseur. Vous trouverez le guide pour l'effectuer sur le Portail d'aide Emarsys ici
Service Worker
Un service worker est un script que le navigateur exécute en arrière-plan, séparément de la page web. Le rôle du service worker est de recevoir l'événement push. Si vous avez déjà un service worker pour le site web, importez-y le service worker Emarsys en ajoutant la ligne suivante au fichier de service worker actuel.
self.importScripts("https://assets.emarsys.net/web-emarsys-sdk/<VERSION>/web-emarsys-service-worker.js")Si le site web n'a pas de fichier de service worker, veuillez créer un fichier appelé "service-worker.js", ajoutez la ligne de code ci-dessus et placez le fichier dans le répertoire racine du site web.
La fichier de service worker doit être conservé sur le répertoire racine du site web.
Veuillez noter qu'au moment de la publication de ce document, la version est 4.3.1 mais elle peut être mise à jour dans le futur. Pour trouver la dernière version, veuillez utiliser la commande cURL ci-dessous :
curl --head https://redirector.eservice.emarsys.net/web-emarsys-sdk/latest/Salesforce Commerce Cloud
Les clients qui utilisent Salesforce Commerce Cloud n'ont pas accès au répertoire racine pour placer le Service Worker. Toutefois, il est possible de remapper le Service Worker sur Salesforce Commerce Cloud afin que Push Web fonctionne. Les étapes à suivre sont les suivantes :
- Dans Salesforce, créez un objet Salesforce Commerce Cloud de type "Content Asset".
- Ajoutez-y le code du service worker Emarsys, comme détaillé ci-dessus.
- Créez un alias de l'itinéraire vers le servie worker en allant dans Business Manager > Outils marchand > SEO > Alias.
- Entrez dans l'exemple ci-dessous :
{...
"host-name" : \[
...,
{
"if-site-path": "/web-emarsys-service-worker.js",
"pipeline": "[name of SFCC object created in step 1]"
}
\]
}5. Vérifiez que le service worker est disponible en allant sur https://[CustomerDomain]/web-emarsys-service-worker.js
Page de site web
Initialisez le SDK en chargeant le fichier SDK de manière asynchrone et mettez l'initialisation en attente jusqu'à ce que le fichier SDK soit complètement chargé en plaçant ce qui suit dans la Première balise du site web HTML.
<script type="text/javascript" src="https://assets.emarsys.net/web-emarsys-sdk/<VERSION>/web-emarsys-sdk.js" async></script>
<script type="text/javascript">
var WebEmarsysSdk = WebEmarsysSdk || []
WebEmarsysSdk.push(['init', {
applicationCode: 'XXXXX-XXXXX', // your Domain code obtained above
safariWebsitePushID: 'web.com.yoursite.example', // unique reverse-domain string, obtained in you Apple Developer Portal
defaultNotificationTitle: 'Your Default Title', // sets your default title for push notifications
defaultNotificationIcon: 'https://yoursite.com/img/your-logo.png', // URL to your notification icon
autoSubscribe: false, // If true, prompts a user to subscribe for pushes upon SDK initialization which is not recommended
serviceWorker: {
url: 'service-worker.js',
applicationServerPublicKey: 'your-public-vapid-key'
}
}])
</script>- Le
safariWebsitePushIDn'est requis que si l'on désire envoyer des notifications push aux navigateurs Safari. defaultNotificationTitleest utilisé lorsque le titre du message Push Web n'est pas défini dans la campagne.- Le titre par défaut est remplacé par le titre de la campagne lorsqu'il est présent.
- Pour le titre par défaut, veuillez éviter d'utiliser quoi que ce soit de propre à une campagne spécifique ou une société apparentée, mais utilisez plutôt un titre lié à la marque ou au thème principal du site Web.
- Par exemple, si une société apparentée possède plusieurs marques et sites Web qui recueillent des abonnés au Push Web, les utilisateurs qui ne connaissent pas le nom de la société apparentée seront déroutés par la réception du message.
defaultNotificationIcon: Utilisez le format PNG pour l'icône par défaut.
- Veuillez vous assurer que la version du SDK indiquée sur la page correspond à celle du Service Worker. En d'autres termes, si la version actuelle du SDK est 4.3.1, alors le Service Worker et le SDK Web saisis sur la page indiquent tous deux qu'il s'agit de la version 4.3.1.
- Au moment de la publication de ce document, la version est 4.3.1 mais il se peut qu'elle soit mise à jour ultérieurement. Pour trouver la dernière version, veuillez utiliser la commande cURL ci-dessous :
curl --head https://redirector.eservice.emarsys.net/web-emarsys-sdk/latest/Gestion des contacts
Les fonctions publiques détaillées ci-dessous ne devraient être utilisées qu'après que le SDK a terminé son initialisation.
Les fonctions décrites dans cette section permettent au client de gérer la liaison des navigateurs au compte Emarsys, pour que les notifications push puissent être envoyées aux contacts. Avant de suivre les étapes ci-dessous, il est bon de comprendre le concept de dossier de contact anonyme (par opposition au contact connu) qu'Emarsys utilise pour gérer les dossiers.
- Contact anonyme - Un dossier de contact anonyme est simplement un dossier d'appareil qui est créé quand un utilisateur souscrit aux notifications Push Web pour la première fois, au moment où la plateforme reçoit un appel du SDK Push Web. Quand le dossier est créé, un ID d'hardware est assigné, qui sera utilisé pour empêcher la création de dossiers en doublon, si l'utilisateur retourne sur le site web.
Les données des contacts supprimés seront supprimées et ne recevront pas de notifications push. Ils doivent s'abonner à nouveau pour recevoir des messages push.
- Contact connu - Un contact connu est un dossier qui existe déjà dans le compte Emarsys. Ce dossier est créé et entretenu par la synchronisation de contacts implémentée pour tout le compte. La synchronisation de contacts doit avoir été déjà établie avant d'implémenter le SDK Push Web. Veuillez noter que le SDK web Emarsys ne crée pas de dossiers de contacts connus, il ne fait que connecter l'appareil au dossier de contact connu pré-existant.
Inscription
Safari et Firefox exigent qu'un événement ait lieu sur la page avant de demander l'autorisation à l'utilisateur. Déclencher l'appel avant un événement sur la page entraînera l'échec de la demande. Un événement peut être n'importe quel clic sur la page. On s'attend à ce que les autres navigateurs, par exemple Chrome, aient bientôt des exigences similaires.
Utilisez la méthode subscribe pour demander l'envoi de notifications push au contact. Si le contact a déjà souscrit, la méthode reviendra simplement.
function subscribe (): Promise<void>;Quand un contact donne son accord pour recevoir des notifications push, le rappel onSubscribe sera invoqué.
Voici un exemple de demande à l'utilisateur de souscrire après un scroll ou un clic sur la page :
// Subscribe on button click
<button onclick="generalSubscribe()">Subscribe</button>
<script>
function generalSubscribe() {
return WebEmarsysSdk.subscribe()
}
// The submit event fires when a <form> is submitted.
document.addEventListener('submit', function(e) {
generalSubscribe();
});
// An element receives a click event when a pointing device button (such as a mouse's primary mouse button) is both pressed and released while the pointer is located inside the element.
document.addEventListener('click', function(e) {
generalSubscribe();
});
</script>Désabonnement
Utilisez la méthode unsubscribe pour désactiver les notifications push pour un contact. Cet appel pourrait par exemple être placé sur une page de préférences, où l'utilisateur pourrait configurer les canaux autorisés à communiquer avec lui.
function unsubscribe (): Promise<void>;Lien de contact
Pour lier le navigateur à un dossier de contact anonyme ou connu, utilisez la fonction login. Pour cela, vous devez inclure les fieldId et fieldValue dans l'appel. Vous trouverez le fieldId en naviguant jusqu'à l'éditeur de champ dans le compte Emarsys (Gestion > Éditeur de champ).
Il est formellement interdit de régler le champ fieldId sur tout champ contenant des données PII (comme une adresse électronique ou une adresse électronique hachée). L'utilisation d'un tel fieldId peut entraîner le stockage de ces données dans notre infrastructure clou, ce qui non autorisé.
Veuillez définir le fieldld comme un identifiant de contact unique, non devinable et immuable (l'email ou l'email haché n'est pas autorisé). Par exemple, les identifiants de clients sont considérés comme non-PII et peuvent être utilisés en toute sécurité.
function login (contactInfo?: ContactInfo): Promise<boolean>;
type ContactInfo = {
fieldId: number,
fieldValue: string
}Déliaison de contact
Pour délier un dossier de contact connu du navigateur, par ex. l'utilisateur se déconnecte du compte et les communications push sont privées/sensibles, utilisez la fonction logout. Le dossier de contact anonyme continuera d'être lié au navigateur.
function logout (): Promise<boolean>;Événements personnalisés
Les événements personnalisés ne peuvent pas être supprimés et ne doivent donc pas contenir de données PII.
Vous pouvez utiliser la méthode customEvent pour déclencher un événement personnalisé, qui peut être utilisé pour le suivi ou le déclenchement d'un programme d'automatisation (Automation Center ou Interactions).
Lors de la mise en œuvre, le paramètre eventName est requis.
WebEmarsysSdk.customEvent(<eventName: String>)
L'événement sera disponible dans le programme d'automatisation dès que le premier événement sera déclenché par les contacts.
Utiliser un événement personnalisé pour déclencher un programme Interactions
Voici ce que vous devez faire pour déclencher un événement personnalisé qui déclenche un programme Interactions lorsque les contacts effectuent une action spécifique sur votre site Web :
1. Ajoutez le code ci-dessous à l'action du site Web qui déclenchera l'événement personnalisé où eventName est le nom de votre événement personnalisé :
WebEmarsysSdk.customEvent('eventName', { k1: 'v1', k2: 'v2' }).then((success) => {
console.log('Sending custom event result:', success)
}).catch(err => {
console.error('Error during custom event sending', err)
})2. Vous pouvez sélectionner l'événement spécifique dans le déclencher événement Mobile dans votre programme Interactions.
L'événement sera disponible dans Interactions dès que les contacts le déclencheront.
Exemple de charges utiles
{"dnd":true,"events":
[{"type":"custom","name":"MCTestEvt","timestamp":"2022-01-17T09:57:20.121Z"}],
"clicks":[],"viewedMessages":[]}Fonctions supplémentaires
Les fonctions supplémentaires détaillées ci-dessous servent à donner aux développeurs un contrôle accru et de la flexibilité concernant le moment d'implémenter la fonctionnalité Push Web.
isSubscribed
Retourne une indication booléenne si le navigateur web et l'utilisateur sont complètement enregistrés. C'est le cas si :
- L'utilisateur a donné son autorisation pour recevoir des notifications push (il a un token push),
- Le navigateur est enregistré dans notre backend et
- L'utilisateur est connecté.
function isSubscribed (): Promise<boolean>;getLoggedInContact
Retourne les informations sur le contact qui est actuellement lié au navigateur.
function getLoggedInContact (): Promise<ContactInfo | {} | undefined>;Retourne l'un des éléments suivants
- Les
ContactInfoconsistant enfieldIdetfieldValuesi le dossier de contact lié au navigateur est celui d'un contact connu. - Un objet vide {} si le dossier de contact lié au navigateur est anonyme.
- Indéfini s'il n'y a ni de contact connu, ni de contact anonyme lié au navigateur.
Écouteurs d'événement
Pour enregistrer une fonction rappel vous devez utiliser la méthode de push publique du SDK et enregistrer tous vos rappels dans une partie <script> qui est placée à la fin du site web HTML.
type HandlerFn = (params?: any) => any
type SdkOnReadyCallback = HandlerFn
type SdkInitCallback = ['init', IInitParams]
type WebSdkEvent = 'onReady' | 'onSubscribe' | 'onUnsubscribe' | 'onSWInitError' | 'onPermissionPrompt' | 'onPermissionDenied' | 'onPermissionGranted'
type WebSdkEventCallback = [WebSdkEvent, HandlerFn]
type SdkCommand = SdkInitCallback | SdkOnReadyCallback | MeWebSdkEventCallback
function push (sdkCommand: SdkCommand): void;init
Est invoqué après que la page web et le code SDK sont complètement chargés. Le rappel init fait partie du SDK. Les paramètres d'initialisation doivent être passés à la méthode push.
type SdkInitCallback = ['init', IInitParams]
type SdkCommand = SdkInitCallback | ...
function push (sdkCommand: SdkCommand): void;onReady
Le rappel onReady est invoqué après que le SDK a été initialisé. Il est possible d'enregistrer le rappel désiré en passant une fonction à la méthode push ou d'utiliser la même approche pouvant être utilisée pour tous les autres événements pris en charge.
<script>
WebEmarsysSdk.push(function() {
console.log('EVENT: onReady');
// do whatever you need to do after the SDK is ready
});
// further event handler registrations...
</script>Autres événements
Tous les rappels pour les événements listés dans cette section doivent être enregistrés en passant un objet tableau à la méthode push, consistant en le nom de l'événement et la fonction rappel :
onSubscribe: Invoqué quand le navigateur est enregistré avec notre backend, que nous avons un token push et qu'un utilisateur est lié au navigateur.onUnsubscribe: Invoqué après l'exécution réussie du désabonnement.onSWInitError: Invoqué dans le cas d'une erreur détectée pendant l'enregistrement du service worker (SW).onPermissionPrompt: Invoqué quand il est nécessaire de solliciter l'autorisation de l'utilisateur pour l'envoi de notifications push.onPermissionDenied: Invoqué quand l'utilisateur a globalement refusé de recevoir des notifications push.onPermissionGranted: Invoqué quand l'utilisateur a accepté de recevoir des notifications push.
<script>
// ...
WebEmarsysSdk.push(['onPermissionPrompt', function() {
console.log('EVENT: onPermissionPrompt');
}]);
</script>Résolution des problèmes
Dans le cas où les messages push ne sont pas reçus, nous vous suggérons tout d'abord de vérifier les paramètres du système d'exploitation de l'appareil et les paramètres du navigateur.
- En vérifiant le système d'exploitation, veuillez vous assurer que Ne Pas Déranger est désactivé dans les Préférences/Paramètres de système du système d'exploitation.
- En vérifiant les paramètres du navigateur, veuillez vous assurer que le site a l'autorisation d'envoyer des notifications.
Il vaut la peine de noter que si vous testez les notifications push pendant que vous êtes en réunion virtuelle (par ex. avec Zoom, Microsoft Teams etc.), le logiciel de réunion aura peut-être activé ne pas déranger au début de la réunion automatiquement et à votre insu.