Dieser Artikel richtet sich an Developer und beschreibt, wie man Websites so konfiguriert, dass sie von der Emarsys Plattform gesendete Web Push Benachrichtigungen empfangen können.
Einführung
Eine Web Push Benachrichtigung ist eine Push Message, die Kontakte in ihrem Desktop- oder Mobile-Browser empfangen. Die Push-Benachrichtigung wird im aktiven Browser angezeigt; ist der Browser minimiert, erfolgt die Anzeige auf dem Desktop. Bei geschlossenem Browser wird die Nachricht gereiht, bis der Browser wieder online ist. Browser-Benachrichtigungen erfüllen vor allem einen Zweck: Sie ermöglichen die Interaktion mit Kontakten, auch wenn sich diese gerade nicht auf der Website des Unternehmens befinden. Web Push Benachrichtigungen werden auch als Browser Push Benachrichtigungen bezeichnet. Web Push Benachrichtigungen funktionieren in Mobile-Browsern unter Android, jedoch nicht auf iPhones, da Apple dies verhindert.
Web Push Benachrichtungen unterscheiden sich von Mobile Push Benachrichtigungen: Web Push Benachrichtigungen werden an den Browser gesendet, während Mobile Push Benachrichtigungen an die Mobile App gesendet werden. Wenn Sie sich für Push Benachrichtigungen an die Mobile App interessieren, lesen Sie bitte die Dokumentation zu Mobile Engage.
Unterstützte Browser
Nachstehend haben wir eine Liste der Browser zusammengestellt, für die das Emarsys Web SDK Web Push Benachrichtigungen unterstützt.
Desktop
- Chrome v53+
- Firefox v22+
- Opera v39+
- Safari v11+
- Microsoft Edge v26+
Mobile
- Firefox Android v26+
- Chrome Android v53+
- Opera Android v41+
- Safari v16.4+
Die 2 Arten von Sendemechanismen, die für den Versand von Web Push Benachrichtigungen unterstützt werden, sind VAPID (Voluntary Application Server Identity) und APNS (Apple Push Notification Service). Mittlerweile unterstützen die meisten Browser die VAPID-Authentifizierung, unter anderem Chrome, Firefox, Opera, Safari und Edge.
Web Push Benachrichtigungen können weder im Inkognito- noch im Gastmodus eines Browsers verwendet werden.
Um die Web Push Benachrichtigungen zu implementieren, müssen Sie auf das Root-Verzeichnis der entsprechenden Webseite zugreifen. Weitere Informationen erhalten Sie unter: Service Worker
Es ist bekannt, dass Web Push ein Problem mit Safari 17.3 und 17.4 ICNS unter Verwendung von APNS hat. Da die genannten Browser möglicherweise nicht in der Lage sind, ICNS-Dateien für das Push-Benachrichtigungspaket zu generieren, empfehlen wir die Verwendung von VAPID für Safari unter macOS (gilt nur für Safari 16 oder höher) und das Setzen der Flag enableMacSafariVapid auf true, bis es weitere Informationen von Apple gibt.
Standardschritte der Implementierung
Mit den unten angeführten Schritten wird das Web Push Feature implementiert und aktiviert. Zudem haben wir eine Beispiel-Indexdatei bereitgestellt, die Sie während der Implementierung als Referenz heranziehen können.
Domain in Emarsys einrichten
Damit das Web SDK eine Verbindung zu Emarsys herstellen kann, muss die Domain zum Emarsys Account hinzugefügt werden.
- Melden Sie sich beim Emarsys Account an und gehen Sie zu Kanäle > Web Push > Tab "Domains".
- Klicken Sie "Domain erstellen" in der rechten oberen Ecke des Screens.
- Geben Sie den Domainnamen und die Standardsprache ein:
- Domain Name - Der Name der App, der im vorherigen Abschnitt gesetzt wurde.
- Default language - Die Standardsprache der App.
- Klicken Sie Speichern.
Notieren Sie sich den Domain code; dieser wird später in der Integration verwendet.
- Unter Platform, klicken Sie Add VAPID, um den VAPID Key hinzuzufügen (für Chrome, Firefox etc.). Geben Sie sodann die Private und Public Keys ein und klicken Sie Save.
Wir empfehlen, einen neuen VAPID Key zu erstellen, auch wenn Sie bereits mit dem bisherigen Provider einen solchen verwendet haben. Es gibt online zahlreiche Tools, mit denen ein Key dieser Art erstellt werden kann. Wir haben diesebezüglich keine besondere Empfehlung.
- Klicken Sie Add APNS, um das APNS-Zertifikat hinzuzufügen (für Safari). Laden Sie dann die .p12-Datei hoch, geben Sie die bei der Erstellung verwendete Passphrase ein und klicken Sie Save.
Wir empfehlen, einen neuen APNS Key zu erstellen, auch wenn Sie bereits mit dem bisherigen Provider einen solchen verwendet haben. Im Emarsys Hilfeportal finden Sie hier die entsprechende Anleitung.
Service Worker
Ein Service Worker ist ein Script, das der Browser im Hintergrund und unabhängig von der Webseite ausführt. Der Service Worker hat die Aufgabe, das Push Event zu empfangen. Wenn Sie bereits einen Service Worker für die Website haben, importieren Sie den Emarsys Service Worker dazu, indem Sie folgende Zeile zur aktuellen Service-Worker-Datei hinzufügen:
self.importScripts("https://client-version.cf.emarsys.net/web-emarsys-sdk-v4/latest/web-emarsys-service-worker.js")Sollte die Website keine Service-Worker-Datei haben, erstellen Sie eine Datei namens service-worker.js, fügen Sie die oben angeführte Codezeile hinzu und platzieren Sie die Datei im Stammverzeichnis der Website.
Die Service-Worker-Datei muss im Stammverzeichnis der Website gespeichert sein.
Bitte beachten Sie: Zum Zeitpunkt der Veröffentlichung dieses Dokuments ist 4 die aktuelle Version, die aber möglicherweise zu einem späteren Zeitpunkt aktualisiert wird.
Salesforce Commerce Cloud
Kunden, die mit Salesforce Commerce Cloud arbeiten, haben keinen Zugriff auf das Root-Verzeichnis und können den Service Worker nicht platzieren. Jedoch kann der Service Worker in Salesforce Commerce Cloud neu zugeordnet werden, damit Web Push funktioniert. Dazu führen Sie folgende Schritte aus:
- In Salesforce erstellen Sie ein Salesforce Commerce Cloud Objekt mit dem Typ "Content Asset".
- Fügen Sie den Emarsys Service Worker Code hinzu (wie oben angegeben).
- Erstellen Sie ein Alias für die Route zum Service Worker; dafür gehen Sie zu Business Manager > Merchant Tools > SEO > Aliases.
- Geben Sie das unten angeführte Beispiel ein:
{... "host-name" : \[ ..., { "if-site-path": "/web-emarsys-service-worker.js", "pipeline": "[name of SFCC object created in step 1]" } \] }5. Überprüfen Sie, ob der Service Worker verfügbar ist, indem Sie zu https://[CustomerDomain]/web-emarsys-service-worker.js gehen.
Website-Seite
Initialisieren Sie das SDK, indem Sie die SDK-Datei asynchron laden, und reihen Sie die Initialisierung, bis die SDK-Datei vollständig geladen ist, indem Sie Folgendes im head-Tag des Website-HTML platzieren:
<script type="text/javascript" src="https://client-version.cf.emarsys.net/web-emarsys-sdk-v4/latest/web-emarsys-sdk.js" async></script> <script type="text/javascript"> var WebEmarsysSdk = WebEmarsysSdk || [] WebEmarsysSdk.push(['init', { applicationCode: 'XXXXX-XXXXX', // your Domain code obtained above enableMacSafariVapid: true, // If true, enables VAPID instead of APNS for Safari on Mac 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>-
safariWebsitePushIDist nur erforderlich, wenn Sie Push-Benachrichtigungen an Safari-Browser senden wollen. -
defaultNotificationTitlewird verwendet, wenn der Titel der Web Push Message in der Kampagne nicht definiert ist.- Ist ein Kampagnentitel vorhanden, wird der Standardtitel überschrieben.
- Für den Standardtitel gilt: Bitte verzichten Sie auf einen Namen, der auf eine bestimmte Kampagne oder ein Dachunternehmen verweist; verwenden Sie stattdessen einen Titel, der sich auf die Brand oder das Hauptthema der Website bezieht.
- Ein Beispiel: Wenn ein Dachunternehmen mehrere Marken und Websites besitzt, die Web Push Abonnenten erfassen, könnten die Nutzer möglicherweise verwirrt reagieren, wenn sie Nachrichten vom Dachunternehmen erhalten.
-
defaultNotificationIcon: Verwenden Sie das Format PNG für das Standard-Icon.
- Bitte vergewissern Sie sich, dass die SDK-Version auf der Seite jener des Service Worker entspricht. Mit anderen Worten: Wenn die aktuelle SDK-Version 4 ist, müssen sowohl der Service Worker als auch die auf der Seite eingefügte Web-SDK die Version 4 haben.
- Zum Zeitpunkt der Veröffentlichung dieses Dokuments ist 4 die aktuelle Version, die aber möglicherweise zu einem späteren Zeitpunkt aktualisiert wird.
Kontaktmanagement
Die nachstehend beschriebenen öffentlichen Funktionen sollten erst verwendet werden, nachdem die Initialisierung des SDK abgeschlossen ist.
Mit den in diesem Abschnitt beschriebenen Funktionen können Kunden das Verlinken von Browsern mit dem Emarsys Account und damit das Senden von Push-Benachrichtigungen an ihre Kontakte managen. Bevor Sie die unten angeführten Schritte ausführen, stellen wir Ihnen das Konzept der anonymen versus der bekannten Kontakte vor, das Emarsys für das Verwalten von Kontakteinträgen verwendet.
-
Anonymer Kontakt - Ein Eintrag für einen anonymen Kontakt ist im Grunde ein Geräteeintrag und wird erstellt, wenn ein Nutzer sich erstmals für den Erhalt von Web Push Benachrichtigungen anmeldet; im Zuge dessen erhält die Plattform einen Call vom Web Push SDK. Beim Erstellen des Eintrags wird eine
hardware IDzugewiesen; das verhindert die Duplizierung des Eintrags, sollte der Nutzer zur Website zurückkehren.
Gelöschte Kontaktdaten werden entfernt, die entsprechenden Kontakte erhalten keine Push-Benachrichtigungen. Um wieder Push Messages zu erhalten, müssen sie sich erneut für den Erhalt anmelden.
- Bekannter Kontakt - Ein bekannter Kontakt ist ein Eintrag, der bereits im Emarsys Account existiert. Erstellt und gewartet wird dieser Eintrag durch die Kontaktsynchronisation, die für den gesamten Account implementiert ist. Die Kontaktsynchronisation sollte bereits vor Implementierung des Web Push SDK aufgesetzt worden sein. Bitte beachten Sie, dass das Emarsys Web SDK keine Einträge für bekannte Kontakte erstellt, sondern nur das Gerät mit einem bereits existierenden Kontakteintrag verbindet. Es verbindet das Gerät nur mit dem bereits bestehenden Kontaktdatensatz.
Anmeldung
Safari und Firefox erwarten, dass auf der Seite ein Event eintritt, bevor die Zustimmung des Nutzers eingeholt wird. Wird der Call vor Eintreten des Events auf der Seite getriggert, schlägt der Request fehl. Als Event gilt jeder Klick auf der Seite. Es wird erwartet, dass andere Browser, zum Beispiel Chrome, bald eine ähnliche Anforderung implementieren werden.
Verwenden Sie die Methode subscribe, um den Versand von Push-Benachrichtigungen an den Kontakt zu fordern. Sollte der Kontakt bereits angemeldet sein, wird die Methode einfach zurückgegeben.
function subscribe (): Promise<void>;Wenn ein Kontakt dem Erhalt von Push-Benachrichtigungen zustimmt, wird der Callback onSubscribe aufgerufen.
Hier ist ein Beispiel für das Einholen der Zustimmung vom Nutzer nach einem Klick auf der Seite:
// 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>Abmeldung
Um Push-Benachrichtigungen für einen Kontakt zu deaktivieren, verwenden Sie die Methode unsubscribe. Dieser Call kann zum Beispiel auf einer Seite mit Präferenzen platziert sein, auf der ein Nutzer konfigurieren kann, welche Kanäle mit ihm kommunizieren dürfen.
function unsubscribe (): Promise<void>;Kontakt verlinken
Um den Browser mit einem Eintrag für einen bekannten Kontakt zu verbinden, verwenden Sie die Funktion login. Dafür müssen Sie fieldId und fieldValue im Call einschließen. Die fieldId finden Sie, indem Sie im Emarsys Account zum Feld-Editor gehen (Management > Feld-Editor).
Das Setzen der fieldId auf ein Feld, das benutzerbezogene Daten enthält (wie E-Mail oder Hash E-Mail) ist verboten. Das Verwenden einer solchen fieldId kann dazu führen, dass diese Daten in der Cloud-Infrastruktur gespeichert werden, und das ist nicht erlaubt.
Bitte setzen Sie die fieldValue auf eindeutige, nicht erratbare und unveränderliche Kontaktkenner (E-Mail oder Hash E-Mail ist nicht erlaubt). Kunden-IDs gelten zum Beispiel nicht als personenbezogene Daten, ihre Verwendung ist sicher.
function login (contactInfo?: ContactInfo): Promise<boolean>; type ContactInfo = { fieldId: number, fieldValue: string }Verlinkung des Kontakts aufheben
Um die Verlinkung eines Eintrags für einen bekannten Kontakt mit dem Browser aufzuheben, verwenden Sie die Funktion logout. Meldet sich der Nutzer beispielsweise von seinem Konto ab und die Push-Nachrichten sind privat oder sensibel, bleibt der anonyme Kontaktdatensatz mit dem Browser verknüpft.
function logout (): Promise<boolean>;Custom Events
Custom Events können nicht gelöscht werden und sollten daher keine personenbezogene Daten enthalten.
Für das Auslösen eines Custom Events können Sie die Methode customEvent verwenden; damit können Sie ein Automation Programm (Automation Center oder Interactions) tracken oder triggern.
Beim Implementieren ist der Parameter eventName erforderlich.
WebEmarsysSdk.customEvent(<eventName: String>)
Das Event ist im Automation Programm verfügbar, sobald das erste Event von Kontakten getriggert wird.
Custom Event für das Triggern eines Interactions Programms verwenden
So lösen Sie ein Custom Event aus, das ein Interactions Programm triggert, wenn Kontakte eine bestimmte Aktion auf Ihrer Website ausführen:
1. Fügen Sie den unten angeführten Code zu jener Website-Aktion hinzu, die das Custom Event auslösen soll, wobei eventName der Name Ihres Custom Events ist:
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. Sie können das Event in Ihrem Interactions Programm im Trigger Web Push Event auswählen.
Das Event ist in Interactions verfügbar, sobald es von Kontakten getriggert wird.
Payload-Beispiel:
{"dnd":true,"events": [{"type":"custom","name":"MCTestEvt","timestamp":"2022-01-17T09:57:20.121Z"}], "clicks":[],"viewedMessages":[]}Zusätzliche Funktionen
Mit den nachstehend angeführten zusätzlichen Funktionen erhalten Developer mehr Kontrolle und Flexibilität bei der Implementierung des Web Push Features.
isSubscribed
Gibt einen booleschen Indikator zurück, wenn der Web-Browser und der Nutzer vollständig registriert sind. Das ist der Fall, wenn:
- der Nutzer für den Erhalt von Push-Benachrichtigungen freigeschaltet ist (ein Push Token hat),
- der Browser in unserem Backend registriert ist und
- der Nutzer angemeldet ist.
function isSubscribed (): Promise<boolean>;getLoggedInContact
Gibt die Information über den Kontakt zurück, der aktuell mit dem Browser verlinkt ist.
function getLoggedInContact (): Promise<ContactInfo | {} | undefined>;Gibt eine der folgenden Informationen zurück
- Die C
ontactInfo,bestehend aus fieldIdund fieldValue,wenn der mit dem Browser verlinkte Eintrag der eines bekannten Kontakts ist. - Ein leeres Objekt {}, wenn der mit dem Browser verlinkte Eintrag anonym ist.
- Nicht definiert, wenn weder ein bekannter noch ein anonymer Kontakt mit dem Browser verlinkt ist.
Event Listeners
Um eine Callback-Funktion zu registrieren, müssen Sie die Public-Push-Methode des SDK verwenden - und Sie sollten alle Callbacks in einem <script>-Teil registrieren, das am Ende des Website-HTML platziert ist.
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
Wird aufgerufen, nachdem die Website und der SDK Code vollständig geladen sind. Der Callback init ist Teil des SDK. Die Initialisierungsparameter müssen an die Push-Methode übergeben werden.
type SdkInitCallback = ['init', IInitParams] type SdkCommand = SdkInitCallback | ... function push (sdkCommand: SdkCommand): void;onReady
Der Callback onReady wird aufgerufen, nachdem das SDK initialisiert wurde. Es ist möglich, den gewünschten Callback zu registrieren, indem eine Funktion an die Push-Methode übergeben wird; oder Sie nutzen denselben Ansatz, der für alle anderen unterstützten Events verwendet werden kann.
<script> WebEmarsysSdk.push(function() { console.log('EVENT: onReady'); // do whatever you need to do after the SDK is ready }); // further event handler registrations... </script>Weitere Events
Alle in diesem Abschnitt aufgelisteten Callbacks für Events müssen registriert werden, indem ein Array-Objekt an die Push-Methode übergeben wird, bestehend aus dem Eventnamen und der Callback-Funktion:
-
onSubscribe: Wird aufgerufen, wenn der Browser mit unserem Backend registriert ist, wir ein Push Token haben und ein Nutzer mit dem Browser verlinkt ist. -
onUnsubscribe: Wird nach der erfolgreichen Durchführung einer Abmeldung aufgerufen. -
onSWInitError: Wird aufgerufen, wenn während der Service-Worker-Registrierung (SW) ein Fehler entdeckt wurde. -
onPermissionPrompt: Wird aufgerufen, wenn es erforderlich ist, den Nutzer um die Zustimmung für den Erhalt von Push-Benachrichtigungen zu bitten. -
onPermissionDenied: Wird aufgerufen, wenn der Nutzer den Erhalt von Push-Benachrichtigungen generell abgelehnt hat. -
onPermissionGranted: Wird aufgerufen, wenn der Nutzer dem Erhalt von Push-Benachrichtigungen zugestimmt hat.
<script> // ... WebEmarsysSdk.push(['onPermissionPrompt', function() { console.log('EVENT: onPermissionPrompt'); }]); </script>Problembehandlung
Falls die Push Messages nicht empfangen werden, sollten Sie zuerst die Einstellungen für das Gerätebetriebssystem und die Browsereinstellungen überprüfen.
- Bei den Einstellungen/Präferenzen für das Betriebssystem vergewissern Sie sich, dass die Option "Do Not Disturb" deaktiviert ist.
- Bei den Browsereinstellungen vergewissern Sie sich, dass die Seite die Erlaubnis hat, Benachrichtigungen zu senden.
Wichtig ist auch folgender Hinweis: Wenn Sie Push-Benachrichtigungen testen, während Sie sich in einem virtuellen Meeting befinden (z.B. über Zoom oder Microsoft Teams), kann es sein, dass die Meeting-Software die "Do not disturb"-Funktion zu Beginn des Meetings automatisch und ohne Ihr Wissen aktiviert hat.