Notification API

Mit der Notification API kann eine Webseite Nachrichten auf Systemebene versenden.

Links

https://stackoverflow.com/questions/32717824/notification-system-using-php-and-mysql Allgmeine Überlegungen kein Push
https://webdamn.com/build-push-notification-system-with-php-mysql/
https://web-push-book.gauntface.com/ // must read
https://github.com/gauntface/web-push-book // node.js code beispiel zum web-push-book
https://github.com/Minishlink/web-push-php-example/tree/master/src // Beispiel (ungetestet)
https://github.com/web-push-libs/web-push-php // Web-Push Lib für PHP (senden von Notifications)
https://developers.google.com/web/fundamentals/codelabs/push-notifications

Stichworte

Observer Design Pattern

Übersicht

Dieses Tutorial orientiert sich am web-push-book. ein weiterer guter Einstieg ist in Googles web fundamentals.

Schritte in der Übersicht

1. Subscription
2. Send Push Message
3. Handle Push Event

Schritt 1: Subscription

1. Get permission
2. Get PushSubscription
3. Send PushSubscription to Server
4. Store PushSubscription Details

=> JavaScript PushAPI

https://developer.mozilla.org/en-US/docs/Web/API/Push_API

Aplication Server Keys

Der VAPID Key verifiziert den Server, so dass der Browser später weiß, dass es sich um den echten Server handelt. Eigentlich wird ein Schlüsselpaar generiert s.u.

Schritt 2: Push Message senden

Server -> WebPush Protocol Request -> PushService -> End Device

• Der Server der eine Nachrichtschicken will schickt diese Standartisiert an einen Push Service.
• Welche URL dieser hat teilt der Browser im Schritt eins mit.
• Der PushService schickt diese dann wenn der Browser des Nutzers Online ist an den Nutzer.
• Der PushService kann Instruktionen entgegennehmen:
  • Lebensdauer einer Push Nachricht - danach wird sie verworfen.
  • Dringlichkeit (der Service entscheidet z.B. bei geringer Batteriekapazität nur Prio-Nachrichten durchzulassen)
  • Topic - Eine Nachricht mit dem selben Topic wie eine alte ersetzt die Alte.

Schritt 3: Push Events auf dem Endgerät

https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API

Message kommt an -> Browser spricht mit Service Worker -> Push Event wird aufgelöst.

• Wenn die Nachricht abgeliefert wurde wird dies dem Service Worker mitgeteilt. Der Service Worker ist eine JavaScript Datei, die der Browser aufrufen und ausführen kann, ohne dass die Webseite aufgerufen werden muss.
• Innerhalb des Service Workers kann man eine spezielle API aufrufen. Diese ist nur im Service Worker verfügbar.
• Der ServiceWorker kann ausgeführt werden wenn der Browser geschlossen ist.
• Im Push Event des Service Worker kann man Hintergrundaufgaben erledigen (Analytics, Seiten Offline Cachen...)

Subscription in Detail

1. Feature Detection
   1. Check for serviceWoker on navigator
   2. Check for PushManager on window
2. Register Service Worker
3. Request Permission

Feature Detection

if (!('serviceWorker' in navigator)) {
    // Service Worker isn't supported on this browser, disable or hide UI.
    return;
  }

  if (!('PushManager' in window)) {
    // Push isn't supported on this browser, disable or hide UI.
    return;
  }

Register Service worker

function registerServiceWorker() {
  return navigator.serviceWorker.register('service-worker.js')
  .then(function(registration) {
    console.log('Service worker successfully registered.');
    return registration;
  })
  .catch(function(err) {
    console.error('Unable to register service worker.', err);
  });
}

Der Code veranlasst den Browser das service-worker.js File vom Server zu laden. Im Hintergrund wird der Browser das enthaltene JS ausführen. Wenn alles klappt wird ein Promise von register(aufgelöst) und gibt die ServiceWorkerRegistration zurück. Diese können wir für den Zugriff auf die PushManager API nutzen.

https://developer.mozilla.org/en-US/docs/Web/API/PushManager

Request Permission

Die API um eine Permission vom User zu bekommen hat sich verändert. Früher hat es über eine Callback Funktion funktioniert jetzt über die Rückgae einer Promise. Daher sollten wir beides implementieren.

function askPermission() {
  return new Promise(function(resolve, reject) {
    const permissionResult = Notification.requestPermission(function(result) {
      resolve(result);
    });

    if (permissionResult) {
      permissionResult.then(resolve, reject);
    }
  })
  .then(function(permissionResult) {
    if (permissionResult !== 'granted') {
      throw new Error('We weren\'t granted permission.');
    }
  });
}

Die Methode Notification.requestPermission() zeigt dem User die Aufforderung.

getPermissionState

requestPermission lockt den Hauptthread, daher ist es sinnvoll zu checken, welchen Permission Status der User im Moment hat.

function getNotificationPermissionState() {
  if (navigator.permissions) {
    return navigator.permissions.query({name: 'notifications'})
    .then((result) => {
      return result.state;
    });
  }

  return new Promise((resolve) => {
    resolve(Notification.permission);
  });
}

Subscribe mit dem PushManager

Service Worker ist registriert und der User hat die Erlaubnis gegeben. Jetzt kann man den User im PushManager registrieren.

