Android SDK (v4)

    Maven metadata URL

    Note

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

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

    Install SDK

    The Airbridge Android SDK can be installed using the method below. After installation, you can verify whether the SDK has been properly installed through an Android SDK test.

    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.

    Initialize SDK

    Initializing the Airbridge Android SDK in the Android Application class is recommended.

    1. Create an Application class.

    12345678
    import android.app.Application
    
    class AndroidApplication: Application() {
    
        override fun onCreate() {
            super.onCreate()
        }
    }

    2. Set the generated Application in AndroidManifest.xml.

    AndroidManifest.xml
    123
     <application
            android:name=".AndroidApplication"
            ...>

    3. Get Airbridge from the Application class.

    1
    import co.ab180.airbridge.Airbridge

    4. Add the following code snippet to the Application class file registered in AndroidManifest.xml.

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

    12345678
    override fun onCreate() {
        super.onCreate()
        // YOUR_APP_NAME: input your app name
        // YOUR_APP_SDK_TOKEN: input your app token
        val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
            .build()
        Airbridge.initializeSDK(this, option)
    }

    Attention

    Make sure that the initalizeSDK function is called within the onCreate method of the Application class for proper functionality.

    5. Set the following permissions.

    Opt-in setup

    Attention

    Optional settings. Configure 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 where you can collect events. When the startTracking function is called, the SDK will start collecting events.
    1. Initialize SDK in the Application class. Prevent automatic event tracking after initialization through the autoStartTrackingEnabled.

    12345
    // Default Auto Start Tracking Enabled = true
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setAutoStartTrackingEnabled(false)
        .build()
    Airbridge.initializeSDK(this, option)

    2. Collect user responses to the collection and use of personal information. If the user agrees to the collection and use of personal information, start tracking events.

    1234
    // Set a variable like below
    if (properties.isGDPRAccepted) {
        Airbridge.startTracking()
    }

    Opt-out setup

    Attention

    Optional settings. Configure only if necessary.

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

    After setting the setAutoStartTrackingEnabled function to true, call the stopTracking function at the point where event data cannot be collected. From the moment the stopTracking function is called, the SDK will stop collecting events.

    123456
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setAutoStartTrackingEnabled(true)
        .build()
    Airbridge.initializeSDK(this, option)
    ...
    Airbridge.stopTracking()

    SDK Signature

    Attention

    Optional settings. Configure 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.

    You can set the SDK Signature by calling the setSDKSignature function above the SDK initialization code.

    1234
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setSDKSignature("YOUR_SDK_SIGNATURE_SECRET_ID", "YOUR_SDK_SIGNATURE_SECRET")
        .build()
    Airbridge.initializeSDK(this, option)

    The information required for the setup is as follows.

    • YOUR_APP_NAME: The name of your app on Airbridge. Navigate to [Settings]>[Tokens] in the Airbridge dashboard to find it.

    • YOUR_APP_SDK_TOKEN: Android SDK Token. Navigate to [Settings]>[Tokens] in the Airbridge dashboard to find it.

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

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

    Deep Linking

    Deep linking allows you to redirect users from ads to specific locations within your app. The data collected from the tracking link enables you to monitor the performance of the deep link in Airbridge.

    When a user clicks on the Airbridge tracking link, the scheme deep link embedded in the tracking link is converted into an Airbridge Deep Link, which can be either an HTTP deep link or a scheme deep link. This Airbridge Deep Link redirects the user to the desired app location. Then, the Airbridge SDK converts the Airbridge Deep Link back to the original scheme deep link embedded in the tracking link and passes it to the app.

    • Example scheme deep link embedded in the tracking link: YOUR_SCHEME://product/12345

    • Examples of Airbridge Deep Links

      • HTTP deep link format 1: https://YOUR_APP_NAME.airbridge.io/~~~

      • HTTP deep link format 2: https://YOUR_APP_NAME.abr.ge/~~~

      • Scheme deep link format: YOUR_SCHEME://product/12345?airbridge_referrer=~~~

    When the app is installed on the device and the tracking link is clicked, the app opens through the Airbridge Deep Link. The Airbridge SDK converts the Airbridge Deep Link into the scheme deep embedded in the tracking link and passes it to the app.

    When the app is not installed on the device and the tracking link is clicked, the Airbridge SDK saves the Airbridge Deep Link is saved. After the user is redirected to the app store or website and the app is installed and launched, the Airbridge SDK converts the saved Airbridge Deep Link into the scheme deep embedded in the tracking link and passes it to the app.

    Set up deep linking

    For the deep linking setup, the following information is required.

    • Deep link information submitted in the Airbridge dashboard

    • In-app location address for user redirection

    First, submit the deep link information to the Airbridge dashboard.

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

    • App launch with Airbridge Deep Links

    • 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 collects the deep link as follows.

    The Airbridge.handleDeferredDeeplink function retrieves the stored Airbridge deep link and converts it into a scheme deep link to pass it to the app. Users are redirected to the intended destination using the converted scheme deep link.

    1234
    val isHandled = Airbridge.handleDeferredDeeplink {
        // when app is opened with deferred deeplink
        // show proper content using url
    }

    The Airbridge.handleDeferredDeeplink function returns true if it has been called for the first time after the install and waits for the Airbridge Deep Link to be retrieved, converts it to a scheme deep link to pass it to onSuccess. You can use this scheme deep link to send users to the intended destination.

    If there is no stored Airbridge Deep Link, null is passed to onSuccess. If the SDK is not initialized or if the Airbridge.handleDeferredDeeplink function has not been called for the first time, false will be returned.

    The scheme deep link is usually a URL in the form of YOUR_SCHEME://... If you use services like Meta Deferred App Links, a different form of URL may be passed.

    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

    SDK setup for hybrid apps

    You can set up the Android SDK to handle Airbridge-related tasks within the in-app website without changing the website's code for your hybrid app.

    Use the trackEvent method to send events. Call Airbridge to use the trackEvent method.

    1
    import co.ab180.airbridge.Airbridge

    Call the AirbridgeCategory, AirbridgeAttribute to use the category names and attributes predefined by Airbridge.

    12
    import co.ab180.airbridge.common.AirbridgeCategory
    import co.ab180.airbridge.common.AirbridgeAttribute

    Refer to the information below about the required trackEvent function components and their types.

    12345
    fun trackEvent(
        category: String,
        semanticAttributes: Map<String, Any?>? = null,
        customAttributes: Map<String, Any?>? = null
    )

    Component

    Required or Optional

    Type

    Description

    category

    Required

    String

    Event name

    semanticAttributes

    Optional

    Map<String, Any?>

    Semantic Attributes of the event

    customAttributes

    Optional

    Map<String, Any?>

    Custom Attributes of the event

    Refer to the component definition and available strings below.

    The Standard Event Categories and Semantic Attributes provided by the SDK are as follows.

    Refer to the example codes for each data type below.

    12345678910111213
    Airbridge.trackEvent(
        "event",
        mapOf(
            AirbridgeAttribute.VALUE to 10,
        ),
        mapOf(
            "string" to "string",
            "number" to 1000,
            "boolean" to true,
            "object" to mapOf("key" to "value"),
            "array" to listOf("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.

    12345678910111213
    Airbridge.trackEvent(
        "event",
        mapOf(
            AirbridgeAttribute.VALUE to 10,
        ),
        mapOf(
            "string" to "string",
            "number" to 1000,
            "boolean" to true,
            "object" to ["key": "value"],
            "array" to ["value"],
        )
    )

    User Data

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

    Set up User ID

    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 user ID.

    Airbridge.clearUserID

    Deletes user ID.

    Airbridge.setUserAlias

    Adds additional 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 identifiers.

    Refer to the example below.

    1234567
    // ID
    Airbridge.setUserID("testID")
    
    // alias
    Airbridge.setUserAlias("ADD_YOUR_KEY", "value")
    Airbridge.removeUserAlias("DELETE_THIS_KEY")
    Airbridge.clearUserAlias()

    Send additional user information

    Attention

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

    Refer to the functions below to send additional user information.

    #{"width":"140px"}

    Function

    #{"width":"240px"}

    Description

    Airbridge.setUserEmail

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

    Airbridge.clearUserEmail

    Deletes user email.

    Airbridge.setUserPhone

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

    Airbridge.clearUserPhone

    Deletes user's phone number.

    Airbridge.setUserAttribute

    Adds additional user attributes. Up to 100 items can be entered.
    - key: Up to 128 characters. Must follow the regular expression ^[a-zA-Z_][a-zA-Z0-9_]*$.
    - value: Only string, number, and Boolean types are supported. 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.

    1234567891011121314
    // Automatically hashed on client side using SHA256
    // Can turn off hashing feature with special flag
    Airbridge.setUserEmail("testID@ab180.co")
    Airbridge.setUserPhone("821012341234")
    
    // attributes
    Airbridge.setUserAttribute("ADD_YOUR_KEY", 1)
    Airbridge.setUserAttribute("ADD_YOUR_KEY", 1L)
    Airbridge.setUserAttribute("ADD_YOUR_KEY", 1f)
    Airbridge.setUserAttribute("ADD_YOUR_KEY", 1.0)
    Airbridge.setUserAttribute("ADD_YOUR_KEY", "1")
    Airbridge.setUserAttribute("ADD_YOUR_KEY", true)
    Airbridge.removeUserAttribute("DELETE_THIS_KEY")
    Airbridge.clearUserAttributes()

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

    12345
    // Default User Info Hash Enabled = true
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setHashUserInformationEnabled(false)
        .build()
    Airbridge.initializeSDK(this, option)

    Clear user data

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

    1
    Airbridge.clearUser()

    Additional SDK Settings

    Refer to the information below for additional setup.

    Attention

    Optional settings. Configure only if necessary.

    Tracking links are links that are embedded to ads for data collection. When users click on the ad, the tracking link is used to pass the touchpoint data to Airbridge, allowing for ad attribution.

    Also, users who click on the ad with a tracking link can be redirected to a specific destination.

    Use the createTrackingLink function to create tracking links. Refer to the code examples and the parameter details below.

    123456789101112
    fun createTrackingLink(
        channel: String,
        option: Map<String, String>,
        onSuccess: OnSuccess<AirbridgeTrackingLink>
    )
    
    fun createTrackingLink(
        channel: String,
        option: Map<String, String>,
        onSuccess: OnSuccess<AirbridgeTrackingLink>,
        onFailure: OnFailure?
    )

    Name

    Required or Optional

    Type

    Description

    channel

    Required

    String

    The ad channel the tracking link is used

    option

    Required

    Map<String, String>

    Options for creating tracking links

    onSuccess

    Required

    OnSuccess<AirbridgeTrackingLink>

    Success callback

    onFailure

    Optional

    OnFailure

    Fail callback

    Use the option parameter in the createTrackingLink function to configure tracking link options.

    Use the onSuccess callback in the createTrackingLink function to pass the AirbridgeTrackingLink.

    1234
    data class AirbridgeTrackingLink(
        val shortURL: Uri,
        val qrcodeURL: Uri
    )

    이름

    Type

    Description

    shortURL

    Uri

    The short URL of the tracking link

    qrcodeURL

    Uri

    The QR code URL of the tracking link

    Refer to the example codes below.

    Depending on the method of opening the link, it may be challenging to properly use the tracking link within the app.

    By using the Airbridge.click function or the Airbridge.impression function, you can properly use the tracking link within the app without sending users to an external browser.

    Attention

    When you set up the Airbridge Android SDK v2.18.0 or later to use tracking links within apps, every time a tracking link is used within the app, Deeplink Pageviews are aggregated, which are Target Events. The deep link performance may be affected when Deeplink Pageviews occur frequently right after Deeplink Opens.

    The attribution window for Deeplink Pageviews is set to 3 days by default. If you want to change the attribution window for Deeplink Pageviews, contact your Airbridge CSM. If you don't have a designated CSM, contact the Airbridge Help Center.

    Get 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 AirbridgeOptionBuilder.setOnAttributionReceived to get the attribution data of install events.

    12345678
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
    	.setOnAttributionReceived(object : OnAttributionResultReceiveListener {
    		override fun onAttributionResultReceived(result: Map<String, String>) {
    			// Process attribution data
    		}
    	})
    	.build()
    Airbridge.initializeSDK(application, option)

    Depending on whether the attribution result exists or not, data is passed as follows.

    The Airbridge SDK collects deep link events when the app is opened through a deep link, even if the deep link is not an Airbridge Deep Link. Set the setTrackAirbridgeDeeplinkOnlyEnabled function to true to collect deep link events only if the app is opened through an Airbridge Deep Link and prevent unnecessary event collection.

    12345
    // Default Track Airbridge Link Only = false
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setTrackAirbridgeDeeplinkOnlyEnabled(true)
        .build()
    Airbridge.initializeSDK(application, option)

    Collect in-session lifecycle events

    The Airbridge SDK collects Open and Foreground events that initiate a new session. These events are not collected during an ongoing session.

    By setting the setTrackInSessionLifeCycleEventEnabled function to true, you can collect Open and Foreground events during ongoing sessions.

    All collected Foreground events are recorded as Open events.

    1234
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setTrackInSessionLifeCycleEventEnabled(true)
        .build()
    Airbridge.initializeSDK(application, option)

    Compliance with Google DMA

    To comply with the Digital Markets Act (DMA), the user consent data must be sent to Airbridge. For more information about the DMA and whether it applies to your service, refer to the Airbridge user guide.

    If you are in the European Economic Area (EEA), the user consent data must be sent to Airbridge at all times.

    1. Confirm whether the end user launched the app in the EEA. If the end user did launch the app in the EEA (eea=1), confirm whether the consent values have already been stored for the session. If consent values are stored, proceed to Step 3.

    If the user launched the app from outside the EEA, user consent data collection is not mandatory.

    Note

    Airbridge cannot provide guidance on storing the user consent data and implementing the prompts. For assistance, consult legal professionals.

    2. If no consent values are stored, collect user consent data using means such as a prompt. The adPersonalization and adUserData values should be collected in this step.

    3. After the SDK initialization, the user consent data must be passed to Airbridge before the user data collection.

    Attention

    Ensure to follow the instructions below.

    • Use the field names specified by Airbridge: eea, adPersonalization, adUserData

    • Input 0 or 1 following the consent data collected.

    123456789101112131415161718192021
    // MainApplication.kt
    override fun onCreate() {
        super.onCreate()
        // Initialize Airbridge SDK
        val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
            // Make Airbridge SDK explicitly start tracking
            .setAutoStartTrackingEnabled(false)
            .build()
        Airbridge.initializeSDK(application, option)
    
        // Set device alias into Airbridge SDK
        // 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")
        
        // Explicitly start tracking
        Airbridge.startTracking()
    }

    Attention

    Upon completing the SDK setup to use Meta deferred app links, Facebook SDK's fetchDeferredAppLink function should not be used.

    Follow the steps below to use deferred deep linking in Meta ads. 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.

    Note that Meta does not support Meta deferred app links for SKAdNetwork campaigns. For more details, refer to the Meta ads documentation.

    1. Add the following repository to the project/build.gradle file.

    123456789
    allprojects {
        ...
        repositories {
            ...
            mavenCentral()
            ...
        }
        ...
    }

    2. Add the following code to the dependencies block in the app/build.gradle file.

    12345
    dependencies {
        ...
        implementation 'com.facebook.android:facebook-android-sdk:latest.release'
        ...
    }

    3. Add the following string below to the app/res/values/string.xml file.

    12345
    ...
    <string name="facebook_app_id">FACEBOOK_APP_ID</string>
    <string name="facebook_client_token">FACEBOOK_CLIENT_TOKEN</string>
    ...
    

    4. Add the following <meta-data> to the <application> element in the AndroidManifest.xml file.

    12345678
    ...
    <application android:label="@string/app_name" ...> 
        ...
        <meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/>
        <meta-data android:name="com.facebook.sdk.ClientToken" android:value="@string/facebook_client_token"/>
        ...
    </application>
    ...

    5. Set the setTrackMetaDeferredAppLinkEnabled function to true to enable Meta deferred app links during the SDK initialization.

    12345
    // Default meta Deferred App Link Enabled = false
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setTrackMetaDeferredAppLinkEnabled(true)
        .build()
    Airbridge.initializeSDK(application, option)

    Initialize the Airbridge SDK with all functions disabled

    Attention

    If the SDK is not enabled immediately after the SDK initialization, the Install, Open, and Deeplink Openbvevents may not be collected.

    Upon initialization, all functions of the SDK are enabled by default. By setting the setSDKEnabled function to false, the SDK can be initialized with all functions disabled.

    1234
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setSdkEnabled(false)
        .build()
    Airbridge.initializeSDK(application, option)

    You can also check the activation status of the Airbridge SDK and enable or disable all functions, as in the following example.

    123456789
    // Checks whether the SDK is currently enabled.
    // @return Boolean
    Airbridge.isSDKEnabled()
    
    // Enables the SDK.
    Airbridge.enableSDK()
    
    // Disables the SDK.
    Airbridge.disableSDK()

    Set up Meta Install Referrer collection

    To collect the Meta Install Referrer, the Meta app ID should be passed to the setMetaInstallReferrer function during the SDK initialization.

    1234
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setMetaInstallReferrer("YOUR_FACEBOOK_APP_ID")
        .build()
    Airbridge.initializeSDK(application, option)

    Note that the decryption key must be submitted to the Airbridge dashboard to read the decrypted Meta Install Referrer. Refer to this user guide to learn 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 instructions.

    Integrate with third-party solutions

    An additional SDK setup is required to integrate with some third-party solutions. It is recommended that you complete this setup before collecting data with the Airbridge SDK.

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

    SDK logs

    The logs provided by the Airbridge SDK are categorized into Debug, Info, Warning, Error, and Fault levels. The Debug level is the least critical log, while the Fault level is the most critical log.

    By default, the Airbridge SDK provides logs at Warning, Error, and Fault levels. By configuring the setLogLevel function with a specific log level, the logs from that specified level up to the Fault level will be available.

    12345
    // Default log level = Log.INFO
    val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
        .setLogLevel(AirbridgeLogLevel.DEBUG)
        .build()
    Airbridge.initializeSDK(this, option)

    このページは役に立ちましたか?

    ご質問やご提案はありますか?