> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkrunner.io/llms.txt
> Use this file to discover all available pages before exploring further.
# React Native SDK
> Complete guide for integrating Linkrunner in React Native apps
## Installation
### Step 1: Install the Package
```bash theme={null}
# Using npm
npm install rn-linkrunner
# Using yarn
yarn add rn-linkrunner
```
### Step 2: iOS Configuration
If you're developing for iOS, follow these additional steps:
1. Install pods for the package:
```bash theme={null}
cd ios && pod install
```
2. Add the following code to your `info.plist` file:
```xml theme={null}
NSUserTrackingUsageDescription
This identifier will be used to deliver personalized ads and improve your app experience.
```
### Step 3: SKAdNetwork Configuration
To enable SKAdNetwork postback copies to be sent to Linkrunner, add the following keys to your `Info.plist` file:
```xml theme={null}
NSAdvertisingAttributionReportEndpoint
https://linkrunner-skan.com
AttributionCopyEndpoint
https://linkrunner-skan.com
```
For complete SKAdNetwork integration details, see the [SKAdNetwork Integration Guide](/features/skadnetwork-integration).
### 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](/sdk/android#backup-configuration).
### Step 5: Encrypted SharedPreferences (Android)
**SDK Version Requirement:** Starting from `rn-linkrunner` **v2.10.1**, the SDK automatically encrypts the credentials it stores in Android SharedPreferences (such as the install ID and other persisted SDK state). No additional configuration is required — upgrade to v2.10.1 or above to get this behavior by default.
On Android, values written by the SDK are encrypted at rest, with a hardware-protected key generated on the device and stored in the [Android Keystore](https://developer.android.com/training/articles/keystore). The key never leaves the device and is not bundled with the SDK.
If you are upgrading from an earlier version, the SDK will transparently migrate any existing plaintext entries to the encrypted store on the next read after the upgrade — no code changes are needed on your side.
### Expo Support
If you are using Expo, follow the above steps to install the required packages. After this, you will need to use development builds since the Linkrunner SDK relies on native libraries. Follow the [Expo Development Builds Documentation](https://docs.expo.dev/develop/development-builds/introduction/) to get started.
## Initialization (Required)
To initialize the Linkrunner SDK, add this code to your `App.tsx` component:
You can find your project token [here](https://dashboard.linkrunner.io/dashboard?s=members\&m=documentation).
Note: The initialization method doesn't return any value. To get attribution data and deeplink information, use the `getAttributionData` method.
```javascript theme={null}
import linkrunner from "rn-linkrunner";
// Inside your React component
useEffect(() => {
init();
}, []); // Empty dependency array ensures it runs only once
const init = async () => {
await linkrunner.init(
"YOUR_PROJECT_TOKEN",
"YOUR_SECRET_KEY", // Optional: Required for SDK signing
"YOUR_KEY_ID", // Optional: Required for SDK signing
false, // Optional: Set to true to disable IDFA collection for iOS devices (defaults to false)
true // Optional: Enable debug mode for development (defaults to false)
);
console.log("Linkrunner initialized");
};
```
## SDK Signing Parameters (Optional)
For enhanced security, the LinkRunner SDK requires the following signing parameters during initialization:
* **`secretKey`**: A unique secret key used for request signing and authentication
* **`keyId`**: A unique identifier for the key pair used in the signing process
You can find your project token, secret key, and key ID [here](https://dashboard.linkrunner.io/settings?s=sdk-signing).
## User Identification (Required)
Call the `signup` method as soon as the user is identified — whether through signup or login. This is the moment Linkrunner ties the install (and any future events) to a user identifier.
It is strongly recommended to use the integrated platform's identify function to set a persistent user\_id once it becomes available (typically after signup or login).
* [Mixpanel - ID Management & User Identification](https://docs.mixpanel.com/docs/tracking-methods/id-management/identifying-users-simplified)
* [PostHog - How User Identification Works](https://posthog.com/docs/product-analytics/identify#how-identify-works)
* [Amplitude - Identify Users Documentation](https://amplitude.com/docs/get-started/identify-users)
If the platform's identifier function is not called, you must provide a user identifier for Mixpanel, PostHog, and Amplitude integration.
* mixpanel\_distinct\_id for Mixpanel
* posthog\_distinct\_id for PostHog
* amplitude\_device\_id for Amplitude
```javascript theme={null}
const onSignup = async () => {
try {
await linkrunner.signup({
user_data: {
id: "123", // Required: User ID
name: "John Doe", // Optional
phone: "9876543210", // Optional
email: "user@example.com", // Optional
// These properties are used to track reinstalls
user_created_at: "2024-01-01T00:00:00Z", // Optional
is_first_time_user: true, // Optional
mixpanel_distinct_id: "mixpanel_distinct_id", // Optional - Mixpanel Distinct ID
amplitude_device_id: "amplitude_device_id", // Optional - Amplitude User ID
posthog_distinct_id: "posthog_distinct_id", // Optional - PostHog Distinct ID
},
data: {}, // Optional: Any additional data
});
console.log("Signup successful");
} catch (error) {
console.error("Error during signup:", error);
}
};
```
## Handle Deeplink
To enable [remarketing and reattribution](/features/remarketing), you need to capture deep links and pass them to the Linkrunner SDK. This allows Linkrunner to detect returning users who open the app via a deep link.
```javascript theme={null}
import { useEffect } from 'react';
import { Linking } from 'react-native';
import linkrunner from 'rn-linkrunner';
function App() {
useEffect(() => {
// Cold start — app was launched by a deeplink
Linking.getInitialURL().then((url) => {
if (url) {
linkrunner.handleDeeplink(url);
}
});
// Warm start — app was in background, deeplink brought it to foreground
const subscription = Linking.addEventListener('url', ({ url }) => {
linkrunner.handleDeeplink(url);
});
return () => subscription.remove();
}, []);
return (
// your app content
);
}
```
## Getting Attribution Data
To get attribution data and deeplink information for the current installation, use the `getAttributionData` function:
```javascript theme={null}
const getAttributionInfo = async () => {
try {
const attributionData = await linkrunner.getAttributionData();
console.log("Attribution data:", attributionData);
} catch (error) {
console.error("Error getting attribution data:", error);
}
};
```
The `getAttributionData` function returns:
```typescript theme={null}
{
deeplink: string | null;
campaign_data: {
id: string;
name: string;
type: string; // "ORGANIC" | "INORGANIC"
ad_network: string | null; // "META" | "GOOGLE" | null
installed_at: string;
store_click_at: string | null;
group_name: string;
asset_name: string;
asset_group_name: string;
}
attribution_source: string;
}
```
## Setting User Data
Call `setUserData` each time the app opens and the user is logged in:
**`setUserData` is optional and is not a replacement for `signup`.** Always call `signup` first as soon as the user is identified (signup or login). Use `setUserData` afterwards only when additional user details become available later — for example, when the user adds a phone number, email, or completes their profile after identification.
```javascript theme={null}
const setUserData = async () => {
await linkrunner.setUserData({
id: "123", // Required: User ID
name: "John Doe", // Optional
phone: "9876543210", // Optional
email: "user@example.com", // Optional
mixpanel_distinct_id: "mixpanel_distinct_id", // Optional - Mixpanel Distinct ID
amplitude_device_id: "amplitude_device_id", // Optional - Amplitude User ID
posthog_distinct_id: "posthog_distinct_id", // Optional - PostHog Distinct ID
});
};
```
## Setting CleverTap ID
Use the `setAdditionalData` method to set CleverTap ID:
```javascript theme={null}
const setIntegrationData = async () => {
await linkrunner.setAdditionalData({
clevertapId: "YOUR_CLEVERTAP_USER_ID", // CleverTap user identifier
});
};
```
### Parameters for `linkrunner.setAdditionalData`
* `clevertapId`: string (optional) - CleverTap user identifier
This method allows you to connect user identities across different analytics and marketing platforms.
## Revenue Tracking
Revenue data is only stored and displayed for attributed users. Make sure you have implemented the [`.signup`](#user-registration) function before capturing payments. To attribute a test user, follow the [Integration Testing](/testing/integration-testing) guide. You can verify your events are being captured on the [Events Settings](https://dashboard.linkrunner.io/dashboard/settings/events) page.
### Capture Payment
Use this method to capture payment information:
```js theme={null}
const capturePayment = async () => {
await linkrunner.capturePayment({
amount: 100, // Payment amount
userId: "user123", // User identifier
paymentId: "payment456", // Optional: Unique payment identifier
type: "FIRST_PAYMENT", // Optional: Payment type
// type: "SECOND_PAYMENT", // Optional: Payment type
status: "PAYMENT_COMPLETED", // Optional: Payment status
eventData: {
// Optional: Ecommerce/custom event data
content_ids: ["product_123"],
content_type: "product",
currency: "USD",
value: 99.99,
num_items: 1,
order_id: "order_12345",
contents: [
{
id: "product_123",
quantity: 1,
item_price: 99.99,
},
],
},
});
};
```
#### Parameters for `linkrunner.capturePayment`
* `amount`: number (required) - The payment amount
* `userId`: string (required) - Identifier for the user making the payment
* `paymentId`: string (optional) - Unique identifier for the payment
* `type`: string (optional) - Type of payment. Available options:
* `FIRST_PAYMENT` - First payment made by the user
* `SECOND_PAYMENT` - Second payment made by the user
* `WALLET_TOPUP` - Adding funds to a wallet
* `FUNDS_WITHDRAWAL` - Withdrawing funds
* `SUBSCRIPTION_CREATED` - New subscription created
* `SUBSCRIPTION_RENEWED` - Subscription renewal
* `ONE_TIME` - One-time payment
* `RECURRING` - Recurring payment
* `DEFAULT` - Default type (used if not specified)
* `status`: string (optional) - Status of the payment. Available options:
* `PAYMENT_INITIATED` - Payment has been initiated
* `PAYMENT_COMPLETED` - Payment completed successfully (default if not specified)
* `PAYMENT_FAILED` - Payment attempt failed
* `PAYMENT_CANCELLED` - Payment was cancelled
* `eventData`: object (optional) - Key-value pairs for additional event data, including Meta ecommerce properties.
### Removing Payments
Remove payment records (for refunds or cancellations):
```javascript theme={null}
const removePayment = async () => {
await linkrunner.removePayment({
userId: "user123", // User identifier
paymentId: "payment456", // Optional: Unique payment identifier
});
};
```
#### Parameters for `Linkrunner.removePayment`
* `userId`: String (required) - Identifier for the user whose payment is being removed
* `paymentId`: String (optional) - Unique identifier for the payment to be removed
Note: Either `paymentId` or `userId` must be provided when calling `removePayment`. If only `userId` is provided, all payments for that user will be removed.
## Ecommerce Events
> **Minimum SDK Version:** Ecommerce Event Manager requires `react-native-linkrunner` **v2.7.0** or above. Please ensure your SDK is updated before using this feature.
If you are tracking Ecommerce events to sync with Meta Catalog Sales, you must format your `eventData` to include Meta's required fields. **You also need to map your custom event to the standard commerce event in the Linkrunner Dashboard.**
For detailed explanations of the required fields like `content_ids`, `contents`, and `value`, refer to our [Meta Commerce Manager documentation](/ecommerce-manager/meta-commerce-manager#understanding-event_data).
### Add To Cart Example
Use the `trackEvent` method to send an `AddToCart` event:
```javascript theme={null}
const trackAddToCart = async () => {
try {
await linkrunner.trackEvent(
"add_to_cart", // Map this custom event to "AddToCart" in the Linkrunner Dashboard
{
content_ids: ["product_123"],
contents: [
{
id: "product_123", // Matches content_ids
quantity: 1,
item_price: 49.99,
},
],
content_type: "product",
currency: "USD",
value: 49.99,
num_items: 1,
},
);
console.log("Add To Cart event tracked successfully");
} catch (error) {
console.error("Error tracking Add To Cart event:", error);
}
};
```
### View Content Example
Use the `trackEvent` method to send a `ViewContent` event:
```javascript theme={null}
const trackViewContent = async () => {
try {
await linkrunner.trackEvent(
"view_item", // Map this custom event to "ViewContent" in the Linkrunner Dashboard
{
content_ids: ["product_123"],
contents: [
{
id: "product_123", // Matches content_ids
quantity: 1,
item_price: 49.99,
},
],
content_type: "product",
currency: "USD",
value: 49.99,
num_items: 1,
},
);
console.log("View Content event tracked successfully");
} catch (error) {
console.error("Error tracking View Content event:", error);
}
};
```
### Payment / Purchase Example
Use the `capturePayment` method to send a `Purchase` event containing the ecommerce payload:
```javascript theme={null}
const capturePurchase = async () => {
try {
await linkrunner.capturePayment({
amount: 49.99,
userId: "user123",
paymentId: "payment_456",
type: "FIRST_PAYMENT", // Map this payment type to "Purchase" in the Linkrunner Dashboard
status: "PAYMENT_COMPLETED",
eventData: {
content_ids: ["product_123"],
contents: [
{
id: "product_123", // Matches content_ids
quantity: 1,
item_price: 49.99,
},
],
content_type: "product",
currency: "USD",
value: 49.99,
num_items: 1,
order_id: "order_abc123", // Required for Purchase events
},
});
console.log("Purchase captured successfully");
} catch (error) {
console.error("Error capturing purchase:", error);
}
};
```
> **Note:** For more information on testing and verifying your ecommerce events, please see our [Testing Ecommerce Events](/ecommerce-manager/meta-commerce-manager#testing-ecommerce-events) guide.
## Tracking Custom Events
Events are only stored and displayed for attributed users. Make sure you have implemented the [`.signup`](#user-registration) function before tracking events. To attribute a test user, follow the [Integration Testing](/testing/integration-testing) guide. You can verify your events are being captured on the [Events Settings](https://dashboard.linkrunner.io/dashboard/settings/events) page. For capturing revenue, it is recommended to use the [`.capturePayment`](#revenue-tracking) method instead of `.trackEvent`.
Track custom events in your app:
```javascript theme={null}
const trackEvent = async () => {
await linkrunner.trackEvent(
"purchase_initiated", // Event name
{ product_id: "12345", category: "electronics", amount: 99.99 } // Optional: Event data, include amount as a number for revenue sharing with ad networks like Google and Meta
);
};
```
### Revenue Sharing with Ad Networks
To enable revenue sharing with ad networks like Google Ads and Meta, include an `amount` parameter as a number in your custom event data. This allows the ad networks to optimize campaigns based on the revenue value of conversions:
```javascript theme={null}
const trackPurchaseEvent = async () => {
await linkrunner.trackEvent("purchase_completed", {
product_id: "12345",
category: "electronics",
amount: 149.99, // Revenue amount as a number
});
};
```
For revenue sharing with ad networks to work properly, ensure the `amount` parameter is passed as a number, not as a
string.
## Enhanced Privacy Controls
The SDK offers options to enhance user privacy:
```javascript theme={null}
// Enable PII (Personally Identifiable Information) hashing
linkrunner.enablePIIHashing(true);
```
When PII hashing is enabled, sensitive user data like name, email, and phone number are hashed using SHA-256 before being sent to Linkrunner servers.
## Uninstall Tracking
### Before you begin
Here's what you need to know before getting started:
**Requirements:**
* React Native SDK 2.8.0 and later
* [Firebase in your React Native project (Android)](https://rnfirebase.io/)
* [Registering your app with APNs (iOS)](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns)
### Android
Connect Firebase Cloud Messaging (FCM) with Linkrunner
To configure FCM HTTP V1 for uninstalls:
**Enable the FCM API:**
1. Go to the [FCM console](https://console.firebase.google.com).
2. Select a project.
3. Go to **Project Overview** > **Project settings**.
4. Copy the Project ID. This will be required in a later step.
5. Go to the **Cloud Messaging** tab.
6. Make sure that Firebase Cloud Messaging API (V1) is set to Enabled.
**Create a custom role for Linkrunner Uninstall:**
1. Go to the **Service accounts** tab.
2. Click **Manage service account permissions**.
3. A new browser tab opens in Google Cloud Platform.
4. In the side menu, select **Roles**.
5. Click **+ Create role**.
6. Enter the following details:
* **Title**: Linkrunner Uninstalls
* **ID**: lr\_uninstalls
* **Role launch stage**: General availability
7. Click **+ Add permissions**.
8. In **Enter property name or value** field, enter `cloudmessaging.messages.create` and select it from the search results.
9. Check the **cloudmessaging.messages.create** option and click **Add**.
10. Click **Create**.
**Assign Linkrunner the FCM uninstall role:**
1. In the side menu, select **IAM**.
2. Open the **View by Principals** tab.
3. Click **Grant Access**.
4. In **Add Principals** -> **New principals** field, enter `lr-uninstalls-tracking@lr-uninstalls-tracking.iam.gserviceaccount.com`
5. In **Assign Roles** -> **Select a role** field, enter `Linkrunner Uninstalls` and select it from the search results.
6. Click **Save**.
The Linkrunner service account has been assigned the role of Linkrunner Uninstalls.
1. In Linkrunner, go to **Settings** > **Uninstall Tracking**.
2. Under the **Android** tab, enter the Firebase Project ID that you copied initially and click **Save**.
Follow these instructions to integrate FCM with the Linkrunner SDK:
1. **Set up Firebase Cloud Messaging:**
Set up Firebase Cloud Messaging in your React Native app. See the [React Native Firebase documentation](https://rnfirebase.io/messaging/usage) for detailed instructions.
2. Configure your app to provide the device's push token to the Linkrunner SDK.
```javascript theme={null}
import messaging from '@react-native-firebase/messaging';
import linkrunner from 'rn-linkrunner';
// Fetch FCM token and set in Linkrunner SDK
const initializePushToken = async () => {
const token = await messaging().getToken();
if (token) {
await linkrunner.setPushToken(token);
}
};
// Listen for token refresh
const setupTokenRefresh = () => {
messaging().onTokenRefresh(async (token) => {
await linkrunner.setPushToken(token);
});
};
// Handle incoming messages
const setupMessageListener = () => {
messaging().onMessage(async (remoteMessage) => {
if (remoteMessage.data && remoteMessage.data['lr-uninstall-tracking']) {
// Silent notification for uninstall tracking, ignore
return;
}
// Handle other messages here
});
};
```
Custom implementations of FCM's message handler can unintentionally make uninstall push notifications visible to users, disrupting the intended silent experience. To avoid this, ensure your logic checks if the message contains `lr-uninstall-tracking` and handles it accordingly, as shown in the code example above.
### iOS
Connect APNs with Linkrunner
Get the required credentials from the Apple Developer Portal:
**APNs Authentication Key (p8) and Key ID:**
* Go to the [Apple Developer Portal](https://developer.apple.com/account).
* Select **Identifiers** under **Certificates, IDs & Profiles**.
* Click on the app you want to track uninstalls for. Then, under **Capabilities**, search for **Push Notifications** and enable it.
* Under **Certificates, IDs & Profiles**, select **Keys** and click on plus (+) icon to create a key. Enable APNs when creating the key and download the key file (p8).
* The Key ID can be found in the **Keys** tab.
**Bundle ID and Team ID:**
* Under **Identifiers**, click on your app and you will see the Bundle ID and Team ID (App ID Prefix).
1. In Linkrunner, go to **Settings** > **Uninstall Tracking**.
2. Under the **iOS** tab, upload the APNs Authentication Key (p8) file and enter the Key ID, Bundle ID and Team ID (App ID Prefix) that you copied from the Apple Developer Portal.
Follow these instructions to integrate APNs with the Linkrunner SDK:
1. **Set up Firebase Cloud Messaging:**
Set up Firebase Cloud Messaging in your React Native app if you haven't already. See the [React Native Firebase documentation](https://rnfirebase.io/messaging/usage) for detailed instructions.
2. Configure your app to provide the device's APNs token to the Linkrunner SDK.
```javascript theme={null}
import messaging from '@react-native-firebase/messaging';
import linkrunner from 'rn-linkrunner';
import { Platform } from 'react-native';
const initializeAPNsToken = async () => {
if (Platform.OS === 'ios') {
const apnsToken = await messaging().getAPNSToken();
if (apnsToken) {
await linkrunner.setPushToken(apnsToken);
}
}
};
```
## Function Placement Guide
| Function | Where to Place | When to Call |
| ------------------------------- | ------------------------------------- | ---------------------------------------------- |
| `linkrunner.init` | App.tsx within useEffect | Once when app starts |
| `linkrunner.getAttributionData` | Attribution data handling flow | Whenever the attribution data is needed |
| `linkrunner.setAdditionalData` | Integration code | When third-party integration IDs are available |
| `linkrunner.signup` | Identification flow (signup or login) | Once when the user is identified |
| `linkrunner.setUserData` | Authentication logic | Every time app opens with logged-in user |
| `linkrunner.trackEvent` | Throughout app | When specific user actions occur |
| `linkrunner.capturePayment` | Payment processing | When user makes a payment |
| `linkrunner.removePayment` | Refund flow | When payment needs to be removed |
| `linkrunner.setPushToken` | Push notification setup | When FCM/APNs token is available |
| `linkrunner.handleDeeplink` | Deep link entry points | When app is opened via a deep link |
## Next Steps
Validate your setup end-to-end
Configure deep links for your app
## Support
If you encounter issues during integration, contact us at [support@linkrunner.io](mailto:support@linkrunner.io).