Skip to content
Optima docs
SDKsReact Native SDK

Push notifications

React Native SDK v1.2.0 — Push notifications

The SDK has no push library dependency of its own — it never registers for FCM or APNs, never receives a push, and doesn't render a notification for you. What it provides is the three hooks that connect your push integration to Optima: registering the device's token so campaigns can target it, parsing an Optima-built payload, and recording that a delivered push was opened. You still install and wire your own push library.

@react-native-firebase/messaging recipe

import messaging from "@react-native-firebase/messaging";
import { Optima } from "@optima/react-native";

// Token registration and refresh
messaging().getToken().then((token) => Optima.instance.push.setToken(token));
messaging().onTokenRefresh((token) => Optima.instance.push.setToken(token));

// A push opened the app from background
messaging().onNotificationOpenedApp((remoteMessage) => {
  Optima.instance.push.trackOpen(remoteMessage.data ?? {});
  const parsed = Optima.instance.push.parse(remoteMessage.data ?? {});
  if (parsed?.deepLink) navigateTo(parsed.deepLink);
});

// A push opened the app from a cold start
messaging().getInitialNotification().then((remoteMessage) => {
  if (!remoteMessage) return;
  Optima.instance.push.trackOpen(remoteMessage.data ?? {});
  const parsed = Optima.instance.push.parse(remoteMessage.data ?? {});
  if (parsed?.deepLink) navigateTo(parsed.deepLink);
});

push.setToken(token) defaults the identifier key from Platform.OS (push_token_apns on iOS, push_token_fcm everywhere else) — pass {platform: "fcm"}/{platform: "apns"} explicitly only if you need to override that (uncommon). It stores the token and, if it's new or changed, immediately calls identify({push_token_<platform>: token}) to attach it to the device's current profile — a no-op if the value hasn't actually changed, so it's safe to call unconditionally from getToken()/onTokenRefresh on every app start. The token is remembered as synced only once the gateway accepts it; until then the SDK retries on the next setToken and on every foreground. Under beforeDecision: "buffer" the sync waits for the visitor's consent decision.

expo-notifications recipe

import * as Notifications from "expo-notifications";
import { Optima } from "@optima/react-native";

// Token registration
Notifications.getDevicePushTokenAsync().then(({ data }) => Optima.instance.push.setToken(data));

// A push opened the app (background or cold start)
Notifications.addNotificationResponseReceivedListener((response) => {
  const data = response.notification.request.content.data ?? {};
  Optima.instance.push.trackOpen(data);
  const parsed = Optima.instance.push.parse(data);
  if (parsed?.deepLink) navigateTo(parsed.deepLink);
});

Notifications.getLastNotificationResponseAsync().then((response) => {
  if (!response) return;
  const data = response.notification.request.content.data ?? {};
  Optima.instance.push.trackOpen(data);
});

getDevicePushTokenAsync() returns the native token (APNs on iOS, FCM on Android) — push.setToken infers the right platform key from Platform.OS the same way as the Firebase recipe, so this one call works for both platforms without branching. expo-notifications delivers data values already typed (not all-string, unlike a raw FCM payload) — push.parse accepts either shape for its buttons field (a JSON string or an already-parsed array), so both recipes above work unchanged.

Reading the payload with push.parse

push.parse(data) reads the reserved data keys the deliverer sends — deep_link, buttons, optima_open, image_url — and returns OptimaPush{deepLink, buttons, data, openToken}, where data is every other key (your own custom payload, with the reserved keys filtered out). It returns null if none of the reserved keys are present at all — a signal that this message wasn't built by Optima's delivery pipeline, so you can fall through to whatever else handles your other push sources. Use parsed.buttons (PushButton[], {id, label, deepLink}) to render your own custom notification-response UI, or an in-app action sheet if the push arrived while the app was foregrounded and you're handling display yourself.

push.trackOpen

Call it from wherever your push library surfaces "the user tapped this notification" — both recipes above show the two call sites (background/cold start), and it's safe to call unconditionally on every launch, including a normal (non-push) app open: trackOpen looks for optima_open; if absent, it does nothing and returns false. If present and non-blank, it fires GET /edge/v1/o/{token} fire-and-forget (a 5-attempt backoff ladder, failures logged at debug only — a missed open record never surfaces as an app-visible error event) and returns true immediately, without waiting for the request to land.

Both recipes above call push.parse right after trackOpen to pull deepLink/buttons out of the same payload — trackOpen and parse are independent calls (call one, the other, or both; neither depends on the other having run) that both read from the identical reserved-key set.

What the backend needs

Three prerequisites, all covered in the operator-facing sections of FEATURES.md/TASK.md in the main optima repo:

  • EMAIL_TRACK_KEY must be configured — the same key the email open pixel uses. Push opens are sealed with the identical internal/emailtrack mechanism, just tagged channel: "push" instead of the email pixel's implicit channel.
  • Open tracking must be turned on for the push template (or the instance-wide email_open_tracking default, if the template doesn't override it) — the same switch email templates use, not a separate mobile-specific one. If it's off, the send simply never mints an optima_open key, push.parse returns openToken: null, and trackOpen correctly does nothing — there is no error state here, just "nothing to track."
  • push_token_fcm and/or push_token_apns must be allowlisted identifiers in the tenant's identify_allowed_keys — otherwise push.setToken's identify(...) call succeeds but the server drops the key (visible in the identify event's dropped list, and, more importantly, in a campaign never actually reaching the device because the token was never attached). These are two different identifier keys — a tenant shipping both Android and iOS traffic needs both allowlisted.

optima_open is a reserved data key — the backend rejects any attempt by a template author to set it themselves, so it's always the delivery pipeline's own minted token, never something a campaign's custom data payload could spoof or collide with.

reset() and the token

reset() deliberately preserves _optima_push_token and, as one of its final steps, re-sends it via identify({push_token_<platform>: token}) under the new device id — because the physical device (and its push registration) hasn't changed, only the person using the app has, and pushes should keep reaching this device under whatever profile it resolves to next.

If the outgoing user should not keep receiving pushes meant for this device once a new person logs in — the common case for a genuinely shared/kiosk device, less so for "my personal phone, I logged out of one account and into another" — call push.setToken(null) before calling reset(). setToken(null) forgets the token locally without notifying the server, so reset()'s re-attach step finds nothing to re-send:

function logout(): void {
  Optima.instance.push.setToken(null);
  Optima.instance.reset();
  // Once a fresh token arrives (onTokenRefresh, or the next app start),
  // call setToken(token) again to re-attach it.
}

On this page