Push providers on back(d)

Local development

Mon, 01 Jan 0001 00:00:00 +0000

You don’t need a device or a provider key to develop with push.

The capture provider

Give a platform provider: capture: the worker then stores each delivery in a push_outbox collection of the realm’s system database instead of calling a provider, with the message as it would have gone out and the outcome the device was given.

push:
 android: { provider: capture }
 web:
 provider: capture

It needs no credentials and no secrets, but it stores message content, so startup refuses it unless BACKD_DEV=true. Captured deliveries are kept for 24 hours.

FCM: Android, and iOS apps on the FCM SDK

Mon, 01 Jan 0001 00:00:00 +0000

FCM is the provider for Android, and for iOS apps that use the FCM SDK (ios.provider: fcm). backd sends through FCM’s HTTP v1 API from the worker, with an OAuth2 access token it mints from a service account.

1. A Firebase project

Open the Firebase console and create a project, or pick the one your app uses.
Android: add an Android app with your application id (the package name). Download google-services.json for the app’s build.
iOS over FCM: add an iOS app with the bundle id, download GoogleService-Info.plist, and upload an APNs authentication key under Project settings → Cloud Messaging → Apple app configuration (see APNs for where it comes from). That key lives in Firebase: backd never sees it.
In the linked Google Cloud project, enable the Firebase Cloud Messaging API (V1) (APIs & Services → Library). The legacy API is not used.

2. A service account

Project settings → Service accounts → Generate new private key. A JSON file downloads: it holds project_id, client_email and private_key.
Store it as a realm secret, from the file:

backd secret set --realm acme --name FCM_SERVICE_ACCOUNT < service-account.json

The value is read from standard input, newlines included, and encrypted with the instance’s BACKD_SECRETS_KEY. Delete the downloaded file afterwards.

APNs: iOS

Mon, 01 Jan 0001 00:00:00 +0000

ios.provider: apns sends to iPhones and iPads directly through Apple’s push service: HTTP/2, authenticated with a token signed by a key you create in your Apple Developer account. (Apps on the FCM SDK use FCM instead.)

1. The key

In the Apple Developer account: Certificates, Identifiers & Profiles → Keys → +. Name it, tick Apple Push Notifications service (APNs), and continue.
Download the .p8 file: it can be downloaded once. Note the 10-character Key ID shown.
Note your Team ID: the 10 characters at the top right of the account’s Membership details.
The topic is your app’s bundle id (for example com.acme.app). The app’s App ID must have the Push Notifications capability enabled.

2. The secret

backd secret set --realm acme --name APNS_KEY < AuthKey_AB12CD34EF.p8

The file is read as it is, newlines included.

Web Push: browsers

Mon, 01 Jan 0001 00:00:00 +0000

web.provider: webpush sends to browsers with the standard Web Push protocol: no account with a vendor, only a VAPID key pair that identifies your realm to the browsers’ push services (Google, Mozilla, Apple, Microsoft).

1. The key pair

backd push web-keys --realm acme

It generates a P-256 key pair, stores the private half as the realm secret VAPID_PRIVATE_KEY, and prints the public half with the realm.yaml snippet:

push:
 web:
 provider: webpush
 public_key: BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U
 private_key: secret:VAPID_PRIVATE_KEY
 subject: secret:VAPID_SUBJECT

2. The subject

Browsers’ push services use a contact URI to reach you when something goes wrong with your pushes:

Push providers on back(d)

Local development

The capture provider#

FCM: Android, and iOS apps on the FCM SDK

1. A Firebase project#

2. A service account#

APNs: iOS

1. The key#

2. The secret#

Web Push: browsers

1. The key pair#

2. The subject#

The capture provider

1. A Firebase project

2. A service account

1. The key

2. The secret

1. The key pair

2. The subject