function subscribeUserToPush() {
  return getSWRegistration()
  .then(function(registration) {
    const subscribeOptions = {
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(
        'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U'
      )
    };

    return registration.pushManager.subscribe(subscribeOptions);
  })
  .then(function(pushSubscription) {
    console.log('Received PushSubscription: ', JSON.stringify(pushSubscription));
    return pushSubscription;
  });
}

Über die subscribe Methode gibt man ein Options Objekt mit.

* userVisibleOnly erlaubt im Moment nur true (für Hintergrund Aktivitäten ohne Nachricht
* applicationServerKey enthält den öffentlichen Schlüssel der App. Der Push Service speichert den Schlüssel mit der User Info und kann so später eine Nachricht auf Gültigkeit checken. Wenn der Server eine Message seden möchte, generiert er zuerst einen Authorization Header mit dem Private Key. Mit dem Public Key kann der Push Service checken ob die Nachricht wirklich vom offiziellen Server stammt. Er eignet sich zum entschlüsseln, aber nicht zum verschlüsseln. Verschlüsseln geht nur mit dem Private Key, der immmer gut geschützt sein muss. 

Server Keys

Technisch gesehen sind die Keys optional. Chrome verlangt sie bei Firefox ist der Parameter applicationServerKey Optional. Sie stellen aber sicher, dass der User nur von authentifizierten Servern Nachrichten bekommt.

Die Spezifikation der Schlüssel nennt sich VAPID ein VAPID Key und ein applicationServerKey sind also das Selbe.

https://tools.ietf.org/html/draft-thomson-webpush-vapid-02

Schlüssel generieren

Für jede Anwendung sollte man einmalig ein eigenes Schlüsselpaar generieren. Ein Schlüsselpaar kann man ganz einfach über dieses Tool generieren:

https://web-push-codelab.glitch.me/

Oder über die Command Line mit dem web-push Tool:

$ npm install -g web-push
$ web-push generate-vapid-keys

Nachteile von subscribe() als permission request

Wenn man subscribe() aufruft und der Browser noch keine Erlaubnis hat, fragt der Browser direkt den User. Das kann ein Nachteil sein, wenn man selbst die Kontrolle über die Anfrage haben möchte. Mit Notification.requestPermission() geht das.

PushSubscription im Detail

Wenn man die Permission des Users hat und subscribe() sendet bekommt man ein Promise, das in einem PushSubscription Objekt aufgelöst wird.

function subscribeUserToPush() {
  return getSWRegistration()
  .then(function(registration) {
    const subscribeOptions = {
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(
        'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U'
      )
    };

    return registration.pushManager.subscribe(subscribeOptions);
  })
  .then(function(pushSubscription) {
    console.log('Received PushSubscription: ', JSON.stringify(pushSubscription));
    return pushSubscription;
  });
}

Wenn man das pushSubscription Objekt über JSON.stringify() anschaut bekommt man etwas in dieser Art.

{
  "endpoint": "https://some.pushservice.com/something-unique",
  "keys": {
    "p256dh": "BIPUL12DLfytvTajnryr2PRdAgXS3HGKiLqndGcJGabyhHheJYlNGCeXl1dn18gSJ1WAkAPIxr4gK0_dQds4yiI=",
    "auth":"FPssNDTKnInHVndSTdbKFw=="
  }
}

Subscription auf eigenem Server speichern

Jetzt müssen wir uns merken das der User den Service abonniert hat und speichern dazu am Besten das Stringyfied Objekt. Man kann aber das Ganze auch manuell aus dem Objekt erzeugen.

const subscriptionObject = {
  endpoint: pushSubscription.endpoint,
  keys: {
    p256dh: pushSubscription.getKeys('p256dh'),
    auth: pushSubscription.getKeys('auth')
  }
};

// The above is the same output as:

const subscriptionObjectToo = JSON.stringify(pushSubscription);

Den String übermitteln wir einfach als POST Request:

function sendSubscriptionToBackEnd(subscription) {
  return fetch('/api/save-subscription/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(subscription)
  })
  .then(function(response) {
    if (!response.ok) {
      throw new Error('Bad status code from server.');
    }

    return response.json();
  })
  .then(function(responseData) {
    if (!(responseData.data && responseData.data.success)) {
      throw new Error('Bad response from server.');
    }
  });
}

Der Server speichert den Datensatz, um ihn später für Notifications zu Nutzen. Bei einem Node.js Server könnte das so aussehen:

app.post('/api/save-subscription/', function (req, res) {
  if (!isValidSaveRequest(req, res)) {
    return;
  }

  return saveSubscriptionToDatabase(req.body)
  .then(function(subscriptionId) {
    res.setHeader('Content-Type', 'application/json');
    res.send(JSON.stringify({ data: { success: true } }));
  })
  .catch(function(err) {
    res.status(500);
    res.setHeader('Content-Type', 'application/json');
    res.send(JSON.stringify({
      error: {
        id: 'unable-to-save-subscription',
        message: 'The subscription was received but we were unable to save it to our database.'
      }
    }));
  });
});

Gut zu wissen

• Die Notifications sind fest mit dem Browser verbunden. Nachrichten kommen also auch immer nur über den Browser an, mit dem der User den Service abonniert hat.
• Der PushService wird vom Browser vorgegeben. Jeder Browser hat andere Endpoints.