Expo SDK

Complete guide for integrating Linkrunner in Expo apps

Before you start

For

App developers

Time

About 1 hour

You need

• Your project token, from SDK Console in the Linkrunner dashboard
• An Expo SDK 52+ app on React Native 0.70+ and Node.js 18+
• A development build (EAS Build or npx expo prebuild), not Expo Go
• The React Native SDK guide, which has the code steps

Prefer to let your AI coding agent do this? Install the Linkrunner skill and Claude Code, Cursor, GitHub Copilot, or Windsurf will wire up the SDK and deep links for you:

npx @linkrunner/skills add expo

Then ask your agent to "integrate Linkrunner". See Linkrunner Agent Skills.

This guide will help you install, configure, and use the Linkrunner SDK in your Expo application.

Migrating from an older version? For instructions on upgrading from 1.x.x/2.x.x to version 3.x.x, see the Migration Guide below.

Requirements

• Expo SDK 52.0 or higher
• Node.js 18.0 or higher
• React Native 0.70 or higher

Installation

Step 1: Install Both Packages

Install both the React Native and Expo packages:

npm install rn-linkrunner

npx expo install expo-linkrunner

Step 2: Add Plugin to app.json

Important: You must add the expo-linkrunner plugin to your app.json plugins array:

{
    "expo": {
        "plugins": [
            [
                "expo-linkrunner",
                {
                    "userTrackingPermission": "This identifier will be used to deliver personalized ads.",
                    "debug": true
                }
            ]
        ]
    }
}

What the expo-linkrunner Plugin Does

When you add expo-linkrunner to your app.json plugins and run the Expo prebuild step, the config plugin automatically makes the following changes to your iOS project:

