Capacitor SDK

Installation

Step 1: Install the Package

# Using npm
npm install capacitor-linkrunner

# Using yarn
yarn add capacitor-linkrunner

Step 2: Sync Native Projects

npx cap sync

Step 3: iOS Configuration

If you’re developing for iOS, follow these additional steps:

Install pods for the package:

cd ios/App && pod install

Add the following code to your Info.plist file:

<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads and improve your app experience.</string>

Step 4: SKAdNetwork Configuration

To enable SKAdNetwork postback copies to be sent to Linkrunner, add the following keys to your Info.plist file:

<key>NSAdvertisingAttributionReportEndpoint</key>
<string>https://linkrunner-skan.com</string>
<key>AttributionCopyEndpoint</key>
<string>https://linkrunner-skan.com</string>

For complete SKAdNetwork integration details, see the SKAdNetwork Integration Guide.

Step 5: 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.

Step 6: Android Kotlin Configuration

The Capacitor Linkrunner SDK requires the Kotlin Gradle plugin. Add the following to your root build.gradle file under dependencies:

buildscript {
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

For example, with Kotlin version 1.9.22:

buildscript {
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22"
    }
}

Initialization

To initialize the Linkrunner SDK, add this code to your app’s initialization: You can find your project token here.

SDK Signing Parameters (Optional)

For enhanced security, the Linkrunner SDK accepts 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. Note: The initialization method doesn’t return any value. To get attribution data and deeplink information, use the getAttributionData method.

import linkrunner from "capacitor-linkrunner";

// Inside your app initialization
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");
};

// Call init when app starts
init();

User Registration

Call the signup method once after the user has completed your app’s onboarding process: 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).

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

import linkrunner from "capacitor-linkrunner";

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);
    }
};

Getting Attribution Data

To get attribution data and deeplink information for the current installation, use the getAttributionData function:

import linkrunner from "capacitor-linkrunner";

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:

{
    deeplink: string | null;
    campaignData: {
        id: string;
        name: string;
        type: string; // "ORGANIC" | "INORGANIC"
        adNetwork: string | null; // "META" | "GOOGLE" | null
        installedAt: string;
        storeClickAt: string | null;
        groupName: string;
        assetName: string;
        assetGroupName: string;
    }
}

Setting User Data

Call setUserData each time the app opens and the user is logged in:

import linkrunner from "capacitor-linkrunner";

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:

import linkrunner from "capacitor-linkrunner";

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 function before capturing payments. To attribute a test user, follow the Integration Testing guide. You can verify your events are being captured on the Events Settings page.

Capture Payment

Use this method to capture payment information:

import linkrunner from "capacitor-linkrunner";

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
    });
};

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
- 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

Removing Payments

Remove payment records (for refunds or cancellations):

import linkrunner from "capacitor-linkrunner";

const removePayment = async () => {
    await linkrunner.removePayment({
        userId: "user123", // User identifier
        paymentId: "payment456", // Optional: Unique payment identifier
    });
};

Parameters for `linkrunner.removePayment`

userId: string (optional) - Identifier for the user whose payment is being removed. If only userId is provided, all payments for that user will be removed.
paymentId: string (optional) - Unique identifier for the payment to be removed

Note: At least one of paymentId or userId must be provided when calling removePayment.

Tracking Custom Events

Events are only stored and displayed for attributed users. Make sure you have implemented the .signup function before tracking events. To attribute a test user, follow the Integration Testing guide. You can verify your events are being captured on the Events Settings page. For capturing revenue, it is recommended to use the .capturePayment method instead of .trackEvent.

Track custom events in your app:

import linkrunner from "capacitor-linkrunner";

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
    );
};

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:

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:

import linkrunner from "capacitor-linkrunner";

// 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:

Capacitor SDK 1.0.1 and later
Firebase in your Capacitor project (Android)
Registering your app with APNs (iOS)

Android

Connect Firebase Cloud Messaging (FCM) with Linkrunner

FCM HTTP v1 API

To configure FCM HTTP V1 for uninstalls:Enable the FCM API:

Go to the FCM console.
Select a project.
Go to Project Overview > Project settings.
Copy the Project ID. This will be required in a later step.
Go to the Cloud Messaging tab.
Make sure that Firebase Cloud Messaging API (V1) is set to Enabled.

Create a custom role for Linkrunner Uninstall:

Go to the Service accounts tab.
Click Manage service account permissions.
A new browser tab opens in Google Cloud Platform.
In the side menu, select Roles.
Click + Create role.
Enter the following details:
- Title: Linkrunner Uninstalls
- ID: lr_uninstalls
- Role launch stage: General availability
Click + Add permissions.
In Enter property name or value field, enter cloudmessaging.messages.create and select it from the search results.
Check the cloudmessaging.messages.create option and click Add.
Click Create.

Assign Linkrunner the FCM uninstall role:

In the side menu, select IAM.
Open the View by Principals tab.
Click Grant Access.
In Add Principals -> New principals field, enter lr-uninstalls-tracking@lr-uninstalls-tracking.iam.gserviceaccount.com
In Assign Roles -> Select a role field, enter Linkrunner Uninstalls and select it from the search results.
Click Save.

The Linkrunner service account has been assigned the role of Linkrunner Uninstalls.

Linkrunner Dashboard

