Defines cross-platform push behavior for permission timing, token lifecycle, minimal payloads, foreground/background handling, deep links, collapse, expiry, and truthful delivery status.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Ask platform permission only after an in-product explanation tied to a user-valued action. Treat device tokens as rotating installation-scoped addresses, send minimal non-authoritative payloads, and resolve current content and authorization when the app opens.
Scope
- Permission prompt, settings state, installation/token registration, rotation, topics, payload, foreground/background/tap behavior, deep links, collapse, expiry, logout, and metrics.
- Apple and Android push notifications plus desktop where equivalent APIs exist.
- Platform-adapted behavior under one product intent.
Outside this block
- Guaranteeing delivery or using push as the durable system of record.
- Silent/background push as an unlimited scheduler.
Contract
- The app reads platform authorization state and distinguishes not-determined, allowed variants, denied, and system-managed states.
- The native prompt follows a contextual explanation; a denial is respected and recovery points to system settings without repeated coercion.
- A registration binds token, installation, platform, app/environment, account/tenant scope, token generation, and last confirmation.
- Sensitive or mutable content is fetched after tap; payloads contain opaque IDs and the minimum safe preview.
- Deep links validate route and current authorization and provide a safe fallback when the object disappeared.
- Collapse key, priority, expiry, badge, sound, and foreground presentation are explicit per notification class.
Implementation guidance
- Upsert token registrations idempotently and replace old generations atomically on rotation.
- Remove or disable account bindings on logout and provider-invalid-token response.
- Use one logical notification ID across channels for duplicate handling.
- Test actual platform states and app lifecycle, including force stop, reinstall, multiple accounts, and offline tap.
Failure handling and safeguards
- If permission is denied, keep the feature usable with in-app history where appropriate.
- If token ownership is ambiguous after account switch, suppress sending until rebound.
- If a deep-linked resource is unauthorized or deleted, show a safe landing page without revealing it existed.
Verification and operations
- Measure explanation-to-prompt, platform permission outcome, token freshness, provider acceptance, invalid token, tap, deep-link success, duplicate display, and notification class latency.
- Segment by OS/app version while respecting analytics policy.
- Review platform requirements whenever target OS versions or notification APIs change.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.