# Prepare phone notifications

Barua is adding notifications to your own iPhone app, sent through Apple
with your app's own Apple key. This release covers setup: you hand Barua the
key and record the owner's approvals. Sending arrives in a following
release, so nothing is sent yet. Your backend can already
[register your users' phones](/docs/guides/notification-devices.md).

## Before you start

You need the notification key file (`.p8`) from your Apple developer
account. Apple shows its 10-character key ID next to it, and your
10-character team ID in your account. Uploading needs a connection with
`setup:write`, and turning notifications on needs `launch:write` plus the
workspace owner's approval. The marketing statement needs `marketing:attest`.

## Upload the key

Read the current state with the
[installed helpers](/docs/guides/quickstart.md):

```sh
node "$BARUA_SKILL/scripts/manage.mjs" notifications
```

Then run `manage.mjs notification-app-upload --key-file <your .p8 file>`
with this JSON on stdin or in `--input-file`:

```json
{"bundleId":"com.example.app","environment":"production","keyId":"ABCDE12345","teamId":"TEAM123456","expectedRevision":0}
```

Use `production` for App Store and TestFlight builds and `sandbox` for
builds you run from Xcode. Upload once for each environment the key serves.
`expectedRevision` is the `appsRevision` that `notifications` just returned.
It is `0` until the workspace uploads its first app, and it rises by one on
every upload and delete.

The helper reads the file itself and never prints or returns the key. Barua
stores it encrypted and never shows it again. Barua checks that the file
holds an Apple key and that the IDs have the right shape. It does not
contact Apple yet, so a key that Apple refuses shows up at the first real
send.

To replace a key, read `notifications` and upload again with the current
`appsRevision`. A stale value is refused with `action_changed`. You also get
that answer when a retried upload already landed, or when another upload or
delete in the workspace came first. Read `notifications` again and check the
app's `keyId` before you repeat anything.

`notification-app-delete` removes an app and its key. It takes `bundleId`,
`environment` and `expectedRevision`. Deleting an app that is already gone
answers `deleted: false` and changes nothing.

## Turn notifications on

Request `notifications.enable` through `manage.mjs action`, with the current
`generation` as `expectedGeneration` (a string, `"0"` the first time). The
owner approves it. Once sending is available, any event you already approved
for service messages may also notify that person's phones. Each enable
raises `generation`.

## Marketing notifications

Apple allows marketing notifications only when your app asks each person in
its own words and lets them say no later in the app. Request
`notifications.marketing` with `enabled` set to `true`, your statement that
the app does this (20 to 2,000 characters), and the workspace `version` from
`notifications` as `expectedVersion`. The owner approves it, and Barua keeps
the statement, which owner approved it and when.

## Turn it off

`notifications.disable` turns this channel off, even after the workspace has
used its daily action limit. Email keeps working, and the marketing
statement stays as it was. To stop marketing alone, send
`notifications.marketing` with `enabled` set to `false`.

Exact inputs are in the
[management reference](/skills/barua-setup/references/management.md#phone-notifications).