Push Notification

Notification Delivery Pipeline:

1. Device Registration
   App Launch → Request Permission → Register with OS → Receive Token
   → Send Token to Your Server → Store Token + User Association

2. Sending a Notification
   Business Event → Your Server → Provider (APNs / FCM) → OS → Device
   → Foreground: App handles display
   → Background: System displays notification
   → Not Running: System displays, app launched on tap

3. User Interaction
   Notification Displayed → User Taps → App Opens → Deep Link Route
   → Analytics: Delivery confirmed, Tap tracked, Conversion measured

Recommended Server Architecture:

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Business    │────▶│ Notification │────▶│  Provider    │
│  Logic       │     │  Service     │     │  Gateway     │
│  (triggers)  │     │  (queue +    │     │  (APNs/FCM)  │
└─────────────┘     │  templates)  │     └─────────────┘
                     └──────────────┘            │
                           │                     ▼
                     ┌──────────────┐     ┌─────────────┐
                     │  Token Store │     │  Device      │
                     # ... (condensed) ...
- Queue: RabbitMQ/SQS for reliable, ordered delivery
- Template Engine: Handlebars/Mustache for notification content
- Provider Gateway: Abstraction over APNs + FCM APIs
- Analytics Sink: Track delivery, opens, conversions

# Python example using httpx for APNs HTTP/2
import httpx
import jwt
import time

class APNsClient:
    def __init__(self, key_id: str, team_id: str, private_key: str, sandbox: bool = False):
        self.key_id = key_id
        self.team_id = team_id
        self.private_key = private_key
        self.base_url = (
            # ... (condensed) ...
                headers=headers,
                json=payload,
            )
            return response.status_code, response.json() if response.status_code != 200 else None

{
  "aps": {
    "alert": {
      "title": "New Message",
      "subtitle": "From John",
      "body": "Hey, are you free for lunch today?"
    },
    "badge": 3,
    "sound": "default",
    "category": "MESSAGE_CATEGORY",
    "thread-id": "conversation-123",
    # ... (condensed) ...
  "conversation_id": "123",
  "sender_id": "user-456",
  "deep_link": "myapp://chat/123"
}

import google.auth.transport.requests
from google.oauth2 import service_account
import httpx

class FCMClient:
    def __init__(self, service_account_file: str, project_id: str):
        self.project_id = project_id
        self.credentials = service_account.Credentials.from_service_account_file(
            service_account_file,
            scopes=["[reference URL]"]
        )
# ... (condensed) ...
        }
        async with httpx.AsyncClient() as client:
            response = await client.post(url, headers=headers, json={"message": message})
            return response.json()

{
  "message": {
    "token": "device_token_here",
    "notification": {
      "title": "New Order",
      "body": "Your order #1234 has been shipped!"
    },
    "android": {
      "priority": "high",
      "notification": {
        "channel_id": "orders",
        # ... (condensed) ...
      "type": "order_shipped"
    }
  }
}

// Define channels at app startup
class NotificationChannelManager(private val context: Context) {

    fun createChannels() {
        val manager = context.getSystemService(NotificationManager::class.java)

        val channels = listOf(
            NotificationChannel(
                "messages", "Messages",
                NotificationManager.IMPORTANCE_HIGH
            ).apply {
                # ... (condensed) ...

        manager.createNotificationChannels(channels)
    }
}

// NotificationServiceExtension/NotificationService.swift
class NotificationService: UNNotificationServiceExtension {
    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    supersede func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        self.contentHandler = contentHandler
        bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent
# ... (condensed) ...
            completion(tmpURL)
        }.resume()
    }
}

// Big picture notification
fun showImageNotification(context: Context, title: String, body: String, bitmap: Bitmap) {
    val notification = NotificationCompat.Builder(context, "orders")
        .setSmallIcon(R.drawable.ic_notification)
        .setContentTitle(title)
        .setContentText(body)
        .setStyle(
            NotificationCompat.BigPictureStyle()
                .bigPicture(bitmap)
                .bigLargeIcon(null as Bitmap?) // Hide large icon when expanded
        )
        # ... (condensed) ...
        .build()

    NotificationManagerCompat.from(context).notify(conversationId, notification)
}

Silent Notification Use Cases:
├── Background data sync
├── Cache invalidation
├── Configuration updates
├── Location tracking updates
├── Badge count updates
├── Content pre-fetching
└── Token refresh triggers

Implementation Rules:
├── iOS: content-available: 1, no alert/sound/badge
# ... (condensed) ...
│   ├── Handled by FirebaseMessagingService
│   ├── App gets ~20 seconds in onMessageReceived
│   ├── High priority: wakes dozing device
│   └── Normal priority: may be deferred by Doze mode

// iOS silent notification handling
func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
    guard let type = userInfo["type"] as? String else {
        completionHandler(.noData)
        return
    }

    # ... (condensed) ...
    default:
        completionHandler(.noData)
    }
}

