Skip to content

2. Einrichten von Web Push auf Kundenseiten (Glocke*)

2.1. Voraussetzungen

Web Push Notifications funktionieren nur auf Websites, die das HTTPS-Protokoll verwenden. Folgende Schritte sind für die Umsetzung erforderlich:

2.2. Einschränkungen

Die Glocken-Funktion stellt einen Ein-Klick-Weg zur An- bzw. Abmeldung von Web Push Nachrichten dar. Es ist daher nicht möglich, wenn mehrere Push-Listen verwendet werden, sich für einzelne Push-Listen an- bzw. von einzelnen Push-Listen abzumelden.

2.3. Scripte

Auf jeder Seite, auf der die Glocke angezeigt werden soll, müssen die erforderlichen Scripte wie unter 2.5. beschrieben eingebunden werden.

*Glockensymbol dient der einfachen An- und Abmeldung von Web Push Nachrichten

Diese sind:

  • jQuery
  • jQuery „Cookies“ Plugin
  • Konfiguration der Web Push Glocke
  • Vorzugsweise kundenspezifische Einstellungen in eigener Datei
  • AGN.webpush.bell.prepare.js
  • AGN.webpush.api.js
  • AGN.webpush.bell.js

Das Laden der Skripte erfolgt vorzugsweise in dieser Reihenfolge.

<!-- jQuery + plugins -->
<script type="text/javascript" src="jquery.js" />
<script type="text/javascript" src="jquery.cookies.js" />

<!-- Web push configuration -->
<script type="text/javascript" src="AGN.webpush.bell.config.js" />
<script type="text/javascript" src="custom-webpush-config.js" />

<!-- Web push API -->
<script type="text/javascript" src="AGN.webpush.api.js" />

<!-- Register service worker -->
<script type="text/javascript" src="AGN.webpush.bell.prepare.js" />

<!-- Show bell -->
<script type="text/javascript" src="AGN.webpush.bell.js" />

Hinweis: Ggf. sind Pfade und Dateinamen der Skripte anzupassen, da diese von der Infrastruktur und der Version der Skripte abhängen können!

2.4. manifest.json

Zur Unterstützung von Google Chrome ist ein Manifest-Dokument zu referenzieren. Dazu im <head>-Abschnitt diese Zeile eintragen:

<link rel="manifest" href="manifest.json">

Hinweis: Ggf. sind Pfad und Dateinamen der Manifest-Datei anzupassen, da diese von der Infrastruktur abhängen können!

2.5. Service Worker

Der Service Worker ist für die Anzeige der Push Nachrichten zuständig. Der Code findet sich in der Datei webpush-client-sw.js. Diese Datei wird nicht direkt in die Webseite eingebunden, sondern wird vom Browser selber geladen.

Die Service Worker-Datei kann in jedem beliebigen Verzeichnis der Domain liegen.

Der Gültigkeitsbereich entspricht dem URL-Pfad (ohne Protokoll, Domain und Dateiname), unter dem der Service Worker abgerufen wird, oder einem beliebigen Unterpfad davon, der nicht zwingend existieren muss. Sollten sich mehrere Service Worker im gleichen Verzeichnis befinden, so muss jeder einer eindeutigen Gültigkeitsbereich zugewiesen bekommen.

2.6. Konfiguration und Internationalisierung

Um die Konfiguration auf die eigenen Bedürfnisse anzupassen, empfiehlt es sich, ein zusätzliches Script zu laden, welches die Änderungen an der Standardkonfiguration vornimmt (z.B. ändern der Sprache). Dieses Skript sollte direkt nach agn.push.bell.config.js geladen werden. Das Script führt die Properties aus der nachfolgenden Tabelle auf, die geändert werden sollen und weißt ihnen die entsprechenden Werte zu wie z.B.:

AGN.push.config.company_id = 123
AGN.push.config.bell.language = 'de'

Die Konfiguration findet sich im Namespace „AGN.push.bell.config“. Die Werte lassen sich nur anpassen, bevor der Code für die Integration von Glocke und Overlay ausgeführt wird.

Die Konfigurationsmöglichkeiten sind:

