sales-push-notification

What this skill does

# Mobile & Web Push Notifications

Help the user with push notification strategy — from opt-in optimization and message design through segmentation, timing, frequency capping, and analytics. This skill is tool-agnostic but includes platform-specific guidance for Braze, OneSignal, Airship, Firebase/FCM, Customer.io, Klaviyo, Iterable, and MoEngage.

## Step 1 — Gather context


If `references/learnings.md` exists, read it first for accumulated knowledge.

Ask the user:

1. **What do you need help with?**
   - A) Strategy — planning a push notification program from scratch
   - B) Opt-in optimization — increasing push permission acceptance rates
   - C) Message design — content, rich push, action buttons, deep links
   - D) Segmentation — targeting the right users for push
   - E) Timing & frequency — when and how often to send
   - F) A/B testing — testing push variants
   - G) Analytics — measuring push effectiveness
   - H) Tool selection — choosing a push notification platform
   - I) Technical setup — SDK integration, certificates, FCM keys
   - J) Something else — describe it

2. **What platforms do you target?**
   - A) iOS (iPhone/iPad)
   - B) Android
   - C) Web (browser push)
   - D) iOS + Android
   - E) All (iOS + Android + Web)

3. **What tool are you using (or considering)?**
   - A) Braze
   - B) OneSignal
   - C) Airship (Urban Airship)
   - D) Firebase Cloud Messaging (FCM) directly
   - E) Customer.io
   - F) Klaviyo
   - G) Iterable
   - H) MoEngage
   - I) Not decided yet
   - J) Other

**If the user's request already provides most of this context, skip directly to the relevant step.** Lead with your best-effort answer using reasonable assumptions (stated explicitly), then ask only the most critical 1-2 clarifying questions at the end.

## Step 2 — Strategy and approach

### When push notifications work best

Push is highest-value for:
- **Time-sensitive actions** — flash sales, expiring offers, appointment reminders
- **Transactional updates** — order shipped, delivery arriving, payment received
- **Re-engagement** — dormant users, abandoned cart, feature they haven't tried
- **Social triggers** — someone liked/commented/messaged them
- **Personalized content** — recommendations, score updates, content they follow

Push is lowest-value (and most likely to cause unsubscribes) for:
- Generic promotional blasts with no personalization
- Sending too frequently (more than 1-2 per day for most apps)
- Content that could wait for email or in-app

### Push opt-in strategy

iOS requires explicit user permission for push. Android auto-enables but users can disable. Web requires permission prompt.

**The push primer pattern (critical for iOS):**
1. Don't show the OS permission prompt immediately on first launch
2. First, show a custom in-app message explaining the value ("Get notified when your order ships")
3. If user taps "Enable" on your custom prompt → show the OS prompt
4. If user taps "Not now" → don't show OS prompt, try again later
5. This avoids permanent "denied" status from premature OS prompts

**Opt-in rate benchmarks:**
- With push primer: 50-70% opt-in
- Without primer (OS prompt on first launch): 30-40% opt-in
- Web push: 5-15% opt-in (browser prompts are lower than native)

### Message design principles

1. **Keep it short** — 40-50 characters for the title, 100-120 for the body (iOS truncates beyond this)
2. **Lead with value** — what does the user get? Not what you want them to do.
3. **Personalize** — use name, last action, product interest. Generic = ignored.
4. **Create urgency (sparingly)** — "Ends in 2 hours" works, but don't manufacture false urgency
5. **Rich push** — images, GIFs, and action buttons increase engagement 20-40%
6. **Deep link** — always deep link to the relevant screen, never just open the app home

### Frequency and timing

**Frequency guidelines:**
- **Transactional**: No limit — users expect these (order updates, etc.)
- **Promotional**: 2-5 per week for engaged users, 1-2 per week for casual users
- **Maximum**: More than 1-2 per day drives unsubscribes for most app categories
- **Use frequency capping**: Most tools let you cap per user per day/week

**Timing optimization:**
- **Intelligent timing** (Braze, Iterable, OneSignal): ML-based per-user optimal send time
- **Manual defaults**: 10am-1pm and 6-9pm local time for most consumer apps. Avoid late night (10pm-7am).
- **Quiet hours**: Always respect quiet hours — never wake users up

## Step 3 — Platform-specific guidance

**Read `references/platform-guide.md`** for detailed platform comparisons, implementation checklist, and key metrics.

*You no longer need the platform guide details — focus on the user's specific situation.*

## Step 4 — Actionable guidance

Based on the user's specific question, provide targeted recommendations drawing on the strategy framework in Step 2 and platform details in the reference guide.

## Gotchas

1. **iOS push permission is permanent** — if a user denies the OS prompt, you can never ask again (they must go to Settings to re-enable). This is why push primers are critical. Never show the OS prompt without a primer first.
2. **Android 13+ requires opt-in** — Android 13 (API 33) introduced runtime push permission, similar to iOS. Don't assume all Android users have push enabled by default.
3. **Push tokens expire** — if a user doesn't open your app for months, their push token may become invalid. Monitor delivery rates and clean stale tokens. Don't count push-enabled users who haven't opened the app in 90+ days.
4. **Web push has low opt-in** — browser push permission prompts are aggressively blocked by users (5-15% opt-in). Don't rely on web push as a primary channel. Use it as a supplement to email.
5. **Rich push requires separate assets** — iOS and Android handle rich push differently (different image sizes, aspect ratios, and action button limits). Test rich push on both platforms before launching.

- **Self-improving**: If you discover something not covered here, append it to `references/learnings.md` with today's date.

## Before recommending a specific platform skill

This skill covers a strategy domain across many platforms. **Before pointing the user to any specific platform skill** (any `/sales-{platform}` listed in `## Related skills`, e.g., `/sales-mailshake`, `/sales-klaviyo`, `/sales-apollo`), read that platform skill's actual `SKILL.md` first. The 1-line description in `## Related skills` is enough to *identify* a candidate — it's not enough to *commit* to it or to write a prompt that invokes it well.

**How to read it:**
- If `~/.claude/skills/{skill-name}/SKILL.md` exists locally, `Read` it.
- For `sales-*` skills, `WebFetch` directly from this repo: `https://raw.githubusercontent.com/sales-skills/sales/main/skills/{skill-name}/SKILL.md` — e.g., for `sales-mailshake`: `https://raw.githubusercontent.com/sales-skills/sales/main/skills/sales-mailshake/SKILL.md`.
- For non-`sales-*` skills (third-party), look up `{org}/{repo}` in `~/.claude/skills/sales-do/references/skill-sources.md` if installed and fetch the same `skills/{skill-name}/SKILL.md` path under that repo.

**After reading,** ground your recommendation in something concrete from the SKILL.md (its scope, a sub-flow, its `argument-hint` shape, or a "Do NOT use for..." negative trigger). Align any generated invocation with the platform skill's `argument-hint`. If the platform skill turns out not to fit the user's situation, swap to another or handle the question here directly rather than recommending a poor fit.

## Related skills

- `/sales-iterable` — Iterable platform help (push setup, Studio journeys, Brand Affinity, STO)
- `/sales-braze` — Braze platform help (push setup, Canvas integration, BrazeAI timing)
- `/sales-customerio` — Customer.io platform help (push in Journeys)
- `/sales-klaviyo` — Klaviyo platform help (push for Shopify e-commerce)
- `/sales-omnisend` — Omnisend platform help (web push + email + SMS for ecommerce)
- `/