Push notifications

A push reaches a device through a token, and that token belongs to a signed-in user. The Courier mobile SDKs register and refresh those tokens for you. How much they do depends on the native hook you wired up, so it is per provider, not per platform.

Provider	Key	iOS	Android
APNs	`apn`	Automatic via `CourierDelegate`	Not applicable
Firebase Cloud Messaging	`firebase-fcm`	Manual	Automatic via `FirebaseMessagingService`
Expo	`expo`	Manual	Manual
OneSignal	`onesignal`	Manual	Manual
Pusher Beams	`pusher-beams`	Manual	Manual

Anything marked Manual you register yourself, and the rest of this page is how.

Hand the SDK a token

setToken is for a provider the SDK cannot fetch from, one marked Manual in the table above. You supply the string, and everything after that is still the SDK’s job. It writes to the same place the API does. setToken calls against the signed-in user, with the device record attached. There is no separate SDK store. It first deletes whichever token it last cached for that provider, so a device does not leave stale rows behind. That delete is best effort, and a failure is logged rather than thrown. Call it before anyone signs in and the token is only held on the device. signIn writes every held token to that user, and signOut deletes them again, so a shared device stops receiving the previous user’s pushes.

The device rotates its token on reinstall, on restore, and when app data is cleared. Call setToken again from that provider’s own refresh callback, or the stale one fails at the provider rather than in your code.

Task {
    // APNs token
    try await Courier.shared.setAPNSToken(deviceToken)

    // FCM or another provider
    try await Courier.shared.setToken(for: .firebaseFcm, token: fcmToken)
}

lifecycleScope.launch {
    Courier.shared.setToken(
        provider = "firebase-fcm",
        token = "your_messaging_token"
    )
}

await Courier.shared.setTokenForProvider(
  token: fcmToken,
  provider: CourierPushProvider.firebaseFcm,
);

await Courier.shared.setToken(token: 'token_value', provider: 'YOUR_PROVIDER');

import { CourierPushProvider } from "@trycourier/courier-react-native";

await Courier.shared.setTokenForProvider({
    provider: CourierPushProvider.FIREBASE_FCM,
    token: "your_messaging_token"
});

await Courier.shared.setToken({ key: "your-provider-key", token: "your_messaging_token" });

Manage tokens yourself

setToken still leaves the lifecycle to the SDK. To do the CRUD yourself, address the same user through one of two APIs. From a backend, or an app with no Courier SDK, use the Token Management API:

Store one with
Read what a user has with
Remove one on logout with

Calling all three is then your job, on every device. Nothing cleans up on sign-out, and nothing re-registers a rotated token. From inside the app, without signing anyone in, construct a CourierClient and go through its token client. It reaches the same two endpoints, authenticating with the JWT the way signIn does, and it writes nothing to Courier.shared.

let client = CourierClient(jwt: jwt, userId: "user_123")

try await client.tokens.putUserToken(
    token: fcmToken,
    provider: "firebase-fcm"
)

try await client.tokens.deleteUserToken(token: fcmToken)

val client = CourierClient(jwt = jwt, userId = "user_123")

client.tokens.putUserToken(
    token = fcmToken,
    provider = "firebase-fcm",
    device = CourierDevice.current(context)
)

client.tokens.deleteUserToken(token = fcmToken)

final client = CourierClient(jwt: jwt, userId: 'user_123');

await client.tokens.putUserToken(
  token: fcmToken,
  provider: 'firebase-fcm',
);

await client.tokens.deleteUserToken(token: fcmToken);

const client = new CourierClient({ userId: "user_123", jwt: jwt });

await client.tokens.putUserToken({
  token: fcmToken,
  provider: "firebase-fcm",
});

await client.tokens.deleteUserToken({ token: fcmToken });

The client covers writing and deleting only. Listing a user’s tokens is REST, so has no client equivalent. On Android device is required, and CourierDevice.current(context) fills it.

Read the tokens the SDK is holding

Useful when a push does not arrive and you need to confirm the device actually registered.

let apns = await Courier.shared.apnsToken            // Data?
let fcm = await Courier.shared.getToken(for: .firebaseFcm)
let all = await Courier.shared.tokens                // [String: String]

val fcm = Courier.shared.fcmToken

// Force Firebase to hand the SDK a fresh token
lifecycleScope.launch {
    Courier.shared.refreshFcmToken()
    val token = Courier.shared.getToken(provider = "your-provider-key")
}

final fcm = await Courier.shared.getTokenForProvider(
  provider: CourierPushProvider.firebaseFcm,
);
final other = await Courier.shared.getToken(provider: 'YOUR_PROVIDER');

const forKey = await Courier.shared.getToken({ key: "your-provider-key" });
const forProvider = await Courier.shared.getTokenForProvider({
  provider: CourierPushProvider.EXPO,
});
const all = await Courier.shared.getAllTokens();

Notification permissions

Each SDK wraps the platform permission calls, so you prompt, read the status, and recover from a denial without touching the native APIs.

Function	Does
`requestNotificationPermission`	Shows the system dialog. The setup steps above call this once.
`getNotificationPermissionStatus`	Reads the status without prompting. Android calls it `isPushPermissionGranted`.
`openSettingsForApp`	Opens your app’s settings page, the only route back after a denial.

// Prompts once, then returns the resulting UNAuthorizationStatus
let status = try await Courier.requestNotificationPermission()

// Reads the status without prompting
let current = try await Courier.getNotificationPermissionStatus()

// Send the user here after they deny the dialog
Courier.openSettingsForApp()

// Prompts on Android 13 and later, a no-op below API 33
Courier.shared.requestNotificationPermission(activity)

// Reads the status without prompting
val isGranted = Courier.shared.isPushPermissionGranted(context)

final status = await Courier.requestNotificationPermission();

final current = await Courier.getNotificationPermissionStatus();

await Courier.openSettingsApp();

const status = await Courier.requestNotificationPermission();

const current = await Courier.getNotificationPermissionStatus();

Courier.openSettingsForApp();

The system dialog appears once. After that only the user can change the setting, so read the status on launch and offer your own prompt into settings when it is denied.

Android has no openSettingsForApp, and Flutter names it openSettingsApp. iOS returns a UNAuthorizationStatus, Flutter and React Native return a string, and Android’s check returns a Boolean.

Control how iOS presents a foreground push

By default iOS suppresses the system banner while your app is open. Set the presentation options to change that.

// Returned from your CourierDelegate override
override func pushNotificationDeliveredInForeground(
    message: [AnyHashable: Any]
) -> UNNotificationPresentationOptions {
    return [.sound, .list, .banner, .badge]
}

Courier.setIOSForegroundPresentationOptions(options: [
  iOSNotificationPresentationOption.banner,
  iOSNotificationPresentationOption.sound,
  iOSNotificationPresentationOption.list,
  iOSNotificationPresentationOption.badge,
]);

Courier.setIOSForegroundPresentationOptions({
  options: ["sound", "badge", "list", "banner"],
});

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Push notifications

Hand the SDK a token

Manage tokens yourself

Read the tokens the SDK is holding

Notification permissions

Control how iOS presents a foreground push

​Hand the SDK a token

​Manage tokens yourself

​Read the tokens the SDK is holding

​Notification permissions

​Control how iOS presents a foreground push

Hand the SDK a token

Manage tokens yourself

Read the tokens the SDK is holding

Notification permissions

Control how iOS presents a foreground push