Notification Grouping Rules:
├── Group by conversation (messaging apps)
│   └── thread-id (iOS) / group key (Android) = conversation ID
├── Group by category (e-commerce)
│   └── Orders, promotions, and account grouped separately
├── Group by sender (email/social)
│   └── All notifications from same person/account
├── Summary notification
│   ├── iOS: automatic summary with category
│   └── Android: setGroup() + summary notification with setGroupSummary(true)
└── Maximum visible: Show up to 4 individual, then collapse to summary

// Android notification grouping
private val GROUP_KEY = "com.myapp.ORDERS"

fun showOrderNotification(order: Order) {
    // Individual notification
    val notification = NotificationCompat.Builder(context, "orders")
        .setSmallIcon(R.drawable.ic_order)
        .setContentTitle("Order ${order.id}")
        .setContentText(order.statusMessage)
        .setGroup(GROUP_KEY)
        .build()
# ... (condensed) ...
    val manager = NotificationManagerCompat.from(context)
    manager.notify(order.id.hashCode(), notification)
    manager.notify(0, summary) // Summary ID should be constant
}

Deep Link Flow:
Notification Tap → OS Opens App → App Reads Notification Data
→ Parse deep_link field → Route to correct screen

Deep Link Formats:
├── Custom scheme: myapp://orders/1234
├── Universal Links (iOS): [reference URL]
├── App Links (Android): [reference URL]
└── Deferred deep links: Store link + route after install

Implementation Checklist:
├── Parse deep link in notification tap handler
├── Handle cold start (app not running) deep links
├── Handle warm start (app in background) deep links
├── Handle foreground notification tap deep links
├── Queue deep link if auth required, execute after login
└── Track deep link attribution in analytics

Optimal Send Time Strategy:
├── Per-user timezone delivery
│   └── Send at 10 AM local time, not 10 AM server time
├── Per-user engagement window
│   ├── Track when each user opens the app
│   ├── Track when each user opens notifications
│   └── Send during their peak engagement window
├── Frequency capping
│   ├── Maximum 1 promotional notification per day
│   ├── Maximum 3 transactional notifications per hour
│   └── Maximum 5 total notifications per day (unless real-time messaging)
# ... (condensed) ...
└── Quiet hours
    ├── Default: No notifications 10 PM - 8 AM local time
    ├── Exception: Time-sensitive and transactional
    └── Let users configure their quiet hours

Opt-In Strategy (maximize permission grant rate):

1. Pre-permission screen (before iOS system prompt)
   ├── Explain VALUE the user gets from notifications
   ├── Show example notifications visually
   ├── Use specific benefit: "Get notified when your order ships"
   ├── NOT generic: "We'd like to send you notifications"
   └── If user says "Not now" → Ask again after value delivery

2. Contextual permission request (at the right moment)
   ├── After placing first order → "Want delivery updates?"
   # ... (condensed) ...
   ├── Check notification permission status regularly
   ├── Show in-app banner: "Turn on notifications for [benefit]"
   ├── Provide deep link to Settings app
   └── Do NOT nag repeatedly

# Server-side notification analytics tracking
class NotificationAnalytics:
    def track_sent(self, notification_id: str, user_id: str, channel: str):
        self.emit("notification.sent", {
            "notification_id": notification_id,
            "user_id": user_id,
            "channel": channel,  # "push", "email", "sms"
            "timestamp": utcnow(),
        })

    def track_delivered(self, notification_id: str, user_id: str):
        # ... (condensed) ...
            "notification_id": notification_id,
            "user_id": user_id,
            "action": action,  # "purchase", "signup", "view"
        })