push-notification-best-practices（推送通知最佳实践）

Push Notification Best Practices

Overview

Comprehensive guide for implementing and troubleshooting push notifications in mobile applications. Covers iOS (APNS), Android (FCM), React Native, Expo, and Flutter platforms with platform-specific configurations, token management, message handling, and deep linking patterns.

Platform Support Matrix

Decision Trees

Permission Request Timing

When to request notification permission?

User installing app
        |
        v
  [First launch?] ──Yes──> [Show value proposition first]
        |                          |
        No                         v
        |                  [User action triggers need?]
        v                          |
  [Already granted?]              Yes
        |                          |
       Yes                         v
        |                  [Request permission] ──> 70-80% acceptance rate
        v
  [Notifications ready]

Recommendation: Request after explaining value or when user enables a related feature.

Silent vs Visible Notification

Which payload type should I use?

[What's the purpose?]
        |
        +──> Time-sensitive user alert ──> Visible (notification payload)
        |
        +──> Background data sync ──> Silent (data-only payload)
        |
        +──> Custom UI required ──> Silent (data-only payload)
        |
        +──> Need background processing ──> Silent (data-only payload)

Extension Strategy (iOS)

When to use Notification Service Extension?

• Need to modify notification content before display
• Need to download and attach media (images, videos)
• Need to decrypt end-to-end encrypted payloads
• Need to add action buttons dynamically

When to use Notification Content Extension?

• Need custom notification UI beyond system template
• Need interactive elements in expanded view

Anti-patterns (NEVER Do)

Permission Handling

Token Management

Message Handling

iOS Specific

Android Specific

Skill Format

Each rule file follows a hybrid format for fast lookup and deep understanding:

• Quick Pattern: Incorrect/Correct code snippets for immediate pattern matching
• When to Apply: Situations where this rule is relevant
• Deep Dive: Full context with step-by-step guides and platform-specific details
• Common Pitfalls: Common mistakes and how to avoid them
• Related Rules: Cross-references to related patterns

Impact ratings: CRITICAL (fix immediately), HIGH (significant improvement), MEDIUM (worthwhile optimization)

When to Apply

Reference these guidelines when:

• Setting up push notifications in a mobile app
• Debugging push notification delivery issues
• Implementing background notification handlers
• Integrating deep linking with push notifications
• Managing push tokens and device registration
• Troubleshooting platform-specific push issues
• Reviewing push notification code for reliability

Priority-Ordered Guidelines

Quick Reference

Critical: iOS Setup

Setup checklist:

• Generate APNs authentication key (.p8) from Apple Developer
• Upload to Firebase Console with Key ID and Team ID
• Enable Push Notifications capability in Xcode
• Set UNUserNotificationCenter delegate in didFinishLaunchingWithOptions
• Request notification authorization before registering
• Implement foreground presentation options

Critical: Android Setup

Setup checklist:

• Add google-services.json to app/ directory
• Apply google-services Gradle plugin
• Create NotificationChannel (Android 8.0+)
• Request POST_NOTIFICATIONS permission (Android 13+)
• Implement FirebaseMessagingService
• Set notification icon (transparent background + white)
• Use priority 'high' for Doze mode compatibility

High: Token Management

Token lifecycle:

// 1. Register token with server
const token = await getToken();
await registerToken(token, userId);

// 2. Handle token refresh
onTokenRefresh((newToken) => {
  updateTokenOnServer(newToken, userId);
});

// 3. Handle invalidation
if (error.code === 'DeviceNotRegistered') {
  deleteTokenFromDatabase(token);
}

High: Message Handling

Payload types:

• data-only: Background handler runs on both platforms
• notification + data: iOS/Android behavior differs

- iOS: Always shows notification - Android: Background = system tray, Foreground = onMessageReceived

Priority settings:

• Use priority: 'high' for time-sensitive notifications
• Required for Android Doze mode background handlers

Rules

Full documentation with code examples in rules/:

iOS Setup (ios-*)

Android Setup (android-*)

Token Management (token-*)

Message Handling (message-*)

Deep Linking (deeplink-*)

Infrastructure (infra-*)

Best Practices

Searching Rules

# Find rules by keyword
grep -l "apns" rules/
grep -l "fcm" rules/
grep -l "token" rules/
grep -l "background" rules/
grep -l "permission" rules/
grep -l "deeplink" rules/

Problem → Rule Mapping

Platform-Specific Notes

iOS (APNS)

• Requires Apple Developer account and APNs authentication key (.p8)
• Different behavior for Development vs Production builds
• Delegate must be set before other SDK initialization
• Method Swizzling can interfere with delegate calls

Android (FCM)

• Requires google-services.json from Firebase Console
• NotificationChannel required for Android 8.0+
• Runtime permission required for Android 13+
• Doze mode requires priority: 'high' for background handlers
• Notification icons must be monochrome (white on transparent)

React Native

• Common issue: gcm.message_id required for foreground notifications
• Deep linking conflicts with React Navigation
• Terminated state requires native → JS bridge pattern

Expo

• ExpoPushToken format: ExponentPushToken[...]
• Rate limit: 600 push notifications per second per project
• Development builds required for SDK 53+
• Use eas credentials for APNs key management

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Attribution

Based on push notification troubleshooting guides and Firebase Cloud Messaging official documentation.