• Adds NSUserTrackingUsageDescription in your iOS Info.plist if not already present (skipped when disableIdfa is set).
• Adds the SKAdNetwork postback keys NSAdvertisingAttributionReportEndpoint and AttributionCopyEndpoint (both set to https://linkrunner-skan.com) in your iOS Info.plist if not already present, so Apple sends SKAN postback copies to Linkrunner.

These changes are required for IDFA (Identifier for Advertisers) tracking, Apple's App Tracking Transparency (ATT) compliance, and SKAN attribution. For complete SKAdNetwork integration details, see the SKAdNetwork Integration Guide.

Step 3: Prebuild Your Project

The expo-linkrunner package is a config plugin that automatically configures your Expo project for Linkrunner SDK integration. Once you've completed the installation and configuration steps above:

• For EAS Build: If your android and ios folders are in .gitignore (recommended), EAS Build will automatically run the prebuild step during the build process. No manual action required.

• For local development or custom development clients:

  npx expo prebuild

Step 4: Android Backup Configuration

For Android apps, the SDK provides backup rules to exclude Shared Preferences data from backup. This prevents the retention of the Linkrunner install ID during reinstallation, ensuring accurate detection of new installs and re-installs.

For detailed backup configuration instructions, please refer to the Android SDK Backup Configuration.

Google Integrated Conversion Measurement (Optional)

Integrated Conversion Measurement (ICM) recovers Google App Campaign installs on iOS that Google cannot attribute because there is no click identifier and no IDFA to match on. Google's On-Device Measurement (ODM) SDK turns the click context into an encrypted signal that never leaves the device, and Linkrunner sends it with the install. See Google ICM for how it works.

Set this up if you run Google App Campaigns for your iOS app. Requires rn-linkrunner 3.1.0 or later.

Google keeps ODM inactive for users in the European Economic Area, the United Kingdom, and Switzerland, so ICM recovers nothing for that traffic. Elsewhere, Google reports improved coverage for iOS 14+ users.

ICM also needs an iOS link ID configured in your Google Ads integration. Google has nowhere to send the conversion without one. See Prerequisites.

Add Google's On-Device Measurement SDK to the iOS build

Already using the Firebase iOS SDK 11.14.0 or later? The FirebaseAnalytics pod brings this SDK in for you. Skip this step.

rn-linkrunner does not bundle this SDK, so apps that skip ICM carry none of its weight. Expo generates the Podfile, so add the pod through expo-build-properties:

npx expo install expo-build-properties

{
    "expo": {
        "plugins": [
            [
                "expo-build-properties",
                {
                    "ios": {
                        "extraPods": [{ "name": "GoogleAdsOnDeviceConversion" }]
                    }
                }
            ]
        ]
    }
}

CocoaPods adds the -ObjC and -lc++ linker flags for you, so there are no Xcode Build Settings to change.

If you manage ios/ yourself instead of generating it, add pod 'GoogleAdsOnDeviceConversion' to ios/Podfile and run pod install.

Rebuild your development client

npx expo prebuild --clean

ICM needs native code, so it does not work in Expo Go. Build a development client or run an EAS build.

Report consent

Set the values with setConsent before you call init:

import linkrunner from "rn-linkrunner";

linkrunner.setConsent({
    isEEA: "granted",
    hasConsentForDataUsage: "granted",
    hasConsentForAdsPersonalization: "denied",
});

await linkrunner.init("YOUR_PROJECT_TOKEN");

See Google Integrated Conversion Measurement in the React Native guide for what each signal means and how to verify the setup. For users outside the EEA, the UK, and Switzerland, report isEEA as denied and leave the other two unset. See Send Consent.

SDK Usage

The expo-linkrunner plugin handles the native configuration automatically. All SDK methods and APIs are provided by the rn-linkrunner package, which is why you'll use the React Native documentation for implementation details.

Since expo-linkrunner is a config plugin that prepares your project, the actual SDK usage is identical to React Native. Please refer to the React Native SDK Guide for:

• Initializing the SDK
• User registration
• Handling deep links with handleDeeplink
• Getting attribution data
• Setting user data
• Tracking custom events
• Revenue tracking
• Ecommerce Events
• Enhanced privacy controls

Function Placement Guide

Expo uses the rn-linkrunner runtime. The function links below open the implementation details in the React Native guide.

Function	Requirement	Where to Place	When to Call
linkrunner.init	Required	App.tsx within useEffect	Once when app starts
linkrunner.signup	Required	Identification flow (signup or login)	Once when the user is identified
linkrunner.setCustomerUserId	Required	After init, when your user ID is available	As early as the user's ID is available
linkrunner.handleDeeplink	Required	Deep link entry points	When app is opened via a deep link
linkrunner.getAttributionData	Optional	Attribution data handling flow	Whenever the attribution data is needed
linkrunner.setAdditionalData	Optional	Integration code	When third-party integration IDs are available
linkrunner.setUserData	Optional	Profile update flow after signup	When additional user details become available
linkrunner.trackEvent	Optional	Throughout app, including ecommerce flows	When specific user actions occur, including AddToCart or ViewContent events
linkrunner.capturePayment	Optional	Payment processing, including ecommerce purchases	When user makes a payment, including Purchase events with ecommerce data
linkrunner.removePayment	Optional	Refund flow	When payment needs to be removed
linkrunner.setPushToken	Optional	Push notification setup	When FCM/APNs token is available
linkrunner.setConsent	Optional	App initialization or consent flow	Before init, and again when consent changes
linkrunner.enablePIIHashing	Optional	Privacy configuration	When enabling PII hashing
linkrunner.enableTCFConsentCollection	Optional	iOS consent configuration	On every launch before init, if you opt into TCF consent collection
linkrunner.getPackageVersion	Optional	Diagnostics	When you need the installed SDK package version

Migration Guide

If you are using expo-linkrunner with v1.x.x or v2.x.x then moving forward you'll need to migrate to a v3.x.x.

Architecture Changes

Starting with version 3.0.0, the Expo SDK has been redesigned to use a new architecture:

• Config Plugin Architecture: The SDK now uses an Expo config plugin for better integration with the Expo ecosystem
• React Native SDK: Business logic is now handled by the React Native SDK, ensuring consistency across platforms
• Improved Developer Experience: Simplified setup with automatic native configuration

Breaking Changes

• The package installation process has changed to require both React Native and Expo SDKs
• Plugin configuration is now required in app.json
• All SDK methods and APIs are now provided by the rn-linkrunner package

Migration Steps

1. Uninstall the old package:

   npx expo uninstall expo-linkrunner

2. Install the new version:

   Follow the Installation steps above to install both rn-linkrunner and expo-linkrunner.

3. Update your code to use rn-linkrunner:

   The expo-linkrunner package is now just a config plugin. All SDK methods and APIs are now provided by the rn-linkrunner package. You'll need to update your imports and usage accordingly.

   For detailed implementation instructions, see the SDK Usage section above.

Next Steps

Test Your Integration

Validate your setup end-to-end

Set Up Deep Linking

Configure deep links for your app

Support

If you encounter issues during integration, contact us at support@linkrunner.io.