DOCSEARCHbyAlgolia
Submit Docs

AppsFlyer React Native Plugin

repository·master·Indexed 43 days ago

https://github.com/appsflyersdk/appsflyer-react-native-plugin

A React Native plugin providing a bridge to AppsFlyer mobile attribution and marketing analytics SDKs. Supports standard React Native (>=0.76.0 with New Architecture) and Expo environments. Key features include in-app event tracking (logEvent), deep linking (UDL and GCD), purchase measurement via Purchase Connector, and DMA compliance. Version 7.0.2 utilizes an RPC response format for consistent data retrieval across iOS and Android.

Tokens
46.5K
Snippets
121
Records
148
Agent score
54%

What's inside AppsFlyer

  1. Overview of appsflyer-react-native-plugin

    master

    The appsflyer-react-native-plugin provides a bridge to the AppsFlyer SDKs for React Native applications, enabling mobile attribution, in-app event tracking, deep linking, and purchase measurement.

    Compatibility Requirements

    • React Native: Requires version >=0.76.0 with the New Architecture (TurboModules) enabled.
    • Legacy Support: If your app is not yet on the New Architecture, you must use the 6.x version line of this plugin.
    • Android SDK: Built for af-android-sdk v7.0.1 via af-android-plugin-bridge v7.0.12.
    • iOS SDK: Built for AppsFlyer SDK v7.0.2 via AppsFlyerRPC v7.0.13.
    • iOS Minimum Deployment: Version 12.0 or higher (as of 6.15.1).

  2. Overview of AppsFlyer React Native APIs

    master

    The AppsFlyer React Native plugin provides a comprehensive set of APIs categorized by their platform availability and functionality. The core APIs include:

    • Initialization Flow: init, start, and enableDebug.
    • Event Logging: logEvent and logAdRevenue.
    • User Identity: setCustomerUserId, setUserEmail, setUserPhone, and others.
    • Deep Linking: setResolveDeepLinkURLs, registerDeepLinkListener, and handleOpenURL.
    • Platform Specifics: Dedicated APIs for Android and iOS to handle platform-specific attribution and data collection settings.
    • Conversion Data: Listeners for conversion data and session readiness.

  4. Automatic iOS AppDelegate integration via Expo Plugin

    master

    When running expo prebuild with the react-native-appsflyer plugin installed, the plugin automatically modifies your AppDelegate (supporting both Swift templates in Expo SDK 52+ and legacy Objective-C templates) to wire up deep linking and attribution.

    You do not need to manually add these calls unless the plugin logs a warning during expo prebuild indicating it could not match your AppDelegate template.

    The plugin injects the following via AppsFlyerAttribution.shared:

    • AppsFlyerAttribution.shared.handleLaunchOptions(launchOptions) in didFinishLaunchingWithOptions
    • AppsFlyerAttribution.shared.handleOpen(url, options:) in openURL
    • AppsFlyerAttribution.shared.continueUserActivity(userActivity, restorationHandler:) in continueUserActivity

    To verify the injection after running expo prebuild --clean, you can search your iOS directory:

    grep -n "AppsFlyerLib" ios/*/AppDelegate.swift

  5. Manage dependencies for the Purchase Connector

    master

    The Purchase Connector relies on platform-specific libraries for managing in-app purchases. The AppsFlyer SDK does not include these libraries automatically; you are responsible for including them in your project.

    You can include these libraries manually in your native code or use a third-party React Native plugin like react-native-iap. Failure to include these libraries may result in failures during in-app purchase attempts or purchase validation.

  6. How Unified Deep Linking (UDL) works

    master

    Unified Deep Linking (UDL) is the mechanism used to handle both Deferred Deep Linking (via a dedicated API) and Direct Deep Linking (triggered by the OS via Android App Links, iOS Universal Links, or URI schemes).

    When a deep link is triggered, the SDK invokes the registerDeepLinkListener listener with a deep link result object. This object contains the deep_link_value and associated parameters used to create a personalized user experience.

    Privacy Protection Note: For new users, the UDL method only returns parameters relevant to deferred deep linking: deep_link_value and deep_link_sub1 through deep_link_sub10. Attempting to access other parameters like media_source, campaign, or af_sub1-5 will return null for these users.

  7. Understand Deep Linking Types and Unified Deep Linking (UDL)

    master

    AppsFlyer supports two main deep linking behaviors:

    1. Deferred Deep Linking: Serves personalized content to new or former users immediately after they install the app.
    2. Direct Deep Linking: Serves personalized content to existing users who already have the app installed.

    Unified Deep Linking (UDL) is the recommended API that enables you to send both new and existing users to a specific in-app activity as soon as the app is opened.

  8. Configure Android Backup Rules for AppsFlyer

    master

    The AppsFlyer SDK includes built-in backup rules in its Android manifest to ensure accurate install/reinstall detection. You can control whether the plugin uses your app's existing rules or AppsFlyer's rules using the preferAppsFlyerBackupRules option in app.json.

    Behavior Modes

    • Default (false or omitted): Your app's android:dataExtractionRules and android:fullBackupContent attributes remain untouched. You maintain full control.
    • Opt-in (true): Your app's existing backup rules are removed, allowing AppsFlyer SDK's built-in rules to take precedence.

    When to use preferAppsFlyerBackupRules: true

    • If you want AppsFlyer SDK to handle backup rules automatically.
    • If you are experiencing issues with install/reinstall detection.
    • If you do not have specific custom backup requirements for your app.
    {
  "expo": {
    "plugins": [
      [
        "react-native-appsflyer",
        {
          "preferAppsFlyerBackupRules": true
        }
      ]
    ]
  }
}

  9. Use the new Listener API with register* and unregister* pairs

    master

    In 7.0.x, the closure-based listener pattern (e.g., onInstallConversionData) has been replaced by a registration pattern. You must now use registerConversionListener and registerDeepLinkListener with a single configuration object. To prevent memory leaks, use the corresponding unregister* methods to clean up listeners (e.g., in componentWillUnmount).

    Note: In the new API, onFailure callbacks receive a plain string message instead of a ConversionData object.

    // Before
AppsFlyer.onInstallConversionData(onSuccess);
AppsFlyer.onInstallConversionFailure(onFailure);
AppsFlyer.onDeepLink(onDeepLink);

// After — one callbacks object each
AppsFlyer.registerConversionListener({
  onConversionDataSuccess: onSuccess,
  onConversionDataFail: onFailure,
});
AppsFlyer.registerDeepLinkListener({ onDeepLinking: onDeepLink });

// Full teardown (e.g. componentWillUnmount)
AppsFlyer.unregisterConversionListener();
AppsFlyer.unregisterDeepLinkListener();

  11. Recommended Initialization Flow

    master

    When using version 7.0.0 or higher, the order of operations is critical for correct event tracking and listener registration. Follow this sequence:

    1. registerDeepLinkListener: This is the only exception to the 'after init' rule. You must register this before calling init() on both platforms.
    2. init(devKey, appId): Initializes the core SDK.
    3. enableDebug({ enabled: true }): Configures debug mode.
    4. registerConversionListener(...): Register conversion listeners synchronously before the init promise settles.
    5. registerSessionReadyListener(...): Use this callback to trigger the final step.
    6. start(): Explicitly call start() inside the registerSessionReadyListener callback to begin the SDK lifecycle.

  12. Configure Associated Domains on iOS

    master

    You must register your OneLink domain as an associated domain.

    For Expo Projects: Add the domain to your app.json under ios.associatedDomains.

    For Native iOS Projects:

    1. Open your project in Xcode.
    2. Navigate to the Signing & Capabilities tab.
    3. Add the Associated Domains capability.
    4. Add your OneLink domain using the applinks: prefix (e.g., applinks:your-onelink-domain.onelink.me).
    {
  "expo": {
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp",
      "associatedDomains": [
        "applinks:your-onelink-domain.onelink.me"
      ]
    }
  }
}