Key Kunden-spezifische Einstellung erforderlich Bedeutung Beispiel
AGN.push.config.company_id ja Ihre ID AGN.push.config.company_id = 123456
AGN.push.config.push_api_base_url Nur bei EMM-Inhouse-Installation URL für Anmeldung am EMM
AGN.push.config.disable_vapid nein Verwendung von VAPID-Keys deaktivieren Nicht ändern
AGN.push.config.w3c.serviceworker_script_path ja Pfad zur ServiceWorker-Datei AGN.push.config.w3c.service
worker_script_path = '/js'
AGN.push.config.w3c.serviceworker_scope ja Gültigkeitsbereich des ServiceWorkers AGN.push.config.w3c.service
worker_scope = '/js/'
AGN.push.config.safari.website_push_id ja Eindeutige Website-ID, welche bei Apple registriert sein muß AGN.push.config.safari.website_
push_id = 'web.de.agnitas.emm.cid.123456
AGN.push.config.safari.webservice_url Nur bei EMM-Inhouse-Installation URL für Anmeldung am EMM
AGN.push.config.bell.push_list_ids ja IDs von Push-Listen für den An-/Abmeldung über das Glockensymbol AGN.push.config.bell.push_list_
ids = [1,2,5]
AGN.push.config.bell.language ja nach Bedarf Sprache der Texte AGN.push.config.bell.language = 'de'
AGN.push.config.bell.files.bellSubscribed ja Pfad zum Glockensymbol, wenn Besucher zu Push angemeldet ist AGN.push.config.bell.files.bellSubscribed = 'bell-subscribed.png'
AGN.push.config.bell.files.bellUnsub
scribed		 ja Pfad zum Glockensymbol, wenn Besucher nicht zu Push angemeldet ist AGN.push.config.bell.files.bell
Unsubscribed = 'bell-unsubscribed.png'
AGN.push.config.bell.translation.
{language}.subscription.query.title		 nein Titel für Overlay bei Anmeldung
AGN.push.config.bell.translation.
{language}.subscription.query.question		 nein Bestätigungsfrage für Overlay bei Anmeldung
AGN.push.config.bell.translation.
{language}.subscription.query.yes		 nein Beschriftung für Button zur Bestätigung der Anmeldung für Overlay bei Anmeldung
AGN.push.config.bell.translation.
{language}.subscription.query.no		 nein Beschriftung für Button zur Ablehnung der Anmeldung für Overlay bei Anmeldung
AGN.push.config.bell.translation.
{language}.unsubscription.query.title		 nein Titel für Overlay bei Abmeldung
AGN.push.config.bell.translation.
{language}.unsubscription.query.question		 nein Bestätigungsfrage für Overlay bei Abmeldung
AGN.push.config.bell.translation.
{language}.unsubscription.query.yes		 nein Beschriftung für Button zur Bestätigung der Abmeldung für Overlay bei Abmeldung
AGN.push.config.bell.translation.
{language}.unsubscription.query.no		 nein Beschriftung für Button zur Ablehnung der Abmeldung für Overlay bei Abmeldung
AGN.push.config.bell.translation.
{language}.bell.subscribe		 nein Beschriftung für Glocke zur Anmeldung zu Push (wenn Besucher nicht angemeldet)

Angepasst werden müssen alle Einstellungen, bei denen eine kundenspezifische Einstellung erforderlich ist. Einstellungen, die nur bei EMM-Inhouse-Installationen angepasst werden müssen, sollen (außer bei EMM-Inhouse-Installationen) nicht geändert werden. Der Rest kann bei Bedarf verändert werden.

Für EMM-Inhouse-Installationen:

Eine weitere Anpassung ist nur für EMM-Inhouse-Installationen in der Datei manifest.json erforderlich. Dort muss unter „gcm_sender_id“ eine bei Google registrierte Sender-ID eingetragen werden.

Als Sprachen sind „de“ und „en“ vordefiniert, es können aber, wenn das Schema der Keys verwendet wird, weitere Sprachen definiert werden.

Es empfiehlt sich, die Default-Konfiguration über die Datei AGN.webpush.bell.config.js zu laden und die kundenindividuellen Einstellungen in einer eigenen Datei danach zu laden:

<script type="text/javascript" src="AGN.webpush.bell.config.js" />
<script type="text/javascript" src="custom-bell-config.js" />

Dies verringert den Aufwand bei einem Update der JavaScript-Dateien.

2.7. Apple Safari

Apple Safari wird unterstützt, erfordert jedoch zusätzliche Schritte und ist mit kleinen Einschränkungen verbunden.

Als erstes werden Icons im PNG-Format in den Größen

16 x 16 Bildpunkte
32 x 32 Bildpunkte
64 x 64 Bildpunkte
128 x 128 Bildpunkte
256 x 256 Bildpunkte

benötigt.

Diese werden Safari in Form signierter ZIP-Dateien bereitgestellt.

! Die Art, wie Push Nachrichten bei Safari implementiert sind erlaubt es nicht, Icons für unterschiedliche Nachrichten zu definieren. Die Icons, welche für Safari hinterlegt sind, werden verwendet, solange Safari für Push angemeldet ist. Änderungen haben, während einer aktiven Anmeldung, keine Auswirkungen.

2.8. Testen der Integration

Stellen Sie beim Testen der Push-Nachrichten sicher, dass

  • Benachrichtigungen (Notifications) in Ihrem Browser freigeschaltet sind
  • Ihr Browser nicht in einem Privat- oder Gast-Modus läuft
  • Sie nicht den Vollbild-Modus des Browsers verwenden

weil in diesen Fällen Push-Nachrichten nicht angezeigt werden.

2.9. Gründe für fehlerhafte Browserdarstellung

Es gibt eine ganze Reihe von Gründen, warum Push-Nachrichten vom Browser nicht angezeigt werden:

  1. Firefox zeigt eine Push-Nachricht nur einige Sekunden lang an, danach wird sie automatisch geschlossen.
  2. Wird ein Browser geöffnet und liegen mehrere Push-Nachrichten (von unterschiedlichen Versendern) vor, so werden diese z.T. übereinander dargestellt, d.h. die unteren sind verdeckt.
  3. Wird der Browser im Vollbild-Modus betrieben, so verdeckt er dadurch das Push-Fenster.
  4. Wird der Browser im Privacy-Modus betrieben, so zeigt er generell keine Push-Nachrichten an.
  5. Wird die Anzeige von Push-Nachrichten in den Browser-Einstellungen deaktiviert, werden keine Push-Nachrichten mehr angezeigt.
  6. Ist die Push-Anmeldung nicht aktiv, so werden keine Push-Nachrichten an den Browser zugestellt (Achtung: ein vorhandener Service Worker ist nicht gleichbedeutend mit einer aktiven Anmeldung).
  7. Bei Samsung Internet ist der Empfang von Push-Nachrichten standardmäßig deaktiviert.
  8. Veraltete Browser wie der Internet Explorer oder Browser mit geringer Verbreitung stellen möglicherweise die benötigte Funktionalität zum Empfang von Push-Nachrichten nicht bereit.

Für weitere Auskünfte kontaktieren Sie bitte den AGNITAS-Support.