Push notifications

backd sends pushes itself. There are three lanes (FCM for Android, APNs for iOS and Web Push for browsers) and each is a small built-in sender in the worker: you configure credentials once, and your functions only say who gets what. backd keeps the device registry, the templates and their languages, the per-user limits, the retries per device and the records of what went out.

Turning it on#

A realm enables push with a push: section in realm.yaml. Each platform you support gets a block naming its provider and that provider’s credentials; a platform with no block is refused (400 platform_not_enabled). Credentials are realm secrets, written secret:NAME like the keys of sign-in providers and storage: the value never goes in the file.

push:
  android:
    provider: fcm
    credentials: secret:FCM_SERVICE_ACCOUNT   # the service-account JSON
  ios:
    provider: apns                            # or fcm, with `credentials`
    key: secret:APNS_KEY                      # the .p8 signing key
    key_id: "AB12CD34EF"
    team_id: "T123456789"
    topic: com.acme.app                       # the app's bundle id
    sandbox: false
  web:
    provider: webpush
    public_key: BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U
    private_key: secret:VAPID_PRIVATE_KEY
    subject: secret:VAPID_SUBJECT             # mailto: or https:
    endpoint_hosts:                           # where a browser's subscription may point; defaults shown
      - fcm.googleapis.com
      - updates.push.services.mozilla.com
      - web.push.apple.com
      - "*.notify.windows.com"
  devices:
    max_per_user: 10
    stale_after: 60d
  delivery:
    timeout: 60s
    retry: { attempts: 5, backoff: 30s }
    parallelism: 20
  limits:
    per_user: { per_minute: 5, per_day: 24 }
  send_retention: 30d

• BACKD_SECRETS_KEY is required: device tokens are stored encrypted with it, and the senders read the providers’ credentials from the realm’s secrets. A realm with push: and no key refuses to start.
• A secret that isn’t set is a warning at startup and 503 push_unavailable when a push needs it: write the configuration first, set the secrets after.
• provider: capture stores deliveries instead of sending them; startup refuses it unless BACKD_DEV=true.
• Without push: the realm behaves as before: the device endpoints answer 404 push_not_configured, and a function that declares push fails startup.

Messages and templates#

A push is written in the user’s own language (user.locale, which is always one of the realm’s locales; the realm’s default_locale for a user who never chose one), from a template, like an email:

<realm>/push/
  order-shipped/   en.yaml  es.yaml

# <realm>/push/order-shipped/en.yaml
title: "Your order {{.Data.order_no}} is on its way"
body: "It should arrive {{.Data.eta}}."
link: "acme://orders/{{.Data.order_id}}"     # optional: opened when the notification is tapped

• One folder per kind, one file per language. Every language the realm lists needs a file of every kind, or startup fails naming the missing files. Files are parsed and test-rendered at startup, kept in memory and part of the configuration fingerprint. backd template realm writes push/example/en.yaml.
• Data: {{.Realm}}, {{.User.Locale}} and {{.Data}}, the data of the call. Templates get no address or profile field, because lock screens are seen by others.
• Declaring kinds: a function that sends pushes declares push: true, or push: { kinds: [order-shipped], audience: false } in function.yaml. kinds limits the named kinds; raw title and body sends stay available. Startup checks that every declared kind has templates, and that the realm has a push: section.
• Raw messages: a function may pass title and body itself (kind raw), already in the right language, when the text is data, such as a chat preview.
• No system pushes: backd sends no pushes of its own; every push comes from your app.

The message#

What a field does where it isn’t supported is nothing, never an error:

Size. The message is rendered in every listed language and shaped the way each enabled platform’s provider receives it; one over its provider’s limit (4 KiB for FCM and APNs, 3,993 bytes of plaintext for Web Push) is refused with payload_too_large before anything is queued, naming the platform and the language.