Free resource · use it on this page
Push Implementation Workbook
A step-by-step runbook from credentials and SDK or pass integration to your first live send — fill it in once, then reuse it for every launch after.
How to use this workbook
This is a working runbook, not an article. Work top to bottom: fill in the launch header, complete Phase 1 and Phase 2, run the verification matrix, write the one-page send plan, then execute the launch-day checklist. Each phase ends with something you can verify, not a feeling that you are probably ready.
Keep this page open or print it. The fields are meant to be filled in for your first launch and then reused as the template for every send after — the second launch should take a fraction of the time because the answers already exist.
It covers app push (APNs and FCM), web push where noted, and wallet-pass channels. If a line does not apply to your stack, write n/a rather than leaving it blank, so a reviewer can see it was considered and skipped on purpose.
Launch header: fill this in before anything else
Ten minutes here prevents most launch-week arguments. One name per line — teams do not sign off, people do.
Launch owner
One named person who approves the first live send and owns the rollback decision. Not a team, not a channel.
Target first-send date
Pick a mid-week, mid-morning slot in your audience's timezone. Avoid Fridays, holidays, and the day of a big release.
Channels in scope
App push (APNs/FCM), web push, wallet pass, or a combination. Each channel adds its own credential work in Phase 1.
Platforms and minimum OS versions
For example iOS 15+ and Android 8+. Note that Android 13+ requires a runtime notification permission request.
Provider and account owner
The push tool you chose, plus who owns the account login and billing. Orphaned accounts are a common outage cause.
Environments
List dev, staging, and production app entries and which credentials each uses. Mixing sandbox and production APNs keys is the classic silent delivery failure.
Rollback procedure
The exact steps to pause or cancel a send, and who can execute them at any hour. Write commands or dashboard paths, not 'contact engineering'.
Success metric for send #1
One number you will check within 24 hours — for example tap-through on this message. Not app-wide DAU; the first send cannot move that.
Phase 1: credentials and integration
Everything in this phase happens before a single message is written. The exit test at the end is non-negotiable.
- 1
Create platform credentials
For APNs, generate a .p8 auth key in the Apple Developer portal and record the Key ID and Team ID. For FCM, create the Firebase project and export the service account JSON. Store both in a secrets manager, never in the repository.
- 2
Register the app with your provider
Upload the APNs key and FCM credentials into your push tool. Create separate app entries for staging and production so a test campaign can never reach real users.
- 3
Install and initialize the SDK
Pin an exact SDK version, initialize on app start, and confirm registration by finding your own test device in the provider dashboard. If your device is not listed, nothing downstream matters yet.
- 4
Design the permission prompt moment
Do not ask on first launch. Trigger the system prompt after an action where notifications obviously help — an order placed, an item saved. On Android 13+, request POST_NOTIFICATIONS at that same moment.
- 5
Set up wallet-pass credentials, if in scope
Apple Wallet requires a Pass Type ID certificate; Google Wallet requires an issuer account. Wallet passes reach the lock screen with no app install and no SDK — a hosted platform such as PushNotice handles the certificate and update plumbing if you do not want to run it yourself.
- 6
Run the Phase 1 exit test
Send a test notification from the provider dashboard to your own device on each platform, from each environment, and watch it arrive on a locked screen. Do not proceed until all combinations pass.
Phase 2: data, audience, and compliance
Check every line before writing your first campaign. Most first-send incidents trace back to something on this list.
External user IDs mapped to tokens
Every device token ties back to your internal user ID, so the unit of targeting is a person, not a device.
Timezone captured per user
Required for local-time delivery. Default missing values to your primary market — never fall back to server time.
Consent recorded with timestamp and source
OS permission state is not an audit trail. Log when and where each user opted in.
Opt-out honored end to end
Flip a test account to opted-out and confirm the provider actually suppresses delivery — not just your app's settings screen.
Quiet hours written down and enforced
A concrete rule, such as no sends 21:00 to 09:00 local time, configured in the tool rather than remembered by people.
Frequency cap decided before the first campaign
Set the maximum sends per user per week now, and configure it in the tool if it supports caps.
First segment defined, counted, and sanity-checked
Write the exact filter, run the count, and compare it to what you expected. A segment ten times too large is a configuration error, not good news.
Internal and test users on a suppression list
Staff and seed devices excluded from production sends so dogfood accounts never pollute campaign metrics.
Token hygiene job scheduled
Decide how uninstalls and invalid tokens get pruned. Stale tokens inflate audience counts and quietly deflate every rate you report.
Every deep link target exists and survives cold start
Each screen you plan to link to has a stable route that works when the app launches from a killed state.
Data deletion path confirmed
Verify what happens to tokens and profiles when a user deletes their account. Push tokens tied to a person are personal data under GDPR.
Wallet pass install flow tested, if in scope
Install the pass on one iPhone and one Android device, update a field, and confirm the change appears without opening any app.
Phase 3: cross-platform verification matrix
Run each scenario on a real device, not a simulator, and mark the result columns. Print this table and keep the filled copy with the launch record.
| Scenario | How to verify | iOS result | Android result | Notes |
|---|---|---|---|---|
| Delivery to a locked screen | Lock the test device, send a test push, watch it arrive without unlocking | |||
| Foreground receipt | Send while the app is open; confirm your in-app handling behaves as designed | |||
| Tap opens the deep link from cold start | Force-quit the app, tap the notification, confirm it lands on the intended screen | |||
| Opted-out user is suppressed | Include an opted-out test account in the audience; confirm zero delivery to it | |||
| Rich media renders correctly | Attach an image; check both the collapsed and expanded notification views | |||
| Wallet pass field update reaches the lock screen | Change a pass field; confirm the update appears with no app open | |||
| Invalid token handled cleanly | Uninstall the app on one device, send again, confirm the token fails and is pruned | |||
| Local-time delivery respected | Set a device to a different timezone; confirm a scheduled send honors it |
The one-page plan for send #1
Fill in every line before launch day. A field you cannot fill in yet is a task, not a blank.
Audience
Segment name and the exact count at the time of writing. Re-count two hours before sending.
Message
Final title and body, written out in full. Read it aloud as it will appear on a lock screen before anyone approves it.
Destination
The deep link path the tap opens, plus the fallback behavior if the app was uninstalled.
Send time
Date and time, and whether delivery is per-user local time or a single timezone. Name the timezone explicitly.
Success threshold
The number that makes this send a success, decided before sending — so the result cannot be reinterpreted afterward.
Guardrail and stop condition
What makes you pause: for example an opt-out spike or a jump in crash reports within the first hour. Name the threshold.
Approvals
Four separate checks — copy, link, audience, timing — each initialed by whoever verified it. One person may hold several, but each must be explicit.
Post-send review slot
A 15-minute calendar block within 24 hours to record actual vs target in this workbook. This record is your template for send #2.
Launch day: T-24 hours to T+24 hours
Execute in order. If any T-24h item fails, move the send date — the audience will not notice a two-day delay, but they will notice a broken link.
T-24h: dry-run the exact campaign to seed devices
Send the real campaign, not a copy, to the internal seed list only. Check rendering on locked screens on both platforms.
T-24h: verify the environment
Confirm the campaign lives in the production app entry with production credentials — not the staging entry it was drafted in.
T-24h: cold-start the deep link
Force-quit the app, tap the seeded notification, and confirm it lands on the planned screen.
T-2h: re-run the audience count
Compare against the number written in the plan. Investigate any meaningful swing before sending, not after.
T-2h: confirm suppression lists are active
Opted-out users and internal accounts excluded from the final audience.
T-1h: freeze the campaign
No copy, link, or audience edits inside the final hour. If something must change, move the send time instead.
T-0: send, and watch delivery live
Keep the provider's delivery dashboard and your crash or error monitoring open side by side for the first minutes.
T+15m: spot-check real devices
Seed devices should have received the message. If they have not, pause before assuming the rest of the fleet did.
T+1h: check the guardrail
Compare opt-out rate and error logs against the stop condition written in the plan. If breached, execute the rollback procedure from the launch header.
T+24h: record the result
Write actual vs target for the success metric into the plan above. Your filled workbook is now the repeatable runbook this page promised.
From the guide: Best Push Notification Tools (2026)
This resource accompanies the full article — worth reading before you commit to a tool.