Push Notifications Done Right: Tokens, Topics, and UX

Quickstart

If you want immediate improvements (today), start here. These steps work whether you’re using Firebase Cloud Messaging (FCM), APNs directly, or a provider—because they focus on fundamentals: permission timing, segmentation, and a traceable send pipeline.

Overview

“Push notifications done right” is a blend of product decisions and engineering hygiene. The product part is making messages relevant, timely, and controllable. The engineering part is building a pipeline that’s consistent, secure, and easy to debug.

Core concepts

Before you implement anything, it helps to have a shared mental model. Push is not “send a message”. Push is “request delivery through a chain of systems”, each with its own constraints: OS policies, provider limits, app state, network availability, and user settings.

Tokens: the device address (and it changes)

A device token (or registration token) identifies an app installation on a specific device. It can rotate (OS/provider decisions), become invalid (app uninstall), or stop being deliverable (user disables notifications). Your system should treat tokens like temporary credentials: store them, refresh them, and remove them when they fail.

Topics: subscription-based broadcast

A topic is a named audience that devices can subscribe to (e.g., price_drops, release_notes). Topics simplify targeting and reduce backend complexity: instead of managing a million tokens for “people who want release notes”, you send once to a topic and let the provider fan out.

Notification payload vs data payload

Most ecosystems support two styles:

• Notification payload: the OS renders UI for you (title/body). Great for straightforward alerts.
• Data payload: the app receives key/value data and decides what to do (render, deep link, fetch). Great for custom UX.

In practice you often send both: a notification for immediate display, plus data for navigation (deep links) and analytics.

Delivery controls: TTL, priority, collapse, and “don’t spam”

These knobs matter more than most people expect:

UX primitives: channels, categories, and preference centers

Users don’t want “notifications” as a single binary switch—they want control. On Android, notification channels are the OS-native way to expose that control. On iOS, categories and app settings play a similar role. Your job is to map product intent to these primitives so users can tune without uninstalling.

Step-by-step

This is a practical build path you can follow in a real app. It starts with the product decisions (what should be pushed) and ends with the engineering reality (token lifecycle, sending, testing, and cleanup).

Step 1 — Define your notification “contract” (what is allowed)

Step 2 — Build a permission flow that earns “Allow”

The OS permission prompt is a one-shot moment. If you prompt too early, users will deny—and you may never get another chance. A good pattern is:

1. Pre-prompt: lightweight UI explaining the value (one sentence) + “Not now”.
2. Trigger: ask after a clear action (followed a topic, started tracking a shipment, saved a search).
3. Preference center: let users pick categories and frequency inside the app.

Step 3 — Implement token lifecycle on the client

A reliable system assumes tokens will change. Your app should:

• Fetch the current token on startup (after permission is granted).
• Listen for token refresh and re-register with your backend.
• Subscribe/unsubscribe to topics based on in-app preferences.
• Keep sending idempotent (don’t create duplicate device records).

Example (Android + FCM): register token, handle refresh, and manage topic subscriptions. Replace the backend URL with your own.

import com.google.firebase.messaging.FirebaseMessaging
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

// Call after notification permission is granted (Android 13+ requires runtime permission)
fun syncPushStateWithBackend(userId: String?, allowMarketing: Boolean) {
  FirebaseMessaging.getInstance().token
    .addOnSuccessListener { token ->
      // Send token + metadata to your backend (idempotent upsert)
      CoroutineScope(Dispatchers.IO).launch {
        postJson(
          url = "https://api.example.com/push/register",
          body = mapOf(
            "token" to token,
            "platform" to "android",
            "userId" to userId,
            "marketingOptIn" to allowMarketing
          )
        )
      }

      // Topic subscriptions should reflect explicit user preferences
      if (allowMarketing) {
        FirebaseMessaging.getInstance().subscribeToTopic("promos_weekly")
      } else {
        FirebaseMessaging.getInstance().unsubscribeFromTopic("promos_weekly")
      }
    }
}

class PushService : FirebaseMessagingService() {
  override fun onNewToken(token: String) {
    // Token rotated: re-sync with backend ASAP
    CoroutineScope(Dispatchers.IO).launch {
      postJson(
        url = "https://api.example.com/push/register",
        body = mapOf(
          "token" to token,
          "platform" to "android"
        )
      )
    }
  }

  override fun onMessageReceived(message: RemoteMessage) {
    // Use message.data for deep links / routing; notification payload may render automatically
    val deepLink = message.data["deep_link"]
    if (deepLink != null) {
      // Optionally cache deep link for when user taps
    }
  }
}

// Pseudo-implementation: keep it idempotent and retriable on flaky networks
suspend fun postJson(url: String, body: Map<String, Any?>) {
  // Use your HTTP client of choice; include auth if needed
}

Step 4 — Design a backend data model that supports targeting

Your backend shouldn’t store “just a token”. Store enough context to target safely and to debug. A minimal device record often includes:

Step 5 — Build payloads that navigate (and don’t surprise)

The best push is actionable: it opens the right screen and the content matches the title/body. A good payload typically includes:

• Title/body: short, specific, value-forward.
• Deep link: where to send the user on tap.
• Category/channel: so users can control this type.
• TTL + collapse: avoid stale spam and notification floods.

Example message body (FCM-style) combining notification + data + platform hints:

