expo-pusher-push-notifications 0.5.1 → 0.5.3

package/README.md

@@ -1,84 +1,127 @@
 # expo-pusher-push-notifications
 
-Push notifications for Expo and React Native. Two ways to use it:
+Push notifications for Expo and React Native, with two independent paths:
 
-1. **Pusher Beams** — subscribe devices to interests (topics) and/or bind them to your signed-in users. Uses [Pusher Beams](https://pusher.com/beams).
-2. **Device token** — get the raw FCM (Android) / APNs (iOS) token for your own push path. No Beams, no `expo-notifications`, no EAS.
+- **Pusher Beams** — subscribe devices to interests (topics) and/or bind them to your signed-in users. Uses [Pusher Beams](https://pusher.com/beams).
+- **Device token** — get the raw FCM (Android) / APNs (iOS) token for your own push path. No Beams, no `expo-notifications`, no EAS.
 
 Both get custom sounds, Android channels, badges, and local notifications.
 
+You can use **either or both**: Beams only, device token only, or Beams and device token together in the same app. The two paths are independent, and each section below is self-contained, so follow only the one(s) you need.
+
+## Prerequisites
+
+Links only; set up what your path needs.
+
+- [Android: Firebase / FCM setup](https://firebase.google.com/docs/android/setup) — create a Firebase project and add `google-services.json` (all paths).
+- [Apple: APNs setup](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns) — enable Push Notifications and create an APNs key (all paths).
+- [Pusher Beams instance setup](https://pusher.com/docs/beams/getting-started/create-instance/) — create an instance and upload your FCM / APNs credentials (Beams path only).
+
+More detail in [Setup](docs/setup.md#prerequisites).
+
+## 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
+## Beams path
 
-Add the config plugin to `app.json`:
+Use Pusher Beams to push to topics (interests) and/or to your signed-in users.
 
-```json
-["expo-pusher-push-notifications", { "instanceId": "YOUR_BEAMS_INSTANCE_ID" }]
-```
+1. **Add the plugin with your Beams instance ID** in `app.json`. Add `"mode": "users"` if you bind users (interests still work in that mode):
 
-Then in your app:
+   ```json
+   ["expo-pusher-push-notifications", { "instanceId": "YOUR_BEAMS_INSTANCE_ID", "apsEnvironment": "development" }]
+   ```
 
-```ts
-import { Interests } from 'expo-pusher-push-notifications';
+2. **Prebuild and build** a development build: `npx expo prebuild`.
 
-await Interests.start('YOUR_BEAMS_INSTANCE_ID');
-await Interests.subscribe('news');
-```
+3. **Start Beams and subscribe to interests** (topics like `news`, `order-42`):
 
-That device now gets pushes sent to `news`. Full console steps (APNs, Firebase, Beams) are in [Setup](docs/setup.md).
+   ```ts
+   import { Interests } from 'expo-pusher-push-notifications';
 
-## Path 1: Pusher Beams
+   await Interests.start('YOUR_BEAMS_INSTANCE_ID'); // asks for permission
+   await Interests.subscribe('news');
+   await Interests.unsubscribe('news');
+   ```
 
-### Subscribe to interests (topics)
+4. **Bind the device to your signed-in user** (optional), so pushes for that user reach all their devices:
 
-Interests are topics like `news`, `order-42`, or `team-7`. Every device subscribed to one gets the push.
+   ```ts
+   import { Users } from 'expo-pusher-push-notifications';
 
-```ts
-await Interests.subscribe('order-42');
-await Interests.unsubscribe('order-42');
-```
+   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}` },
+   });
+   ```
 
-More in [Interests](docs/interests.md).
+5. **On sign-out**, clear state:
 
-### Bind a device to a user
+   ```ts
+   await Users.logout();
+   await Interests.reset();
+   ```
 
-To get pushes meant for a specific signed-in user on all their devices, bind the device to that user.
+6. **Send pushes** from your server with the Beams API (to interests or user IDs).
 
-```ts
-import { Users } from 'expo-pusher-push-notifications';
+More in [Interests](docs/interests.md) and [Users](docs/users.md).
 
-await Users.start('YOUR_BEAMS_INSTANCE_ID');
+## Device token path
 
-// after your own sign-in (url = your Beams token provider)
-await Users.login('user-123', {
-  url: 'YOUR_BEAMS_TOKEN_URL',
-  headers: { Authorization: `Bearer ${sessionToken}` },
-});
+Get the raw FCM (Android) / APNs (iOS) token and push from your own backend. No Beams, no `expo-notifications`, no EAS.
 
-// on sign-out
-await Users.logout();
-```
+1. **Add the plugin** in `app.json` with `"mode": "device"` and no `instanceId`:
+
+   ```json
+   ["expo-pusher-push-notifications", { "mode": "device", "apsEnvironment": "development" }]
+   ```
+
+2. **Prebuild and build** a development build: `npx expo prebuild`.
+
+3. **Get the token** and send it to your backend:
+
+   ```ts
+   import { DeviceToken } from 'expo-pusher-push-notifications';
+
+   const token = await DeviceToken.start(); // { type: 'fcm' | 'apns', platform, token }
+   await api.saveDevice(token);
+   ```
+
+4. **Keep it fresh** — tokens rotate:
 
-You can use interests and users together. More in [Users](docs/users.md).
+   ```ts
+   DeviceToken.onChange((t) => api.saveDevice(t));
+   ```
 
-## Path 2: Device token
+5. **On sign-out**, delete it: `await DeviceToken.delete();`
 
-No Beams instance needed (leave `instanceId` out of the plugin config).
+6. **Send pushes** from your backend directly to FCM / APNs with that token.
+
+More in [Device token](docs/direct.md).
+
+## Using both together
+
+Follow the Beams path, then also grab the raw token. `registerForDeviceToken()` works in any mode, so it doesn't stop Beams:
 
 ```ts
-import { DeviceToken } from 'expo-pusher-push-notifications';
+import { Interests, registerForDeviceToken, DeviceToken } from 'expo-pusher-push-notifications';
+
+await Interests.start('YOUR_BEAMS_INSTANCE_ID');
+await Interests.subscribe('news');
 
-const token = await DeviceToken.start(); // { type: 'fcm' | 'apns', platform, token }
-DeviceToken.onChange((t) => { /* token rotated */ });
-await DeviceToken.delete(); // on sign-out
+const token = await registerForDeviceToken(); // raw FCM / APNs token
+await api.saveDevice(token);
+DeviceToken.onChange((t) => api.saveDevice(t));
 ```
 
-You get the token in the app; sending it to your backend and pushing from there is up to you. More in [Device token](docs/direct.md).
+Keep the plugin config from the Beams path (with `instanceId`). Don't call `DeviceToken.start()` here, as that switches the module to device-only mode.
 
 ## Extras
 

package/docs/direct.md

@@ -1,6 +1,9 @@
 # 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.
 
 ## Client

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.
+The Beams paths (Interests, Users) and the DeviceToken path are independent: use either or both. To use both, start Beams and call `registerForDeviceToken()` (works in any mode) instead of `DeviceToken.start()`.
+
+| 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.3",
   "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",