> ## 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. # Capacitor SDK > Complete guide for integrating Linkrunner in Capacitor apps ## Installation ### Step 1: Install the Package ```bash theme={null} # Using npm npm install capacitor-linkrunner # Using yarn yarn add capacitor-linkrunner ``` ### Step 2: Sync Native Projects ```bash theme={null} npx cap sync ``` ### Step 3: iOS Configuration If you're developing for iOS, follow these additional steps: 1. Install pods for the package: ```bash theme={null} cd ios/App && 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 4: 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 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](/sdk/android#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`: ```groovy theme={null} buildscript { dependencies { classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" } } ``` For example, with Kotlin version 1.9.22: ```groovy theme={null} buildscript { dependencies { classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22" } } ``` ## Initialization (Required) To initialize the Linkrunner SDK, add this code to your app's initialization: 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. ```typescript theme={null} 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(); ``` ## 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](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 ```typescript theme={null} 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); } }; ``` ## 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. ```typescript theme={null} import { App } from '@capacitor/app'; import linkrunner from 'capacitor-linkrunner'; // Init SDK first await linkrunner.init('your_project_token'); // Cold start — app was launched by a deeplink const launchUrl = await App.getLaunchUrl(); if (launchUrl?.url) { linkrunner.handleDeeplink(launchUrl.url); } // Warm start — app was in background, deeplink brought it to foreground App.addListener('appUrlOpen', ({ url }) => { linkrunner.handleDeeplink(url); }); ``` ## Getting Attribution Data To get attribution data and deeplink information for the current installation, use the `getAttributionData` function: ```typescript theme={null} 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: ```typescript theme={null} { 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: **`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. ```typescript theme={null} 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: ```typescript theme={null} 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`](#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: ```typescript theme={null} 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): ```typescript theme={null} 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`](#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: ```typescript theme={null} 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 ); }; ``` ### 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: ```typescript 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: ```typescript theme={null} 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)](https://capacitorjs.com/docs/guides/push-notifications-firebase) * [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. Project ID 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. Google Cloud Permission 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**. Uninstall Tracking Follow these instructions to integrate FCM with the Linkrunner SDK: 1. **Set up Push Notifications:** Set up push notifications in your Capacitor app. See the [Capacitor Push Notifications documentation](https://capacitorjs.com/docs/guides/push-notifications-firebase) for detailed instructions. 2. Configure your app to provide the device's push token to the Linkrunner SDK. ```typescript theme={null} 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 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. Uninstall Tracking Follow these instructions to integrate APNs with the Linkrunner SDK: 1. **Set up Push Notifications:** Set up push notifications in your Capacitor app if you haven't already. See the [Capacitor Push Notifications documentation](https://capacitorjs.com/docs/guides/push-notifications-firebase) for detailed instructions. 2. 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: ```typescript theme={null} 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` | 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 push 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).