Register phone devices

Barua will send phone notifications only to devices your backend registered for a person. This release stores those registrations. Sending arrives in a following release, so nothing reaches a phone yet.

Before you start

Upload your app's Apple key first, as in Prepare phone notifications. A registration names the bundle id and environment of that upload. Notifications don't need to be turned on.

Your backend needs a live event key with devices:write. An existing key never gains it, so create a new one with manage.mjs action and --secret-file, using a connection that has setup:write:

{"action":"key.create","input":{"mode":"live","label":"Device registration","capabilities":["devices:write"]}}

Test keys can't register devices. Keep this key on your server.

From the app to your backend

After the person signs in, the app asks for notification permission and receives its device token from Apple. It sends the token as hex to your own backend, over the app's signed-in connection. The app never calls Barua.

func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  let token = deviceToken.map { String(format: "%02x", $0) }.joined()
  Task { try? await api.post("/me/device-token", body: ["token": token]) } // your backend
}

Apple can issue a new token, for example after the app is reinstalled, so send the current one at every launch.

Register the device

Your backend calls Barua with the person's external_id, the same one your events use:

curl -X PUT https://barua.ai/api/integrations/v1/devices \
  -H "Authorization: Bearer $BARUA_DEVICE_KEY" -H 'Content-Type: application/json' \
  -d '{"provider":"apns","app":"com.example.app","environment":"production","token":"6f1c9a2e4b7d0835c2e9f14a7b3d6e0c58a1f2b9d4e7c03a6b8f1e2d5c9a4b70","external_id":"user_42"}'

environment is production for App Store and TestFlight builds and sandbox for builds you run from Xcode, matching the key you uploaded. The answer is {"registered":true,"registered_at":"...","bound_at":"..."}. It never contains the token.

Registering the same token again is safe. When the same token arrives for another person, as on a shared phone, Barua moves the device to them. A person keeps at most 10 devices: an eleventh replaces one Apple reported gone, or else the one registered longest ago.

Barua answers 409 unknown_identity until it knows the person. Send their sign-up or first service event and wait until it shows as applied. Then register again. 409 notification_app_not_found means no key was uploaded for that bundle id and environment. On 429, wait for Retry-After and send the same request again. A 503 is safe to retry with backoff, because a repeated registration only refreshes the same device.

Forget the device

At sign-out, send the same body with DELETE. Include external_id: Barua then removes the device only while it still belongs to that person, so a late sign-out can't remove the next person's registration on a shared phone. The answer is {"deleted":true} or {"deleted":false}, and repeating it is harmless.

Erasing a person removes their devices, and deleting an app removes the devices registered for it. An external_id used again after an erasure starts with none.

Exact rules are in the events reference.