Samuel Newman
ff731849b0
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Eric Bailey <git@esb.lol>
98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
# push-notification
|
|
|
|
Sends sample APNS payloads to a booted iOS simulator via `xcrun simctl push`.
|
|
Useful for exercising `useNotificationsHandler` (`src/lib/hooks/useNotificationHandler.ts`)
|
|
without a real APNS round-trip — foreground display behavior, tap responses,
|
|
and notification-driven navigation.
|
|
|
|
## What this does and doesn't cover
|
|
|
|
**Covers** — anything in `useNotificationsHandler`:
|
|
|
|
- `setNotificationHandler` foreground behavior (banner, list, badge, sound flags)
|
|
- `addNotificationResponseReceivedListener` tap handling
|
|
- Account-switch flow when `recipientDid` differs from the signed-in account
|
|
- Navigation routing for each `reason` (post threads, profiles, conversations)
|
|
|
|
**Does not cover** — `BlueskyNSE` (the iOS Notification Service Extension):
|
|
|
|
- Communication Notification styling for chat messages
|
|
- Badge increment via `mutateWithBadge`
|
|
- Custom `dm.aiff` sound for chat messages
|
|
|
|
The simulator does not reliably invoke NSEs for `simctl push` on recent iOS
|
|
versions (verified bypassed on iOS 26.4). To test NSE behavior, run on a real
|
|
device with a real APNS push, or unit-test `NotificationService.didReceive`
|
|
directly in Xcode.
|
|
|
|
## Setup
|
|
|
|
1. Boot an iOS simulator and install the app:
|
|
```
|
|
pnpm ios
|
|
```
|
|
2. Sign in to the account you'll be testing against. The `recipientDid` in
|
|
each payload is substituted at send time and must match the signed-in DID,
|
|
otherwise:
|
|
- Chat notifications trigger the account-switch flow
|
|
- Other reasons are silently dropped by the handler
|
|
3. Find your DID. Easiest: visit your profile in a web browser and copy it
|
|
from the URL, or grep dev logs for `currentAccount`.
|
|
|
|
## Usage
|
|
|
|
```
|
|
./send.sh <payload-name> [--did <did>] [--device <udid>] [--bundle <id>]
|
|
```
|
|
|
|
Pass the DID once via env var to avoid repeating it:
|
|
|
|
```
|
|
export BLUESKY_TEST_DID=did:plc:yourdidhere
|
|
|
|
./send.sh like
|
|
./send.sh chat-message
|
|
./send.sh follow
|
|
```
|
|
|
|
Defaults: `--device booted`, `--bundle xyz.blueskyweb.app`. Run `./send.sh --help`
|
|
for the full list of available payloads.
|
|
|
|
## Foreground vs background
|
|
|
|
`useNotificationsHandler` behaves differently depending on app state:
|
|
|
|
- **Foreground** — `setNotificationHandler.handleNotification` decides whether
|
|
to show a banner, play a sound, etc. For chat reasons, the banner is
|
|
suppressed if `payload.convoId === currentConvoId` (you're already viewing
|
|
that conversation).
|
|
- **Background or tapped** — `addNotificationResponseReceivedListener` fires
|
|
on tap and runs the navigation routing in `notificationToURL`.
|
|
|
|
To test the response listener, background the app first (`cmd+shift+H` in the
|
|
sim), send the push, then tap the banner.
|
|
|
|
## Available payloads
|
|
|
|
| Payload | Reason | Navigation target |
|
|
|---|---|---|
|
|
| `like.apns` | `like` | post thread (from `subject`) |
|
|
| `reply.apns` | `reply` | post thread (from `uri`) |
|
|
| `follow.apns` | `follow` | sender's profile (from `uri.host`) |
|
|
| `chat-message.apns` | `chat-message` | `MessagesConversation` with `convoId` |
|
|
| `chat-reaction.apns` | `chat-reaction` | `MessagesConversation` with `convoId` |
|
|
|
|
The `subject` AT URIs reference fake post rkeys, so the destination screens
|
|
will fail to load real content — that's expected. Routing exercises the
|
|
navigation path, not the data fetch.
|
|
|
|
## Adding a new payload
|
|
|
|
1. Copy an existing `.apns` file in `payloads/` whose shape matches.
|
|
2. Set `aps.mutable-content: 1` and a real `aps.alert.{title,body}`.
|
|
3. Match the payload shape to `NotificationPayload` in
|
|
`src/lib/hooks/useNotificationHandler.ts` for the `reason` you're testing.
|
|
4. Use `__RECIPIENT_DID__` as the placeholder for the recipient — `send.sh`
|
|
substitutes it at send time. Use it anywhere a DID needs to belong to the
|
|
logged-in user (typically `recipientDid`, and post `subject` for likes/replies).
|