React Native and Expo SDK

react-native-appy is an Expo module over the native iOS SDK and Android SDK, with TypeScript types and a config plugin that sets up Associated Domains and Android App Links from app.json. It works in Expo apps and in bare React Native apps. The native guides go deeper on each topic; this page covers what is specific to React Native.

Requirements#

• Expo SDK 54 or later. Bare React Native apps add the expo package with npx install-expo-modules@latest.
• iOS 15.1 or later, Android 5.0 (API 21) or later.
• A development build. Expo Go cannot load the native code.
• An app registered with Appy on the Enterprise plan, and its publishable key (appy_pk_…).

Install the package#

npx expo install react-native-appy

Register the app once under Apps & SDK in the dashboard or with POST /v1/apps: the Apple Team ID and bundle ID for iOS, the package name and every signing certificate’s SHA-256 fingerprint for Android, including Google Play’s app signing key and your EAS credentials. You get the publishable key and your link domain, such as acme.appy.to. See Register your app in the iOS guide and in the Android guide.

Add the config plugin#

{
  "expo": {
    "scheme": "acme",
    "plugins": [
      ["react-native-appy", { "linkDomains": ["acme.appy.to"] }]
    ]
  }
}

Run npx expo prebuild or an EAS build afterwards. The plugin adds applinks:acme.appy.to to the iOS entitlements, an autoVerify App Link intent filter to the main Android activity, the AppySDK pod to the Podfile from the iOS SDK’s Git repository (the CocoaPods trunk no longer accepts new pods), and Android backup rules that keep the first launch after a reinstall. The scheme lets in-app browsers that ignore Universal Links open your app through the Appy redirect page.

Bare React Native#

Without prebuild, add the Associated Domains capability and URL scheme in Xcode, the intent filters from Add intent filters and the backup rules from Keep the first launch a first launch, and this line inside your app target in ios/Podfile:

pod 'AppySDK', :git => 'https://github.com/appy-to/appy-ios-sdk.git', :tag => '1.0.0'

No other native code is needed: the package receives links from the app delegate on iOS, including scene events that ExpoAppDelegate forwards, and from the React activity on Android.

Configure the SDK#

Call configure once, at module scope of your entry file, such as app/_layout.tsx with Expo Router:

import Appy from 'react-native-appy';

Appy.configure({
  publishableKey: 'appy_pk_live_…',
  linkDomains: ['acme.appy.to'],
  logLevel: __DEV__ ? 'debug' : 'error',
});

A link that opens the app before configure runs, such as the link of a cold start, is kept by the native SDK and resolved right after it. A second configure call in the same process, for example after a JavaScript reload, is ignored.

Handle deep links#

import { useEffect } from 'react';
import { router } from 'expo-router';
import Appy from 'react-native-appy';

useEffect(() => {
  const subscription = Appy.addDeepLinkListener((result) => {
    if (result.status === 'found') {
      const item = result.link.parameters.item;
      router.push(item ? `/items/${item}` : `/campaigns/${result.link.slug}`);
    }
  });
  return () => subscription.remove();
}, []);

• The first launch after install calls the listener exactly once. Every Appy link that opens the app, cold or warm, arrives as 'found'. Other launches call nothing.
• A result that arrives while no listener is registered is kept by the native SDK and delivered once to the next listener. Register it in a component that lives as long as the app, such as the root layout.
• A link has url, deeplinkUrl, slug, parameters, isDeferred and clickedAt (a Date). When Appy cannot be reached, a link that opened the app still arrives, read from its own URL, with deeplinkUrl and clickedAt set to null.
• getLatestDeepLink() resolves to the most recent link, including a deferred link that arrived after the timeout.
• Links from push notifications, in-app messages or QR scanners: pass the URL to Appy.handleUrl(url). It resolves to true for an Appy link, which then reaches the listener.

Expo Router and React Navigation#

React Native’s Linking also receives every link that opens the app, so your router would try to open /spring for https://acme.appy.to/spring. Let the Appy listener route those links and tell the router to ignore them. With Expo Router, add app/+native-intent.tsx:

import { isAppyLink } from 'react-native-appy';

export function redirectSystemPath({ path }: { path: string; initial: boolean }) {
  return isAppyLink(path, ['acme.appy.to']) ? null : path;
}

isAppyLink is true for URLs on your link domains and for any URL with appy_click_id. Without the second argument it uses the link and email link domains passed to configure; with it, list your email link domains there too. With React Navigation, apply the same check in linking.getInitialURL and linking.subscribe.

Deferred deep links#

On the first launch after install, the package asks Appy for the link tapped before the install. The listener receives 'found' with isDeferred === true, or 'notFound' for an organic install, within deferredDeepLinkTimeoutMs counted from configure. With openDeferredDeepLinks: true the SDK also opens the link’s deeplinkUrl, which your router receives through Linking; route deferred links in one of the two places, not both. Deferred deep links in the iOS guide explains timing and testing.

Install attribution#

Appy.addAttributionListener((attribution) => {
  analytics.setUserProperty('acquisition', attribution.isOrganic ? 'organic' : attribution.campaign ?? attribution.linkSlug);
});

const stored = await Appy.getAttribution();

The attribution listener is called once, when Appy answers the first launch, also after a deep link timeout. getAttribution() resolves to the stored value on later launches. An attribution has isOrganic, linkSlug, linkTitle, source, medium, campaign, clickedAt and network for installs that Google Ads or Meta attributed. Apple Ads needs no setup; for Meta, set android: { metaAppId: … } in configure. Check attribution.verified from your backend before granting rewards, as described in Verified installs.

Track events#

Appy.track('signup');
Appy.track('add_to_cart', { properties: { sku: 'A1', qty: 2 } });
Appy.track('purchase', { revenue: 19.98, currency: 'USD', deduplicationId: purchase.transactionId });

Property values are strings, finite numbers or booleans; other values are dropped. Pass the store’s transaction ID as deduplicationId and Appy counts the purchase once, also when your backend reports it with the same ID. The limits and the sending schedule are in Track events.

Users, privacy and consent#

Appy.setUserId('u_123');

if (!consent.hasAnswered) {
  Appy.setTrackingEnabled(false);
}
Appy.configure(configuration);

setUserId attaches an opaque user ID to later opens and events; pass null on sign-out. setTrackingEnabled(false) is stored across launches and stops the launch open, the deferred deep link lookup and events until you turn it back on, for example when the user consents. See Privacy and consent.

Build share links#

const url = await Appy.buildLink('spring', { ref: referralCode });

The result is https://acme.appy.to/spring?ref=… on the first link domain, or null before configure, without a link domain or for an invalid slug.

Test and debug#

xcrun simctl openurl booted "https://acme.appy.to/spring?item=42"
adb shell 'am start -W -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://acme.appy.to/spring?item=42"'

API reference#