@suprsend/expo-sdk

SuprSend SDK for Expo and React Native — combines the headless inbox feed from @suprsend/react-core with native push notifications (FCM + APNs) via expo-notifications.

Install

npx expo install @suprsend/expo-sdk \
  expo-notifications expo-secure-store expo-application

SuprSendExpoProvider

SuprSendExpoProvider identifies the current user and is required by both the feed and push notification providers. Wrap your app (or the authenticated portion of it) with it once:

import { SuprSendExpoProvider } from "@suprsend/expo-sdk";

export default function App() {
  return (
    <SuprSendExpoProvider
      publicApiKey={process.env.SUPRSEND_PUBLIC_KEY!}
      distinctId={currentUser.id}
      userToken={currentUser.suprsendToken}
    >
      <RootNavigator />
    </SuprSendExpoProvider>
  );
}

interface SuprSendExpoProviderProps {
  publicApiKey: string;
  distinctId?: unknown;
  userToken?: string; // jwt token needed when enhanced security mode is enabled
  host?: string; // custom host url
  refreshUserToken?: (
    oldUserToken: string,
    tokenPayload: Dictionary,
  ) => Promise<string>; // called after current user token expiry, call your BE api and return new user token
}

See client authentication for how to generate userToken on your backend.

Passing null (or undefined) for distinctId after a user was previously identified resets the client and clears the authenticated user — use this on logout.

Inside this provider you can mount SuprSendFeedProvider (for the inbox feed) and/or SuprSendPushProvider (for push notifications) — each is independent, so use whichever your app needs.

useSuprSendClient

This hook contains SuprSend client instance and has all the methods like, preferences, user methods etc. Read more here: https://github.com/suprsend/suprsend-react-core?tab=readme-ov-file#usesuprsendclient

Push notifications

Native FCM + APNs push delivery via expo-notifications.

For platform-specific setup (APNs credentials and entitlement on iOS, google-services.json and FCM credentials on Android), see PUSH_SETUP.md.

import { SuprSendExpoProvider, SuprSendPushProvider } from "@suprsend/expo-sdk";

export default function App() {
  return (
    <SuprSendExpoProvider {...authProps}>
      <SuprSendPushProvider>
        <RootNavigator />
      </SuprSendPushProvider>
    </SuprSendExpoProvider>
  );
}

SuprSendPushProvider waits for the user to be identified, then requests permission, obtains the native FCM/APNs token, and registers it with SuprSend.

Handling taps and foreground notifications

useSuprSendPushNotifications returns onPushNotificationReceived / onPushNotificationTapped subscribers. Each takes a handler and returns an unsubscribe function — drop them straight into useEffect.

import { useEffect } from "react";
import { useSuprSendPushNotifications } from "@suprsend/expo-sdk";

function PushListeners() {
  const { onPushNotificationReceived, onPushNotificationTapped } =
    useSuprSendPushNotifications();

  useEffect(
    () =>
      onPushNotificationReceived((notification) => {
        console.log("notification delivered", notification);
      }),
    [onPushNotificationReceived],
  );

  useEffect(
    () =>
      onPushNotificationTapped((response) => {
        console.log("notification tapped", response);
      }),
    [onPushNotificationTapped],
  );

  return null;
}

Unregister push

Call unregisterPushNotification() to remove the push token from the user in SuprSend. Usually called just before logout.

Manual registration

Disable auto-registration and call registerPushNotification() yourself — e.g. after an onboarding screen:

<SuprSendPushProvider autoRegister={false}>...</SuprSendPushProvider>

import { useSuprSendPushNotifications } from "@suprsend/expo-sdk";

function EnableNotificationsButton() {
  const { registerPushNotification } = useSuprSendPushNotifications();
  return (
    <Button
      title="Enable notifications"
      onPress={() => registerPushNotification()}
    />
  );
}

Push API reference

interface SuprSendPushProviderProps {
  children: ReactNode;
  autoRegister?: boolean;                         // default: true
  customNotificationHandler?: (notification: Notification) =>
    | NotificationBehavior
    | Promise<NotificationBehavior>;
  setupAndroidNotificationChannel?: () => Promise<void>;
}

useSuprSendPushNotifications(): {
  registerPushNotification: () => Promise<string | null>;
  unregisterPushNotification: () => Promise<void>;
  onPushNotificationReceived: (handler: (notification: Notification) => void) => () => void;
  onPushNotificationTapped:   (handler: (response: NotificationResponse) => void) => () => void;
};

Inbox feed

Headless in-app notification feed, re-exported from @suprsend/react-core. Render with React Native primitives.

Mount SuprSendFeedProvider inside SuprSendExpoProvider:

import { SuprSendExpoProvider, SuprSendFeedProvider } from "@suprsend/expo-sdk";

export default function App() {
  return (
    <SuprSendExpoProvider {...authProps}>
      <SuprSendFeedProvider>
        <RootNavigator />
      </SuprSendFeedProvider>
    </SuprSendExpoProvider>
  );
}

import { useFeedData, useFeedClient } from "@suprsend/expo-sdk";
import { FlatList, Text, Pressable } from "react-native";

function Inbox() {
  const feedData = useFeedData();
  const feedClient = useFeedClient();
  const { refresh } = useFeed(); // used to refresh inbox instance like pull to refresh etc

  return (
    <FlatList
      data={feedData?.notifications ?? []}
      keyExtractor={(n) => n.n_id}
      renderItem={({ item }) => (
        <Pressable onPress={() => feedClient?.markAsInteracted(item.n_id)}>
          <Text>{item.message.header}</Text>
        </Pressable>
      )}
    />
  );
}

Read more about available context and hooks:

• SuprSendFeedProvider
• useFeedClient
• useFeedData

See a full example: InboxScreen.tsx.

Preferences

Headless hooks for reading and updating a user's notification preferences, re-exported from @suprsend/react-core. The API is identical — follow the React preferences guide to wire it up in Expo.

See a full example: PreferenceScreen.tsx.