Push notification strategies

ed user trust.

Core Solution

Architecture Decisions

A robust push notification system requires an event-driven architecture decoupled from the main application thread. Key decisions include:

1. Provider Abstraction: Abstract FCM and APNs behind a unified interface to allow routing based on device type, payload size, and priority. This enables fallback strategies if a provider experiences an outage.
2. Token Management Service: A dedicated service to handle token registration, rotation, and revocation. This service must process feedback from providers (e.g., FCM error responses) to update the database immediately.
3. Idempotent Delivery: Implement idempotency keys for all push requests. This prevents duplicate notifications during retry scenarios and allows safe replay of messages.
4. Payload Validation: Enforce strict schema validation before serialization. APNs and FCM reject malformed payloads, and late validation wastes API calls.

Step-by-Step Implementation

1. Token Registration and Lifecycle

Tokens must be treated as ephemeral credentials. The client should register tokens on app launch and listen for rotation events.

// Client-side token handler (React Native / Expo example)
import * as Notifications from 'expo-notifications';

export async function registerPushToken() {
  const { status: existingStatus } = await Notifications.getPermissionsAsync();
  let finalStatus = existingStatus;

  if (existingStatus !== 'granted') {
    const { status } = await Notifications.requestPermissionsAsync();
    finalStatus = status;
  }

  if (finalStatus !== 'granted') {
    throw new Error('Push notification permissions not granted');
  }

  const token = (await Notifications.getDevicePushTokenAsync()).data;
  
  // Send token to backend with metadata
  await api.post('/devices/register', {
    token,
    platform: Platform.OS,
    appVersion: Constants.expoConfig?.version,
    timestamp: Date.now()
  });
}

2. Backend Orchestrator

The backend orchestrator validates payloads, resolves tokens, and routes to the appropriate provider.

// PushOrchestrator.ts
import { FCMProvider } from './providers/FCMProvider';
import { APNsProvider } from './providers/APNsProvider';
import { TokenRepository } from './repositories/TokenRepository';
import { PushPayload, DeliveryPriority } from './types';

export class PushOrchestrator {
  constructor(
    private fcm: FCMProvider,
    private apns: APNsProvider,
    private tokenRepo: TokenRepository
  ) {}

  async send(payload: PushPayload): Promise<DeliveryResult> {
    // 1. Validate payload schema
    this.validatePayload(payload);

    // 2. Resolve tokens (handle stale tokens)
    const tokens = await this.tokenRepo.getActiveTokens(payload.targetAudience);
    
    if (tokens.length === 0) {
      return { success: false, reason: 'No active tokens found' };
    }

    // 3. Route and Send with Idempotency
    const results = await Promise.allSettled(
      tokens.map(async (token) => {
        const provider = token.platform === 'ios' ? this.apns : this.fcm;
        return provider.send({
          ...payload,
          token: token.value,
          idempotencyKey: this.generateIdempotencyKey(payload, token.value)
        });
      })
    );

    // 4. Process failures and update token state
    await this.handleDeliveryFeedback(results);

    return { success: true, delivered: results.filter(r => r.status === 'fulfilled').length };
  }

  private validatePayload(payload: PushPayload) {
    const jsonSize = JSON.stringify(payload).length;
    if (jsonSize > 4096) {
      throw new Error('Payload exceeds 4KB limit');
    }
    // Additional schema checks...
  }

  private async handleDeliveryFeedback(results: PromiseSettledResult<DeliveryResponse>[]) {
    const invalidTokens = results
      .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
      .map(r => r.reason.token)
      .filter(Boolean);

    if (invalidTokens.length > 0) {
      await this.tokenRepo.markAsStale(invalidTokens);
    }
  }
}

3. FCM v1 and APNs HTTP/2 Integration

Modern implementations must use FCM v1 API (OAuth2) and APNs HTTP/2. Legacy protocols are deprecated and lack support for modern features like message grouping and priority controls.

// APNsProvider.ts
import { APNs } from '@parse/node-apn';

export class APNsProvider {
  private connection: APNs.Provider;

  constructor(config: APNs.Config) {
    this.connection = new APNs.Provider(config);
  }

  async send(payload: PushPayload): Promise<DeliveryResponse> {
    const note = new APNs.Notification();
    note.alert = { title: payload.title, body: payload.body };
    note.topic = config.bundleId;
    note.priority = payload.priority === DeliveryPriority.HIGH ? 10 : 5;
    note.payload = { data: payload.customData };
    
    // Use mutable-content for rich notifications
    note.mutableContent = 1;

    const result = await this.connection.send(note, payload.token);
    
    if (result.failed && result.failed.length > 0) {
      throw { token: result.failed[0].device, error: result.failed[0].status };
    }
    
    return { success: true };
  }
}

Architecture Rationale

• Promise.allSettled: Ensures that a failure for one token does not abort the batch. This is critical for scalability.
• Provider Abstraction: Allows swapping providers or implementing a "best-effort" fallback without changing business logic.
• Idempotency: Prevents duplicate notifications caused by network retries or client re-subscriptions.
• Token Cleanup: Immediate processing of NOT_FOUND errors prevents sending to invalid endpoints, maintaining sender reputation.

Pitfall Guide

1. Ignoring Token Rotation

Mistake: Storing tokens permanently without checking validity. Impact: Delivery rates decay over time. Providers may throttle your IP or project if error rates exceed thresholds. Best Practice: Implement a cron job to process provider feedback and a real-time handler for error responses during sends. Remove tokens immediately upon NOT_FOUND or InvalidRegistration errors.

