[WIP] React Native SDK (v4) (Beta)

    NPM Version

    Attention

    This is a guide for installing and setting up the React Native SDK v4. For previous versions, refer to the React Native SDK (v1) guide.

    Install the Airbridge React Native SDK and implement the necessary settings following the steps below.

    Install SDK

    The Airbridge React Native SDK can be installed using the method below. After installation, you can verify whether the SDK has been properly installed through a React Native SDK Test.

    1. Install airbridge-react-native-sdk using npm.

    1
    npm install airbridge-react-native-sdk

    2. Install iOS dependencies using CocoaPods. (Android dependencies are installed automatically.)

    1
    cd ios; pod install

    Restricted SDK

    Attention

    Install only one version of the SDK, either the general SDK or the restricted SDK.

    Depending on policies and environments, restrictions on collecting device IDs like GAID and IDFA may be required. When installing the Restricted SDK version, the device IDs are not collected.

    Install the Restricted SDK using the method below.

    1. Install airbridge-react-native-sdk using npm.

    1
    npm install airbridge-react-native-sdk-restricted

    2. Install iOS dependencies using CocoaPods. (Android dependencies are installed automatically.)

    1
    cd ios; pod install

    Initialize SDK

    The initialization methods for iOS and Android SDKs are different. Refer to the information below.

    The YOUR_APP_NAME and YOUR_APP_SDK_TOKEN can be found on the [Settings]>[Tokens] page in the Airbridge dashboard.

    iOS

    Add the following code snippet to the ios/YOUR_PROJECT_NAME/AppDelegate.m file.

    123456
    import AirbridgeReactNative
    ...
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        AirbridgeReactNative.initializeSDK(name: "YOUR_APP_NAME", token:"YOUR_APP_SDK_TOKEN")
        ...
    }

    Android

    Add the following code snippet to the android/app/src/main/java/.../MainApplication.kt file.

    1234567
    import co.ab180.airbridge.reactnative.AirbridgeRN;
    ...
    override fun onCreate() {
        super.onCreate()
        AirbridgeReactNative.initializeSDK(this, "YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        ...
    }

    Configure SDK

    Enter the configuration values to use the Airbridge React Native SDK.

    123456789101112131415161718
    {
        "sdkEnabled": boolean,
        "logLevel": "debug" | "info" | "warning" | "error" | "fault",
        "autoStartTrackingEnabled": boolean,
        "autoDetermineTrackingAuthorizationTimeoutInSecond": number,
        "trackMetaDeferredAppLinkEnabled": boolean,
        "sessionTimeoutInSecond": number,
        "metaInstallReferrerAppID": string,
        "trackAirbridgeDeeplinkOnlyEnabled": boolean,
        "trackInSessionLifecycleEventEnabled": boolean,
        "hashUserInformationEnabled": boolean,
        "sdkSignatureID": string,
        "sdkSignatureSecret": string,
        "clearEventBufferOnInitializeEnabled": boolean,
        "eventBufferCountLimit": number,
        "eventBufferSizeLimitInGibibyte": number,
        "eventTransmitIntervalInSecond": number,
    }

    1. Create an airbridge.json file at the top level of the React Native project folder and input the JSON as above.

    2. Don't enter the key values for settings that are not needed.

    Refer to the guides listed below for the settings values.

    Configure ATT Prompt

    Note

    The functions necessary to ensure compliance with privacy policies should be reviewed with legal counsel.

    In the iOS environment, the IDFA can only be collected when users have allowed tracking of information through the AppTrackingTransparency (ATT) prompt.

    Event collection should be delayed until the user allows tracking. If the install event is collected before the user allows tracking on the ATT prompt, the install event data will lack an identifier, making performance measurement difficult. We recommend setting a sufficient delay time for event collection to collect identifiers.

    1. Prepare the text you will use in the ATT prompt.

    2. Provide the ATT prompt following this guide provided by Apple.

    3. If the install event is not collected, the Airbridge React Native SDK delays collecting install events for 30 seconds until the user allows tracking each time the app is launched. If the user exits the app before deciding whether to allow tracking, the SDK will not collect the install event and will try again at the next app launch.

    The autoDetermineTrackingAuthorizationTimeout function can be used to set a longer delay for collecting install events. The default setting for the autoDetermineTrackingAuthorizationTimeout is 300 seconds. It can be set up to 3600 seconds (1 hour).

    Attention

    Sufficient time must be configured to delay the collection of install events. If the delay time is up, the SDK will collect install events without identifiers before users can allow tracking on the ATT prompt.

    SDK Opt-in

    Attention

    The instructions below are optional. Proceed only if necessary.

    The Opt-in policy requires user consent before using user data.

    After setting the autoStartTrackingEnabled to false, call the startTracking function at the point of time when you can collect events. From the moment the startTracking function is called, the SDK will start collecting events.

    123
    import { Airbridge } from 'airbridge-react-native-sdk'
    ...
    Airbridge.startTracking()

    SDK Opt-out

    Attention

    The instructions below are optional. Proceed only if necessary.

    The opt-out policy allows the use of user information until the user explicitly declines.

    After setting the autoStartTrackingEnabled to true, call the stopTracking function at the point of time when you can no longer collect events. From the time the stopTracking function is called, the SDK will stop collecting events.

    123
    import { Airbridge } from 'airbridge-react-native-sdk'
    ...
    Airbridge.startTracking()

    Set up SDK Signature

    Attention

    The instructions below are optional. Proceed only if necessary.

    With the SDK Signature, you can ensure SDK spoofing prevention and use verified events for ad performance measurement.

    For the SDK Signature setup, the SDK Signature Credentials are required, which includes the Secret ID and the Secret. The required SDK Signature Credentials can be found in the Airbridge dashboard. For more details about the SDK Signature Credentials, refer to this Airbridge guide.

    1. Enter the sdkSignatureID listed in the Configure SDK section.

    2. Enter the sdkSignatureSecret listed in the Configure SDK section.

    The information required for the setup is as follows.

    • sdkSignatureID : Signature Secret ID. Navigate to [Management]>[Fraud Validation Rules]>[SDK Signature] in the Airbridge dashboard to find it.

    • sdkSignatureSecret : Signature Secret. Navigate to [Management]>[Fraud Validation Rules]>[SDK Signature] in the Airbridge dashboard to find it.

    Deep Linking

    By setting up a deep link, you can redirect users who click on ads with tracking links to specific pages of the desired app. Based on the information collected through the tracking link, you can also track the ad performance results in Airbridge.

    When Airbridge generates a tracking link, it automatically selects and utilizes the optimal Airbridge deep link, depending on the environment. This link will be used for user redirection, and it is called the scheme deep link.

    Example)

    • Airbridge Deep link: https://YOUR_APP_NAME.airbridge.io/~~~

    • Scheme Deep link: YOUR_SCHEME://product/12345

    When the app is installed on a device and the user clicks the tracking link, the app opens through the Airbridge deep link. The Airbridge SDK converts the Airbridge deep link into a scheme deep link set on the tracking link. The converted scheme deep link is sent to the app.

    When the app is not installed on a device and the user clicks the tracking link, the Airbridge deep link is saved. After the user moves to the app store or website and the app is installed and launched, the Airbridge SDK converts the saved Airbridge deep link into a scheme deep link. The converted scheme deep link is sent to the app.

    Set up deep linking

    For the deep link setup, the deep link information you entered into the Airbridge dashboard and the app page address to redirect users are required.

    First, enter the deep link information into the Airbridge dashboard.

    After entering the deep link information into the Airbridge dashboard, an additional setup is required to enable the following.

    • App launch with Airbridge deep links

    • Airbridge deep link event collection

    • User redirection with Airbridge deep links

    For detailed instructions, refer to the information below.

    Set up deferred deep linking

    When a user clicks on a tracking link with deferred deep linking capabilities and your app is not installed on the device, the Airbridge SDK retrieves the deep link as follows.

    Deferred deep links are automatically passed to OnDeeplinkReceived, so no additional setup is required.

    In-app Events

    The Airbridge SDK collects user actions from the app as per settings and sends them as in-app events.

    Send in-app events

    Setting up a Hybrid App

    In the hybrid app, you can set the React Native SDK to handle Airbridge related tasks occurring on the in-app website without changing the website code.

    Call the Airbridge.trackEvent function to send events. Refer to the information below about the required Airbridge.trackEventfunction components and their types.

    1234567891011121314
    static trackEvent(
        category: string,
    ): void
    
    static trackEvent(
        category: string,
        semanticAttributes: Record<string, any>,
    ): void
    
    static trackEvent(
        category: string,
        semanticAttributes: Record<string, any>,
        customAttributes: Record<string, any>,
    ): void

    Component

    Required or Optional

    Type

    Description

    category

    Required

    String

    Event name

    semanticAttributes

    Optional

    Record<string, any>

    Semantic attributes of the events

    customAttributes

    Optional

    Record<string, any>

    Custom attributes of the event

    Refer to the component definition and available strings below.

    The Event Category of Standard Events and Semantic Attributes provided by the SDK are as follows.

    Refer to the example codes for each data type below.

    123456789101112131415
    import { Airbridge, AirbridgeAttribute } from 'airbridge-react-native-sdk'
    ...
    Airbridge.trackEvent(
        'event',
        {
            [AirbridgeAttribute.VALUE]: 10,
        },
        {
            'string': 'string',
            'number': 1000,
            'boolean': true,
            'object': {'key': 'value'},
            'array': ['value'],
        },
    )

    Additional in-app event settings

    Attention

    The default settings will apply if no additional settings are configured. Proceed after reviewing whether additional settings are necessary.

    Configure additional settings for sending in-app events if necessary.

    Example codes

    Airbridge collects in-app events that are classified as Standard Events and Custom Events. Standard Events are events predefined by Airbridge. Refer to the example codes below.

    Custom Events are events defined by Airbridge users to track user actions that are unique to their services. Refer to the example code below.

    123456789101112131415
    import { Airbridge, AirbridgeAttribute } from 'airbridge-react-native-sdk'
    ...
    Airbridge.trackEvent(
        'event',
        {
            [AirbridgeAttribute.VALUE]: 10,
        },
        {
            'string': 'string',
            'number': 1000,
            'boolean': true,
            'object': {'key': 'value'},
            'array': ['value'],
        },
    )

    User Data

    Airbridge sends user data along with events. User data allows for a more accurate ad performance measurement.

    Set User IDs

    User IDs refer to the user identifier used in a service. User IDs should be unique IDs that can identify unique users across websites and apps.

    #{"width":"140px"}

    Function

    #{"width":"240px"}

    Description

    Airbridge.setUserID

    Inputs the user ID.

    Airbridge.clearUserID

    Deletes the user ID.

    Airbridge.setUserAlias

    Adds additional user identifiers. Up to 10 items can be added.
    - key: Up to 128 characters. Must follow the regular expression ^[a-zA-Z_][a-zA-Z0-9_]*$.
    - value: Up to 1024 characters.

    Airbridge.removeUserAlias

    Deletes only specified identifiers.

    Airbridge.clearUserAlias

    Deletes all additional user identifiers.

    Refer to the example below.

    123456789
    import { Airbridge } from 'airbridge-react-native-sdk'
    ...
    // identifier
    Airbridge.setUserID('string')
    Airbridge.clearUserID()
    // addtional identifier
    Airbridge.setUserAlias('string', 'string')
    Airbridge.removeUserAlias('string')
    Airbridge.clearUserAlias()

    Send additional user information

    Attention

    Sensitive user information may be included. Send after a thorough review with a legal advisor.

    Send additional user information by setting user attributes.

    #{"width":"140px"}

    Function

    #{"width":"240px"}

    Description

    Airbridge.setUserEmail

    Inputs user's email. The data is hashed using SHA256.

    Airbridge.clearUserEmail

    Deletes the user email.

    Airbridge.setUserPhone

    Inputs user's phone number. The data is hashed using SHA256.

    Airbridge.clearUserPhone

    Deletes the user's phone number.

    Airbridge.setUserAttribute

    Adds additional user attributes. Up to 100 items can be added.

    - key: Up to 128 characters. Must satisfy the regular expression: ^[a-zA-Z_][a-zA-Z0-9_]*$.

    - value: Only supports string, number, and Boolean types. Up to 1024 characters.

    Airbridge.removeUserAttribute

    Deletes only specified attributes from the additional attributes.

    Airbridge.clearUserAttributes

    Deletes all additional user attributes.

    Refer to the example below.

    123456789101112
    import { Airbridge } from 'airbridge-react-native-sdk'
    ...
    // email, phone
    Airbridge.setUserEmail('string')
    Airbridge.clearUserEmail()
    Airbridge.setUserPhone('string')
    Airbridge.clearUserPhone()
    // addtional attribute
    Airbridge.setUserAttribute('string', 'string')
    Airbridge.setUserAttribute('number', 1000)
    Airbridge.removeUserAttribute('string')
    Airbridge.clearUserAttributes()

    Hash user information

    When the Airbridge.setHashUserInformationEnabled function is set to false, user emails and phone numbers are transmitted without being hashed. The default setting is true.

    Clear user data

    You can reset user information with the Airbridge.clearUser function.

    123
    import { Airbridge } from 'airbridge-react-native-sdk'
    ...
    Airbridge.clearUser()

    Additional SDK settings

    Follow the instructions below for additional setup.

    Attention

    The instructions below are optional. Proceed only if necessary.

    Depending on how the link is opened, it may be difficult to properly use the tracking link of the app in-app.

    By using the Airbridge.click function or the Airbridge.impression function, you can properly use the tracking link without going through an external browser.

    Attention

    如果在 Airbridge iOS SDK 1.24.0 及以上版本的 App 中使用追踪链接,将记录 “深度链接页面浏览(Deeplink Pageview)” 目标事件(Target Event)。如果深度链接页面浏览频繁随后深度链接打开(Deeplink Open)发生,可能会影响深度链接打开的绩效。

    深度链接页面浏览的的默认归因窗口为 3 天。如果希望更改此归因窗口,请联系您的 CSM。

    Utilize attribution results

    Attention

    It takes some time for the Airbridge SDK to collect attribution results. We do not recommend using attribution results for functionalities requiring real-time processing.

    Use the setOnAttributionReceived function to get the attribution data of install events.

    12345
    import { Airbridge } from 'airbridge-react-native-sdk'
    ...
    Airbridge.setOnAttributionReceived((attribution) => {
        // when attribution is received
    })

    The value is delivered as follows, depending on the existence of attribution results.

    When a user clicks a push notification, the deep link information in the payload should be passed to the Airbridge SDK to enable the collection of deep link events. Use the Airbridge.trackDeeplink function.

    iOS

    Add the following code to the ios/YOUR_PROJECT_NAME/AppDelegate.m file.

    12345678910111213141516171819202122232425262728
    import Airbridge
    
    func application(
        _ application: UIApplication,
        didReceiveRemoteNotification userInfo: [AnyHashable : Any],
        fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
    ) {
        if UIApplication.shared.applicationState == .inactive {
            let url = // 푸시 알림 페이로드의 딥링크
    
            Airbridge.trackDeeplink(url)
        }
    }
    
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandlercompletionHandler: @escaping () -> Void
    ) {
        if 
            UIApplication.shared.applicationState == .inactive || UIApplication.shared.applicationState == .background,
            response.actionIdentifier == UNNotificationDefaultActionIdentifier
        {
            let url = // 푸시 알림 페이로드의 딥링크
    
            Airbridge.trackDeeplink(url)
        }
    }

    Android

    No setup is required as the events are automatically collected on Android.

    The Airbridge SDK collects all types of deep link events regardless of the service that created the deep link. If deep link events are excessively collected, you can set the setTrackAirbridgeDeeplinkOnlyEnabled function to true so that only Airbridge deep links are collected.

    Collect in-session lifecycle events

    SDK collects Open, Foreground events when a new session is started. It does not collect these events while the session is continued.

    By setting the trackInSessionLifecycleEventEnabled of Configure SDK to true, SDK collects Open, Foreground events while the session is continued.

    All collected foreground events are recorded as open events.

    Compliance with Google DMA

    To comply with the Digital Markets Act (DMA), you must pass User Response Information (User Consent) to Airbridge. For more information about the DMA and who it applies to, see the Airbridge guide.

    If you are in the European Economic Area (EEA), you must always pass User Consent information to Airbridge.

    1. Determine the user's region from which they launched your app. If the user launched the app from the EEA(eea=1), check to see if you already have user response information. If you have collected user response information, proceed to step 3.

    If the user launched the app from outside the EEA, you do not need to collect user response information.

    提示

    Airbridge 无法提供有关存储用户同意信息或实现同意弹窗的指导。请咨询法律顾问。

    2. If you don't have any user response information collected, collect user response information from prompts, etc. The information you need to collect in this step is adPersonalization, adUserData.

    3. Set the autoStartTrackingEnabled of Configure SDK to false.

    4. Initialize the Airbridge SDK and pass user response information to the Airbridge before collecting user information.

    注意

    • 必须为 eeaadPersonalizationadUserData 使用相同的名称。

    • 请根据同意情况正确输入 01

    12345678910
    import { Airbridge } from 'airbridge-react-native-sdk'
    ...
    // deliver informations to sdk using device alias
    // based on actual region
    Airbridge.setDeviceAlias('eea', '0' or '1')
    // based on actual user consent
    Airbridge.setDeviceAlias('adPersonalization', '0' or '1')
    Airbridge.setDeviceAlias('adUserData', '0' or '1')
    // start tracking explicitly
    Airbridge.startTracking()

    Attention

    If you have set up the Meta Deferred App Link, Facebook SDK's fetchDeferredAppLink function should not be used.

    You can use deferred deep linking in Meta ads in the following way. The Airbridge SDK collects the Meta deferred app links first above others. If there are no Meta deferred app links, Airbridge deferred deep links are collected.

    Meta does not support Meta deferred app links for SKAdNetwork campaigns.

    1. Install the Facebook SDK. See the Meta guide.

    2. Set the setTrackMetaDeferredAppLinkEnabled function in the Airbridge SDK to true.

    Initialize the Airbridge SDK in inactive mode

    Attention

    If the Airbridge SDK is not activated immediately after initialization, the Install, Open, Deep link events may not be collected.

    Initializing the Airbridge SDK activates all features. You can initialize the Airbridge SDK with all features deactivated by setting the setSDKEnabled function to false.

    You can also check the activation status of the Airbridge SDK in the following way and activate or deactivate all functions.

    12345
    import { Airbridge } from 'airbridge-react-native-sdk'
    ...
    Airbridge.isSDKEnabled()
    Airbridge.enableSDK()
    Airbridge.disableSDK()

    Set up Meta Install Referrer data collection

    Send the Meta App ID to the metaInstallReferrer during the SDK initialization stage.

    After the setup, you need to enter the decryption key into the Airbridge dashboard to view the decrypted Meta Install Referrer. Refer to the Airbridge guide for how to enter the decryption key.

    Set up uninstall tracking

    Airbridge sends a silent push every day between 3:00 PM and 4:00 PM (UTC) to users who performed an app event at least once in the last 6 months to check if the app has been deleted. You can check the uninstall event in the Airbridge reports and raw data export files.

    Refer to the article below for the detailed setup methods and explanations.

    Integrate with third-party solutions

    Additional SDK setup is required to integrate with some third-party solutions. It is recommended to complete the necessary setup for integrating with third-party solutions before collecting data with the Airbridge SDK.

    Refer to the articles listed below for integrating with third-party solutions.

    SDK log settings

    The Airbridge SDK logs are provided in different levels: Debug, Info, Warning, Error, and Fault, with the Debug level being the least critical log and Fault the most critical.

    The Airbridge SDK provides logs at Warning, Error, and Fault levels by default. By inputting a log level into the setLogLevel function, you can view logs from that level up to the Fault level.

    Was this page helpful?

    Have any questions or suggestions?