In Linkrunner, go to Settings > Uninstall Tracking.
Under the Android tab, enter the Firebase Project ID that you copied initially and click Save.

Integrate with Linkrunner SDK

Follow these instructions to integrate FCM with the Linkrunner SDK:

Set up Push Notifications:

Set up push notifications in your Capacitor app. See the Capacitor Push Notifications documentation for detailed instructions.

Configure your app to provide the device’s push token to the Linkrunner SDK.

import { PushNotifications } from '@capacitor/push-notifications';
import linkrunner from 'capacitor-linkrunner';

// Request permission and get token
const initializePushNotifications = async () => {
    const permStatus = await PushNotifications.requestPermissions();
    
    if (permStatus.receive === 'granted') {
        await PushNotifications.register();
    }
};

// Listen for registration
PushNotifications.addListener('registration', async (token) => {
    await linkrunner.setPushToken(token.value);
});

// Handle incoming push notifications
PushNotifications.addListener('pushNotificationReceived', (notification) => {
    if (notification.data && notification.data['lr-uninstall-tracking']) {
        // Silent notification for uninstall tracking, ignore
        return;
    }
    // Handle other notifications here
});

Custom implementations of push notification handlers can unintentionally make uninstall push notifications visible to users, disrupting the intended silent experience. To avoid this, ensure your logic checks if the notification contains lr-uninstall-tracking and handles it accordingly, as shown in the code example above.

iOS

Connect APNs with Linkrunner

Apple Developer Portal

Get the required credentials from the Apple Developer Portal:APNs Authentication Key (p8) and Key ID:

Go to the Apple Developer Portal.
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).

Linkrunner Dashboard

In Linkrunner, go to Settings > Uninstall Tracking.
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.

Integrate with Linkrunner SDK

Follow these instructions to integrate APNs with the Linkrunner SDK:

Set up Push Notifications:

Set up push notifications in your Capacitor app if you haven’t already. See the Capacitor Push Notifications documentation for detailed instructions.

Configure your app to provide the device’s APNs token to the Linkrunner SDK.

For iOS, the token received from the registration event is the APNs token when running on iOS devices:

import { PushNotifications } from '@capacitor/push-notifications';
import { Capacitor } from '@capacitor/core';
import linkrunner from 'capacitor-linkrunner';

// Listen for registration - on iOS this provides the APNs token
PushNotifications.addListener('registration', async (token) => {
    if (Capacitor.getPlatform() === 'ios') {
        await linkrunner.setPushToken(token.value);
    }
});

Function Placement Guide

Function	Where to Place	When to Call
`linkrunner.init`	App initialization	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`	Onboarding flow	Once after user completes onboarding
`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 push token is available

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.

Getting Started

SDK Guides

Core Features

Ad Networks

Analytics Integrations

Ecommerce Manager

API Reference

Billing

FAQ

Installation

Step 1: Install the Package

Step 2: Sync Native Projects

Step 3: iOS Configuration

Step 4: SKAdNetwork Configuration

Step 5: Android Backup Configuration

Step 6: Android Kotlin Configuration

Initialization

SDK Signing Parameters (Optional)

User Registration

Getting Attribution Data

Setting User Data

Setting CleverTap ID

Parameters for `linkrunner.setAdditionalData`

Revenue Tracking

Capture Payment

Parameters for `linkrunner.capturePayment`

Removing Payments

Parameters for `linkrunner.removePayment`

Tracking Custom Events

Enhanced Privacy Controls

Uninstall Tracking

Before you begin

Android

iOS

Function Placement Guide

Next Steps

Test Your Integration

Set Up Deep Linking

Support

Getting Started

SDK Guides

Core Features

Ad Networks

Analytics Integrations

Ecommerce Manager

API Reference

Billing

FAQ

​Installation

​Step 1: Install the Package

​Step 2: Sync Native Projects

​Step 3: iOS Configuration

​Step 4: SKAdNetwork Configuration

​Step 5: Android Backup Configuration

​Step 6: Android Kotlin Configuration

​Initialization

​SDK Signing Parameters (Optional)

​User Registration

​Getting Attribution Data

​Setting User Data

​Setting CleverTap ID

​Parameters for linkrunner.setAdditionalData

​Revenue Tracking

​Capture Payment

​Parameters for linkrunner.capturePayment

​Removing Payments

​Parameters for linkrunner.removePayment

​Tracking Custom Events

​Revenue Sharing with Ad Networks

​Enhanced Privacy Controls

​Uninstall Tracking

​Before you begin

​Android

​iOS

​Function Placement Guide

​Next Steps

Test Your Integration

Set Up Deep Linking

​Support

Installation

Step 1: Install the Package

Step 2: Sync Native Projects

Step 3: iOS Configuration

Step 4: SKAdNetwork Configuration

Step 5: Android Backup Configuration

Step 6: Android Kotlin Configuration

Initialization

SDK Signing Parameters (Optional)

User Registration

Getting Attribution Data

Setting User Data

Setting CleverTap ID

Parameters for `linkrunner.setAdditionalData`

Revenue Tracking

Capture Payment

Parameters for `linkrunner.capturePayment`

Removing Payments

Parameters for `linkrunner.removePayment`

Tracking Custom Events

Revenue Sharing with Ad Networks

Enhanced Privacy Controls

Uninstall Tracking

Before you begin

Android

iOS

Function Placement Guide

Next Steps

Support