{
  "message": {
    "topic": "release_notes",
    "notification": {
      "title": "v2.8 is live: faster sync",
      "body": "Offline edits merge better, and conflicts are clearer. Tap to see what changed."
    },
    "data": {
      "deep_link": "unilab://changelog?v=2.8",
      "campaign": "release_2_8",
      "trace_id": "pn_2026_01_09_1421_9f3c"
    },
    "android": {
      "priority": "HIGH",
      "notification": {
        "channel_id": "product_updates",
        "tag": "release_notes",
        "click_action": "OPEN_DEEPLINK"
      },
      "ttl": "3600s"
    },
    "apns": {
      "headers": {
        "apns-priority": "10",
        "apns-collapse-id": "release_notes"
      },
      "payload": {
        "aps": {
          "category": "PRODUCT_UPDATES",
          "thread-id": "release_notes",
          "sound": "default"
        }
      }
    }
  }
}

Step 6 — Send safely: topic broadcasts and token-targeted messages

Your send pipeline should enforce rules automatically: opt-in, quiet hours, frequency caps, and deduplication. Do not rely on “remembering” these rules in each feature—centralize them in one service.

Example (Node.js): send a message via the Firebase Admin SDK, with cleanup for invalid tokens and a trace ID for debugging.

import admin from "firebase-admin";

admin.initializeApp({
  credential: admin.credential.applicationDefault()
});

// Centralized send: enforce opt-in, caps, and quiet hours before calling this.
export async function sendPushToToken({ token, title, body, deepLink, traceId }) {
  const message = {
    token,
    notification: { title, body },
    data: {
      deep_link: deepLink ?? "",
      trace_id: traceId
    },
    android: {
      priority: "high",
      ttl: 60 * 60 * 1000, // 1 hour
      notification: {
        channelId: "product_updates",
        tag: "updates"
      }
    },
    apns: {
      headers: {
        "apns-priority": "10",
        "apns-collapse-id": "updates"
      },
      payload: {
        aps: {
          category: "PRODUCT_UPDATES",
          threadId: "updates",
          sound: "default"
        }
      }
    }
  };

  try {
    const messageId = await admin.messaging().send(message);
    return { ok: true, messageId };
  } catch (err) {
    // Handle invalid/expired tokens so you don't retry forever.
    // Common strategy: mark token as inactive and stop sending to it.
    const code = err?.errorInfo?.code || err?.code || "unknown";
    const isInvalid =
      code === "messaging/registration-token-not-registered" ||
      code === "messaging/invalid-registration-token";

    return { ok: false, code, deactivateToken: isInvalid };
  }
}

Step 7 — Debug like a pro: “it didn’t arrive” checklist

Delivery is affected by user settings, OS policies, device state, and provider responses. When a push doesn’t arrive, avoid guessing. Work from evidence in this order:

Step 8 — Measure what matters (and iterate)

Open rate is a weak proxy. Track the user journey: push received → opened → performed the intended action. Then improve by targeting and timing, not by sending more.

Common mistakes

Most push notification failures are predictable. Here are the pitfalls that cause low opt-in, low engagement, and “random” delivery issues—plus concrete fixes.

FAQ

Should I use tokens or topics for push notifications?

Use topics for interest-based audiences and tokens for personal or transactional messages. Topics keep your backend simple for broadcasts, while tokens are best for 1:1 content (order updates, account alerts, personalized recommendations).

Why do push notifications sometimes “not arrive” even if the provider accepted the send?

Acceptance is not the same as immediate delivery. Device state (offline, battery saver), user settings (disabled notifications, focus/DND), OS policies, TTL expiry, and environment mismatches can prevent display even if the provider returns success.

What’s the best time to ask for notification permission?

After the user experiences value and expects an update. Trigger the prompt after actions like tracking an order, saving a search, following a topic, or enabling reminders—then offer category controls so “Allow” feels safe.

What should I include in a push payload?

Keep it small and actionable: title/body, a deep link, a category/channel, and delivery controls (TTL/collapse). Add a trace ID for debugging and analytics, and avoid stale promotions by setting an appropriate TTL.

How do I handle invalid or expired tokens?

Deactivate them on provider error and stop retrying. Treat “token not registered/invalid” as a cleanup signal. Also handle token refresh events on the client to re-register automatically.

How do I prevent notification spam as my app grows?

Centralize policy: frequency caps, quiet hours, per-category opt-in, and collapse rules should live in one “notification service” rather than in each feature team’s code. This keeps behavior consistent and protects user trust.

Cheatsheet

A scan-fast checklist for shipping push notifications without annoying users (or yourself).

Wrap-up

Push notifications done right are not magic—they’re a set of consistent choices: earn permission, target with intent, design payloads that navigate, and build a pipeline you can debug. If you implement token lifecycle + cleanup, use topics for broad opt-in audiences, and enforce caps/quiet hours, you’ll avoid the two classic outcomes: “nobody opts in” and “everybody opts out.”

Want to go deeper on shipping-quality mobile systems? The related posts below cover platform tradeoffs, testing, networking, and CI—perfect companions to a reliable notifications pipeline.

Related posts

• Flutter vs React Native vs Native: A Real Decision Guide
• Offline-First Apps: Sync Conflicts Without User Tears
• Mobile Testing Strategy: Unit, UI, Snapshot, and E2E
• CI for Mobile Apps: Fast Builds, Signing, and Release Automation
• App Store Optimization (ASO) for Developers: What Actually Matters
• Mobile Networking: Retries, Timeouts, and Backoff Like a Pro