2. Blocking the Main Thread

Mistake: Performing heavy parsing or network requests in the notification receiver callback. Impact: App crashes, ANRs (Android), or watchdog terminations (iOS). Background execution time is severely limited. Best Practice: Keep the receiver callback minimal. Offload processing to a background task or service worker. Use content-available (iOS) or data messages (Android) for silent updates and defer heavy work.

3. Payload Size Violations

Mistake: Sending large JSON objects or embedded images in the payload. Impact: FCM and APNs reject messages >4KB. Images must be downloaded via URL, not embedded. Best Practice: Enforce strict payload size limits in the orchestrator. Use mutable-content extensions (iOS) to download assets asynchronously before displaying the notification.

4. Misusing Silent Pushes

Mistake: Relying on silent pushes for critical data synchronization. Impact: iOS aggressively throttles background fetches. Silent pushes are not guaranteed to arrive or execute. Best Practice: Use silent pushes only for prefetching or non-critical updates. For critical data, use standard notifications with deep links or implement a persistent socket connection for real-time sync.

5. Timezone Agnosticism

Mistake: Sending marketing blasts based on server time or UTC without considering user locale. Impact: Notifications arrive at 3 AM, causing immediate opt-outs and poor user experience. Best Practice: Store user timezone metadata. Use a scheduler that respects "quiet hours" configured by the user or inferred from activity patterns.

6. Deep Link Mismatch

Mistake: Payload contains a deep link that the app cannot resolve or crashes on cold start. Impact: User clicks notification, app opens to home screen or crashes. Trust is eroded. Best Practice: Implement a robust deep link router that handles missing parameters gracefully. Validate deep links against a schema before sending. Test cold-start scenarios rigorously.

7. Security Leaks

Mistake: Exposing server keys in client code or failing to validate sender identity. Impact: Malicious actors can send spam notifications impersonating your app. Best Practice: Never embed server keys in the client. Use the provider SDKs for token generation on the client. Validate all incoming requests to the push endpoint using authentication tokens and rate limiting.

Production Bundle

Action Checklist

• Implement Token Lifecycle Handler: Create a service to process FCM NOT_FOUND and APNs feedback responses and revoke stale tokens immediately.
• Enforce Payload Validation: Add middleware to validate payload size (<4KB) and schema before provider routing.
• Configure Idempotency: Generate unique idempotency keys for every push request to prevent duplicates during retries.
• Set Up Quiet Hours: Implement a scheduler that respects user timezone and configured quiet hours for non-transactional messages.
• Add Rich Media Support: Implement mutable-content (iOS) and notification channels (Android) to support images and actions without blocking the main thread.
• Establish Telemetry: Track delivery success rates, latency, and opt-out rates per campaign to feed the adaptive throttling engine.
• Test Cold Start Deep Links: Verify that notifications open the correct screen when the app is not running, handling missing state gracefully.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Transactional Alert (e.g., OTP)	High Priority Push (APNs priority: 10, FCM high)	Immediate delivery required; bypasses Doze/low-power modes.	Higher battery impact; minimal infra cost.
Marketing Campaign	Adaptive Batch with Throttling	Reduces opt-outs by respecting user engagement patterns; batches non-urgent messages.	Higher infra complexity; lower churn cost.
Background Sync	Silent Push (Data-only)	Updates app state without user interruption; relies on OS scheduling.	Low user impact; risk of delivery delay.
Rich Media Update	Silent Push + Content Download	Avoids 4KB payload limit; allows high-res assets; uses mutable-content.	Increased bandwidth; requires asset CDN.
Cross-Platform Fallback	In-App Message if Push Fails	Ensures delivery when push is opted-out; maintains message continuity.	Low infra cost; requires in-app messaging SDK.

Configuration Template

{
  "push": {
    "providers": {
      "fcm": {
        "projectId": "your-project-id",
        "keyFilePath": "./secrets/fcm-key.json",
        "retryPolicy": {
          "maxAttempts": 3,
          "backoff": "exponential",
          "initialDelayMs": 1000
        }
      },
      "apns": {
        "teamId": "YOUR_TEAM_ID",
        "bundleId": "com.your.app",
        "keyId": "YOUR_KEY_ID",
        "keyPath": "./secrets/apns-key.p8",
        "production": false
      }
    },
    "limits": {
      "maxPayloadBytes": 4096,
      "batchSize": 500,
      "rateLimit": {
        "requestsPerSecond": 100,
        "burstSize": 200
      }
    },
    "telemetry": {
      "enabled": true,
      "metricsEndpoint": "/metrics/push",
      "sampleRate": 1.0
    }
  }
}

Quick Start Guide

1. Initialize Providers: Configure FCM v1 and APNs HTTP/2 credentials in your backend environment. Ensure keys are stored securely and not committed to version control.
2. Register Token Endpoint: Implement a /devices/register endpoint that accepts the device token, platform, and metadata. Store this in your database with a last_active timestamp.
3. Deploy Orchestrator: Integrate the PushOrchestrator class into your notification service. Ensure it validates payloads and handles token resolution before calling providers.
4. Send Test Payload: Trigger a test notification with a unique idempotency key. Verify delivery on both iOS and Android devices. Check logs for any validation errors or provider rejections.
5. Verify Feedback Loop: Force a token revocation on the client (e.g., uninstall/reinstall) and trigger a send. Confirm that the backend detects the error and marks the token as stale in the database.