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.
push.parse(data: Record<string, unknown>) for deep links and buttons
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_KEYmust be configured — the same key the email open pixel uses. Push opens are sealed with the identicalinternal/emailtrackmechanism, just taggedchannel: "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_trackingdefault, 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 anoptima_openkey,push.parsereturnsopenToken: null, andtrackOpencorrectly does nothing — there is no error state here, just "nothing to track." push_token_fcmand/orpush_token_apnsmust be allowlisted identifiers in the tenant'sidentify_allowed_keys— otherwisepush.setToken'sidentify(...)call succeeds but the server drops the key (visible in theidentifyevent'sdroppedlist, 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.
}