push_notification_strategy v1.0.0

name: push_notification_strategy description: "Push notification strategy for apps and websites: earn permission with a soft ask at a contextual moment instead of a first-launch prompt, split sends into transactional, lifecycle, promotional, and winback classes with separate rules, enforce a global rolling 7-day frequency cap, write copy that survives the lock screen, validate deep links, and test send times and frequency against opt-outs and a holdout. Ships a rolling cap calculator, a lock-screen copy checker, and a test sample-size calculator, plus worked campaigns. Use when planning or auditing a push program, fixing low opt-in or high opt-out rates, setting frequency caps, writing push copy, or testing send times."

Push Notification Strategy

Purpose

Run push as a permission you borrow, not a channel you own. Every send spends a little of that permission. This skill covers how to earn it, how to ration it with caps that hold across teams, how to write copy that still works in the smallest visible preview, and how to tell whether sends are causing action or only causing taps.

Scope boundary: SMS programs belong to the SMS marketing skill. Email programs belong to the email newsletter skill. Retention planning across all channels belongs to the retention marketing skill. This skill covers push only: mobile app push through APNs and FCM, and web push.

Workflow

1. Classify every send before anything else. Use four classes: transactional (per event, exempt from caps, never carries an offer), lifecycle (triggered by what the person did, capped), promotional (scheduled, capped hardest), and winback (dormant accounts only, capped hardest, with a stop rule). One pipeline for all four is the root cause of most opt-out spikes. Detail in references/caps-and-segments.md.
2. Earn permission at a contextual moment. Show your own soft ask first, naming the exact messages on offer, with a clear not now option. Only a yes on your screen triggers the system prompt. On iOS that prompt shows once and a decline can only be reversed in Settings. On Android 13 and later the POST_NOTIFICATIONS runtime permission is required, and apps targeting API 33 or higher choose when to ask. On the web a blocked origin is hard to restore, and web push on iPhone needs a Home Screen web app on iOS 16.4 or later. Timing table and channel rules are in references/permission-and-channels.md.
3. Split types into channels and preferences from day one. On Android 8.0 and later every notification sits in a channel, people can silence one channel without killing the rest, and the app cannot change a submitted channel's importance later. Mirror that type split in the preference centre on every platform. A type the person turned off stays off.
4. Set one global rolling cap, plus per-class caps. Rolling means the prior 168 hours, not a calendar week. Transactional sends sit outside the cap. Run python3 scripts/cap_calc.py <plan.json> on the week's plan per segment: it prints KEEP or DEFER per send with the blocking cap, a quiet-hours release suggestion, and the cap that would be needed to keep everything. That last number settles arguments about which sends die. Worked example: assets/plan-crowded-week.json.
5. Hold quiet hours in the recipient's local time. Non-transactional sends that land in quiet hours move to the end of the window. Decide in writing which transactional types follow the event at any hour (security alerts) and which can wait until morning (a parcel update). Test send times across daylight saving changes.
6. Write copy to the collapsed preview, then check it. Put the point in the first line of the body, one job per send, a number or a recognised name instead of an adjective, and a fallback after every personalization token. Run python3 scripts/copy_check.py --file <copy.json> on every campaign. Safe universal targets: title at or under 38 characters, body at or under 120, action label at or under 15. The hard limit is the 4096 byte payload on both APNs and FCM, counted over the whole JSON. Display rules and payload notes are in references/copy-and-deep-links.md.
7. Treat the deep link as part of the send. Prefer an https Universal Link or App Link with a working web fallback over a custom scheme. Validate the target id, route after auth and data are ready, land on a safe parent screen when the target is gone, and test the exact link on a real device from a cold start, logged in and logged out, before sending.
8. Match delivery settings to how long the message stays true. Set a TTL instead of accepting the FCM default of four weeks. Use a collapse key or APNs collapse id for updates that replace each other, such as scores or stock levels, so a device that was offline does not wake up to a stack of stale alerts.
9. Test with a holdout and read opt-outs as the guardrail. A variant test picks the better message. A random holdout that gets nothing is the only way to know whether sending beat silence. Size send-time and copy tests before they run with python3 scripts/test_size.py --baseline <rate> --mde <lift worth acting on>, run the full planned duration, and read results per platform. Definitions, holdout discipline, and failure reads are in references/testing-and-metrics.md.

Output Contract

• A send inventory: every planned send with its class, trigger or schedule, segment, channel, and owner. No send ships without a class.
• A permission plan: the soft ask copy, the contextual moment that triggers it, the decline path, and the recovery path inside the feature, per platform.
• A cap sheet: the global rolling 7-day cap, per-class caps, quiet hours, and the priority order, plus the calculator output for the coming week's plan showing kept and deferred sends.
• Checked copy for each campaign: title, body, action label, and deep link, with the copy checker verdict and the collapsed preview it printed.
• A measurement record per campaign: sent, delivered, taps, conversions with the window stated, opt-outs with the window stated, and the holdout comparison where one ran.
• A test plan for any send-time or frequency change: baseline, smallest lift worth acting on, per-arm size from the calculator, duration, primary metric, and the opt-out guardrail that would veto a winning variant.

Operating Rules

1. Never fire the system permission prompt on first launch, on page load, or on a timer. The prompt follows a yes on your own soft ask, at a moment where the benefit names itself.
2. Never attach a promotion to a transactional send. The moment an order update carries an offer, people stop trusting order updates, and the class that earns permission for everything else is spent.
3. One global cap, enforced at send time across all campaigns and teams. Per-campaign caps alone fail silently, because each campaign can comply while the person gets buried.
4. Respect a silenced channel, an off preference, and a revoked permission as final for that type. Do not route around them with a new channel, a different class label, or a second identity.
5. Suppress before segmenting. People with an unresolved delivery problem, an open complaint, or a payment dispute come out of promotional and winback sends at send time, not at list build time.
6. Report opens and opt-outs side by side, with windows stated. A win on opens paired with a rise in opt-outs is a loss, because opt-outs delete the audience for every later send.
7. Do not quote benchmark open or opt-out rates from vendor blogs as targets. Rates differ by class, segment, and platform reporting. Set targets from your own first campaigns and move them on your own evidence.
8. Test the tooling on the shipped examples before trusting it live. Verified in this skill: the cap calculator on assets/plan-crowded-week.json reports sends=8 kept=5 deferred=3 with a needed cap of 7, the copy checker passes assets/copy-good.json on every line and warns on assets/copy-bad.json for title, body, action label, filler opening, and custom scheme link, and the size calculator at baseline 0.08 with a 0.01 lift reports 12,208 per arm. If your runs do not match, fix the inputs or the scripts before using them on a real plan.