expo-pusher-push-notifications 0.5.1 → 0.5.2

package/README.md

@@ -7,22 +7,48 @@ Push notifications for Expo and React Native. Two ways to use it:
 
 Both get custom sounds, Android channels, badges, and local notifications.
 
+## Prerequisites
+
+Do these before installing. Which ones you need depends on your path.
+
+**Android (all paths)**
+
+1. Create a project in the [Firebase console](https://console.firebase.google.com) and add an Android app with your `android.package`.
+2. Download `google-services.json` into your project and set `"android": { "googleServicesFile": "./google-services.json" }` in `app.json`.
+3. Beams path only: in Firebase → Project settings → Service accounts, generate a private key (JSON). You'll upload it to Beams.
+
+**Apple (all paths)**
+
+1. In your Apple Developer account, enable the **Push Notifications** capability on your App ID (`ios.bundleIdentifier`).
+2. Create an **APNs auth key (.p8)** under Keys (note the Key ID and Team ID). A .p12 certificate works too, but the key is simpler and doesn't expire.
+3. Set `apsEnvironment` in the plugin: `development` for dev builds, `production` for TestFlight / App Store. The plugin writes the `aps-environment` entitlement for you.
+
+**Beams (Interests / Users paths only)**
+
+Create a Beams instance in the [Pusher dashboard](https://dashboard.pusher.com/beams), upload your APNs key and FCM service account JSON, and copy the instance ID. Skip this entirely for the device-token path.
+
+Full details in [Setup](docs/setup.md).
+
+## Install
+
 ```sh
 npx expo install expo-pusher-push-notifications
 ```
 
-Needs Expo SDK 58+ and a development build (Expo Go can't load native modules).
+Needs Expo SDK 58+ and a development build (Expo Go can't load native modules). Run `npx expo prebuild` after adding the plugin.
 
-## Quick start
+## Getting started
 
-Add the config plugin to `app.json`:
+Pick the path that matches how you send pushes. You can combine Interests and Users; DeviceToken is for when you don't use Beams at all.
+
+### Interests (Beams topics)
+
+`app.json`:
 
 ```json
 ["expo-pusher-push-notifications", { "instanceId": "YOUR_BEAMS_INSTANCE_ID" }]
 ```
 
-Then in your app:
-
 ```ts
 import { Interests } from 'expo-pusher-push-notifications';
 
@@ -30,7 +56,43 @@ await Interests.start('YOUR_BEAMS_INSTANCE_ID');
 await Interests.subscribe('news');
 ```
 
-That device now gets pushes sent to `news`. Full console steps (APNs, Firebase, Beams) are in [Setup](docs/setup.md).
+That device now gets pushes sent to `news`.
+
+### Users (Beams, bind to your signed-in user)
+
+`app.json`:
+
+```json
+["expo-pusher-push-notifications", { "instanceId": "YOUR_BEAMS_INSTANCE_ID", "mode": "users" }]
+```
+
+```ts
+import { Users } from 'expo-pusher-push-notifications';
+
+await Users.start('YOUR_BEAMS_INSTANCE_ID');
+// after your own sign-in; url = your Beams token provider
+await Users.login('user-123', {
+  url: 'YOUR_BEAMS_TOKEN_URL',
+  headers: { Authorization: `Bearer ${sessionToken}` },
+});
+```
+
+That user now gets pushes on every device they're signed in on.
+
+### DeviceToken (no Beams)
+
+`app.json` — no `instanceId`:
+
+```json
+["expo-pusher-push-notifications", { "mode": "device" }]
+```
+
+```ts
+import { DeviceToken } from 'expo-pusher-push-notifications';
+
+const { type, token } = await DeviceToken.start(); // type: 'fcm' | 'apns'
+// send token to your backend, which pushes via FCM / APNs directly
+```
 
 ## Path 1: Pusher Beams
 

package/docs/direct.md

@@ -1,5 +1,7 @@
 # Device token (raw FCM / APNs, no Beams)
 
+
+> Before you start: finish the [Prerequisites](setup.md#prerequisites) (Firebase + APNs; no Beams instance needed).
 **Use this when** your app has its own push path: your backend (or another provider) sends to FCM and APNs directly.
 No Beams instance needed. You get the raw native token and do what you want with it.
 

package/docs/interests.md

@@ -1,5 +1,7 @@
 # Interests (topics)
 
+
+> Before you start: finish the [Prerequisites](setup.md#prerequisites) (Firebase + APNs, plus a Beams instance).
 Use interests when many devices should get the same push. Think topics: `news`, `order-42`, `team-7`.
 
 ## Client

package/docs/setup.md

@@ -1,5 +1,27 @@
 # Setup
 
+## Prerequisites
+
+Set these up first. Android and Apple steps apply to every path; the Beams step only to Interests / Users.
+
+### Android: Firebase / FCM
+
+1. Create a project in the [Firebase console](https://console.firebase.google.com).
+2. Add an Android app whose package name matches `android.package` in `app.json`.
+3. Download `google-services.json`, put it in your project root, and set `"android": { "googleServicesFile": "./google-services.json" }`.
+4. **Beams only:** Project settings → Service accounts → *Generate new private key*. Keep the JSON for the Beams dashboard.
+
+### Apple: APNs
+
+1. In [Apple Developer → Identifiers](https://developer.apple.com/account/resources/identifiers/list), open your App ID (`ios.bundleIdentifier`) and enable **Push Notifications**.
+2. Under Keys, create a key with **Apple Push Notifications service (APNs)** enabled. Download the `.p8` and note the Key ID and your Team ID. (A `.p12` APNs certificate also works, but certificates expire yearly.)
+3. Choose `apsEnvironment` in the plugin config: `development` for dev builds, `production` for TestFlight and the App Store. The plugin writes the `aps-environment` entitlement and the `remote-notification` background mode — you don't edit Xcode by hand.
+4. Test on a real device; the iOS simulator doesn't get APNs tokens reliably.
+
+### Beams (Interests / Users only)
+
+Create an instance in the [Pusher dashboard](https://dashboard.pusher.com/beams), upload the APNs key (with Key ID / Team ID) and the FCM service account JSON, and copy the instance ID. For the device-token path, skip this — your backend talks to FCM / APNs with those same credentials.
+
 ## Install
 
 ```sh
@@ -31,6 +53,8 @@ npx expo install expo-pusher-push-notifications
 }
 ```
 
+Leave out `instanceId` (and set `"mode": "device"`) if you use the device-token path.
+
 Then run `npx expo prebuild` and build a development build. Expo Go cannot load this native module.
 
 ### Plugin options
@@ -47,11 +71,15 @@ Then run `npx expo prebuild` and build a development build. Expo Go cannot load
 
 The plugin also adds the `remote-notification` background mode on iOS. On Android, the library manifest declares one FCM service (it extends the Beams `MessagingService`), the `POST_NOTIFICATIONS` permission, and a receiver for scheduled local notifications.
 
-## Console setup
+## Start, per path
 
-1. **iOS:** enable the Push Notifications capability. The plugin sets the entitlement. Create an APNs auth key (.p8).
-2. **Android:** create a Firebase project, download `google-services.json`, and point `android.googleServicesFile` at it.
-3. **Beams path only:** create a Beams instance in the [Pusher dashboard](https://dashboard.pusher.com/beams), then upload your APNs key and your FCM service account to it.
+Pick one (Interests and Users can be combined).
+
+| Path | Plugin config | First call |
+|---|---|---|
+| Interests | `instanceId` | `Interests.start(instanceId)` then `Interests.subscribe('news')` — see [Interests](interests.md) |
+| Users | `instanceId`, `mode: "users"` | `Users.start(instanceId)` then `Users.login(userId, tokenProvider)` after sign-in — see [Users](users.md) |
+| DeviceToken | `mode: "device"`, no `instanceId` | `DeviceToken.start()` → send `token` to your backend — see [Device token](direct.md) |
 
 ## Permissions
 

package/docs/users.md

@@ -1,5 +1,7 @@
 # Bind a device to a user
 
+
+> Before you start: finish the [Prerequisites](setup.md#prerequisites) (Firebase + APNs, plus a Beams instance).
 Bind the device to the signed-in user so pushes for that user reach every device they're signed in on. Call `Users.login` after your own sign-in, and `Users.logout` on sign-out.
 
 ## In the app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-pusher-push-notifications",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Push notifications for Expo: Pusher Beams (interests / users) or raw FCM/APNs device tokens (no EAS needed), with custom sounds, channels, badges and local notifications",
   "main": "build/index.js",
   "types": "build/index.d.ts",