Add Sumly to a React Native or Expo app
One TypeScript file, no native module and no new build step. It sends screens and events and, with autocapture, every tap, the way the site script counts clicks, under the person RevenueCat knows, so each purchase shows the screens, the buttons and the source that came before it.
Step by step
- 1
In Sumly, open Visitors and copy your project's public key (
sl_…). Add the SDK withnpm i @sumly/sdk(or copy it as one file:curl -o sumly.ts https://sumly.dev/sdk/sumly.ts), and add AsyncStorage (npx expo install @react-native-async-storage/async-storage) so the queue survives a restart. - 2
At start, call
Sumly.init({ siteKey: 'sl_…', storage: AsyncStorage }). AfterPurchases.configure, and again after eachPurchases.logInorlogOut, callSumly.identify(await Purchases.getAppUserID()). - 3
Count screens: with Expo Router,
Sumly.screen(pathname)in the root layout; with React Navigation, on the container'sonReadyandonStateChange. They show on the project's Sources list within 15 seconds, as Mobile SDK.
Once, as the app starts, outside any component. The other tabs use these imports too.
// App.tsx
import AsyncStorage from '@react-native-async-storage/async-storage';
import Purchases from 'react-native-purchases';
import { Sumly } from '@sumly/sdk/react-native';
Sumly.init({ siteKey: 'sl_your_key', storage: AsyncStorage, appVersion: '1.4.0' });
export async function startPurchases(): Promise<void> {
Purchases.configure({ apiKey: REVENUECAT_KEY });
Sumly.identify(await Purchases.getAppUserID());
}
// after signing in or out
export async function signIn(userId: string): Promise<void> {
await Purchases.logIn(userId);
Sumly.identify(await Purchases.getAppUserID());
}
Or do it in one command
In your project's folder. It finds React Native and Expo, shows you the change before writing anything, and waits until the first screen arrives. Add --key sl_… with your key from Visitors, or it asks for it.
Or let your coding assistant do it
Paste this into Claude Code, Cursor or Codex in your project. It fits the code to how your project is built, asks you for the dashboard steps and leaves the keys to you.
See what it says
Set up React Native and Expo for Sumly in this project.
Sumly (https://sumly.dev) shows revenue next to the visits and app users it came from. The full guide is https://sumly.dev/install/react-native; read it if anything below is unclear.
Steps:
1. In Sumly, open Visitors and copy your project's public key (`sl_…`). Add the SDK with `npm i @sumly/sdk` (or copy it as one file: `curl -o sumly.ts https://sumly.dev/sdk/sumly.ts`), and add AsyncStorage (`npx expo install @react-native-async-storage/async-storage`) so the queue survives a restart.
2. At start, call `Sumly.init({ siteKey: 'sl_…', storage: AsyncStorage })`. After `Purchases.configure`, and again after each `Purchases.logIn` or `logOut`, call `Sumly.identify(await Purchases.getAppUserID())`.
3. Count screens: with Expo Router, `Sumly.screen(pathname)` in the root layout; with React Navigation, on the container's `onReady` and `onStateChange`. They show on the project's Sources list within 15 seconds, as Mobile SDK.
Setup: Once, as the app starts, outside any component. The other tabs use these imports too.
```
// App.tsx
import AsyncStorage from '@react-native-async-storage/async-storage';
import Purchases from 'react-native-purchases';
import { Sumly } from '@sumly/sdk/react-native';
Sumly.init({ siteKey: 'sl_your_key', storage: AsyncStorage, appVersion: '1.4.0' });
export async function startPurchases(): Promise<void> {
Purchases.configure({ apiKey: REVENUECAT_KEY });
Sumly.identify(await Purchases.getAppUserID());
}
// after signing in or out
export async function signIn(userId: string): Promise<void> {
await Purchases.logIn(userId);
Sumly.identify(await Purchases.getAppUserID());
}
```
Expo Router: In the root layout, as Expo's own screen tracking guide does it.
```
// app/_layout.tsx
import { Slot, usePathname } from 'expo-router';
import { useEffect } from 'react';
export default function Layout() {
const pathname = usePathname();
useEffect(() => {
Sumly.screen(pathname);
}, [pathname]);
return <Slot />;
}
```
React Navigation: onStateChange does not run for the first screen, so onReady counts that one.
```
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
export function Root() {
const navigationRef = useNavigationContainerRef();
const count = () => Sumly.screen(navigationRef.getCurrentRoute()?.name ?? 'App');
return (
<NavigationContainer ref={navigationRef} onReady={count} onStateChange={count}>
<AppNavigator />
</NavigationContainer>
);
}
```
Taps: Every tap on something pressable counts by itself, on its screen, like a click on your website: its label or words, testID and component, never where or what was typed. The project needs Every click, without marking on in its Visitors settings too. Taps show under Visitors › Clicks & replays.
```
import { Pressable, Text, View } from 'react-native';
Sumly.init({ siteKey: 'sl_your_key', storage: AsyncStorage, autocapture: true });
// around the whole app, once: it only listens
export default function App() {
return (
<Sumly.Touches>
<AppNavigator />
</Sumly.Touches>
);
}
// a clearer name and a stable place for a button that matters
export const Buy = ({ onBuy }: { onBuy: () => void }) => (
<Pressable sumly-label="Start trial" testID="start-trial" onPress={onBuy}>
<Text>Start my 7-day trial</Text>
</Pressable>
);
// leave a part out
export const Account = ({ email }: { email: string }) => (
<View sumly-no-capture>
<Text>{email}</Text>
</View>
);
```
Heatmaps: Optional, off unless you turn it on. Each tap also says where on the screen it landed, a tap on nothing pressable is a dead tap, and the app sends one picture of each screen (once per app version and screen size), so Sumly draws the taps over the screen itself under Visitors › Clicks & replays. Text fields are covered in the picture; maskImages covers pictures too, sumly-mask any part, and sumly-unmask leaves one field as it is. Needs react-native-view-shot (npx expo install react-native-view-shot) and <Sumly.Touches> around the app.
```
import { captureRef } from 'react-native-view-shot';
import { Text, TextInput, View } from 'react-native';
Sumly.init({ siteKey: 'sl_your_key', storage: AsyncStorage, heatmaps: { screenshot: captureRef, maskImages: true } });
export const Profile = ({ email }: { email: string }) => (
<View>
<View sumly-mask>
<Text>{email}</Text>
</View>
<TextInput sumly-unmask placeholder="Search" />
</View>
);
```
Consent: Where your app asks first.
```
Sumly.init({ siteKey: 'sl_your_key', storage: AsyncStorage, waitForConsent: true });
Sumly.consent(true); // when the person agrees
Sumly.consent(false); // when they refuse, or take it back
```
Own domain: Optional: your own address takes app events too.
```
Sumly.init({ siteKey: 'sl_your_key', storage: AsyncStorage, endpoint: 'https://signal.example.com' });
```
Keep in mind: Until `identify`, events go under an id made for this install; the ones still waiting move to the first id you give. Without RevenueCat, give your own user id, and call `Sumly.reset()` on sign-out. Offline, screens and events wait in the queue (kept across restarts with AsyncStorage) and go once the network is back, dated when they happened. In a browser (Expo web, React Native Web) the same app counts as a web app: platform `webapp`, apart from your website's visitors. For a website, use the site script. Taps need `<Sumly.Touches>` around the app. A release build can shorten component names, so give the buttons that matter a `testID` or `sumly-label`. Every option, identify and reset, installs and heatmaps in full: [the SDK page](/integrations/sdk). To ask where people heard about the app: [the heard_from recipe](/docs/api#heard-from).
How to work:
- Look at how this project is built first, and fit the code to its framework and its way of doing things; the examples above are a starting point, not something to paste as is.
- Steps that happen in a dashboard (Sumly, or React Native and Expo's own) are mine: tell me exactly what to click, then wait for me.
- Keys the code needs belong in environment variables, never in the code or the repository. Never ask me to paste a secret key into this chat; tell me which variable to set.
- Change only what this needs, show me the changes before you commit, and tell me how to check that it works.
- sl_your_key stands for the project's public key; it is on the Visitors page in Sumly. Ask me for it.
Consent
Where your app asks first, start with waitForConsent: nothing is kept or sent until consent(true), and consent(false) stops sending and empties the queue. The answer is remembered.
Purchases
Purchases do not come through the app: Sumly reads them from RevenueCat, Adapty or Superwall. Give identify the same person they know: RevenueCat's app user id (the anonymous one too), or the user id you pass to Adapty.identify or Superwall.identify. Each purchase then shows the screens and the source that came before it.
Buyers' names
Apple and Google never share who bought. To see a buyer's name or e-mail on their payments, send it from your server with the secret key: { "type": "identify", "user_id": "u_42", "traits": { "name": "Ana Novak", "email": "[email protected]" } } to /api/v1/events, with the same user id RevenueCat knows. Payments already kept take the name too. An empty trait clears it, and { "type": "forget", "user_id": "u_42" } removes them when they delete their account. Only the name and e-mail are kept, never shown publicly; without them the buyer stays "App user u_42".
Your own domain
Optional. The own address of your site's script (one DNS record on Visitors, on every plan) takes app events too: give it as the endpoint and the app sends to /api/v1/events there.
Good to know
- Until
identify, events go under an id made for this install; the ones still waiting move to the first id you give. Without RevenueCat, give your own user id, and callSumly.reset()on sign-out. - Offline, screens and events wait in the queue (kept across restarts with AsyncStorage) and go once the network is back, dated when they happened.
- In a browser (Expo web, React Native Web) the same app counts as a web app: platform
webapp, apart from your website's visitors. For a website, use the site script. - Taps need
<Sumly.Touches>around the app. A release build can shorten component names, so give the buttons that matter atestIDorsumly-label. - Every option, identify and reset, installs and heatmaps in full: the SDK page. To ask where people heard about the app: the heard_from recipe.
From React Native and Expo's own documentation, checked 4 November 2026: docs.expo.dev/router/reference/screen-tracking, reactnavigation.org/docs/screen-tracking, revenuecat.com/docs/customers/identifying-customers .
Other apps
Try it with your own projects
Sign in with Google or a code by e-mail and connect your first project. The first 14 days of a paid plan are free, with no card.
Start freeOr look around first: open the live demo.