iOS SDK (v4)

    GitHub Tag

    Note

    This guide provides instructions for installing and setting up the iOS SDK v4. For earlier versions, consult the iOS SDK (Previous) guide.

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

    Install SDK

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

    1. Navigate to [File]>[Add Packages...] in Xcode.

    2. Enter the following address into the search bar and click Add Package.

    3. Click Add Package again.

    4. The Airbridge iOS SDK will be added to Package Dependencies.

    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. Navigate to [File]>[Add Packages...] in Xcode.

    2. Enter the following address into the search bar and click Add Package.

    3. Click Add Package again.

    4. The Airbridge iOS SDK will be added to Package Dependencies.

    Initialize SDK

    SDK initialization methods vary depending on the system architecture. For SceneDelegate Lifecycle or AppDelegate Lifecycle, refer to the method for AppDelegate. For SwiftUI Lifecycle, refer to the method for SwiftUI.

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

    Call the Airbridge.initializeSDK function at the very top of AppDelegate's application(_:didFinishLaunchingWithOptions:) function.

    123456789101112131415
    import UIKit
    import Airbridge
    
    @main
    class AppDelegate: UIResponder, UIApplicationDelegate {
        func application(
            _ application: UIApplication,
            didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
        ) -> Bool {
            let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
                .build()
            Airbridge.initializeSDK(option: option)
            return true
        }
    }

    Attention

    Make sure that the Airbridge.initalizeSDK function is called within the application(_:didFinishLaunchingWithOptions:) of the AppDelegate for proper functionality.

    Configure ATT Prompt

    Note

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

    The IDFA can only be collected if users consent to data tracking via the App Tracking Transparency (ATT) prompt.

    Event collection should be delayed until the user allows tracking. If the install event is collected before the user allows tracking through 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. Enter the prepared text in the NSUserTrackingUsageDescription key of the Info.plist file.

    1. Navigate to [YOUR_PROJECT]>[Info]>[Custom iOS Target Properties] in Xcode.

    2. Hover your mouse over the key items, click + that appears, and enter Privacy - Tracking Usage Description.

    3. Enter the text for the ATT prompt as value.

    3. Set the point of time for displaying the ATT prompt on the app.

    4. If the install event is not collected, the Airbridge iOS 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 sufficient delayThe default value is 300 seconds, and it can be set up to 3600 seconds (1 hour). for collecting install events. The default setting for the autoDetermineTrackingAuthorizationTimeout is 30 seconds. It can be set up to 3600 seconds (1 hour).

    1234567
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME",
                                        token: "YOUR_APP_SDK_TOKEN")
        .setAutoDetermineTrackingAuthorizationTimeout(second: 30)
        .build()
    Airbridge.initializeSDK(option: option)

    Attention

    Set a sufficient delay time to collect the app install event. If the SDK collects install events before users can allow tracking on the ATT prompt, the IDFA will not be collected along with the install events.

    Opt-in setup

    Attention

    Optional settings. Configure only if necessary.

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

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

    12345678
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setAutoStartTrackingEnabled(false)
        .build()
    Airbridge.initializeSDK(option: option)
    ...
    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 of time when you can no longer collect events. When the stopTracking function is called, the SDK will stop collecting events.

    12345678
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setAutoStartTrackingEnabled(true)
        .build()
    Airbridge.initializeSDK(option: option)
    ...
    Airbridge.stopTracking()

    SDK Signature

    Attention

    Optional settings. Configure only if necessary.

    With the SDK Signature, you can prevent SDK spoofing and use verified events to measure ad performance.

    The SDK Signature credentials, which are the Secret ID and the Secret, are required for the SDK Signature setup. They can be found on the [Management]>[Fraud Validation Rules]>[SDK Signature] page in the Airbridge dashboard. For more details on how to find the SDK Signature credentials, refer to this Airbridge guide.

    Once you have the credentials, call the setSDKSignature function above the SDK initialization code.

    123456789
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setSDKSignature(
            id: "YOUR_SDK_SIGNATURE_SECRET_ID",
            secret: "YOUR_SDK_SIGNATURE_SECRET"
        )
        .build()
    Airbridge.initializeSDK(option: option)

    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, enter the deep link information into the Airbridge dashboard.

    After entering the deep link information into the Airbridge dashboard, an additional app setup is required. Check the required setup process below, which varies by the app's system method.

    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.

    Use the Airbridge.handleDeferredDeeplink function to convert the saved Airbridge Deep Link into a scheme deep link after collection and pass it to the app. The converted scheme deep link should be used to send the user to the intended destination.

    1234567891011
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .build()
    Airbridge.initializeSDK(option: option)
    ...
    let isHandled = Airbridge.handleDeferredDeeplink() { url in
        if let url {
            // show proper content using url (YOUR_SCHEME://...)
        }
    }

    The Airbridge.handleDeferredDeeplink function returns true if the app is installed and called for the first time, waits for the Airbridge Deep Link collection, and 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, nil 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 passed is generally in the format of YOUR_SCHEME://... URL. If you use services like Meta Deferred App Links, it may be passed in a different format.

    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 app

    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.

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

    Component

    Required

    Type

    Description

    category

    Required

    String

    Event name

    semanticAttributes

    Optional

    [String: Any]

    Semantic attributes of events

    customAttributes

    Optional

    [String: Any]

    Custom attributes of events

    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
    ...
    Airbridge.trackEvent(
        category: "event",
        semanticAttributes: [
            AirbridgeAttribute.VALUE: 10,
        ],
        customAttributes: [
            "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
    ...
    Airbridge.trackEvent(
        category: "event",
        semanticAttributes: [
            AirbridgeAttribute.VALUE: 10,
        ],
        customAttributes: [
            "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
    ...
    // identifier
    Airbridge.setUserID("string")
    Airbridge.clearUserID()
    // addtional identifier
    Airbridge.setUserAlias(key: "string", value: "string")
    Airbridge.removeUserAlias(key: "string")
    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 the user email. It is hashed with 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
    ...
    // email, phone
    Airbridge.setUserEmail("string")
    Airbridge.clearUserEmail()
    Airbridge.setUserPhone("string")
    Airbridge.clearUserPhone()
    // addtional attribute
    Airbridge.setUserAttribute(key: "string", value: "string")
    Airbridge.setUserAttribute(key: "number", value: 1000)
    Airbridge.removeUserAttribute(key: "string")
    Airbridge.clearUserAttributes()

    When the Airbridge.setHashUserInformationEnabled function is set to false, the user's email and phone number are sent without hashing. The default setting is true.

    123456
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setHashUserInformationEnabled(false)
        .build()
    Airbridge.initializeSDK(option: option)

    Clear user data

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

    123
    import Airbridge
    ...
    Airbridge.clearUser()

    Additional SDK Settings

    Follow the instructions below for additional setup.

    Attention

    Optional settings. Configure only if necessary.

    Depending on how links are opened, 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 iOS SDK v1.24.0 or later to use tracking links within apps, every time a tracking link is used within the app, Deeplink Pageviews are aggregated as 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 dedicated 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 setOnAttributionReceived function to get the attribution data of install events.

    12345678
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setOnAttributionReceived({ attribution in
            // when attribution is received
        })
        .build()
    Airbridge.initializeSDK(option: option)

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

    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.

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

    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.

    123456
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setTrackAirbridgeDeeplinkOnlyEnabled(true)
        .build()
    Airbridge.initializeSDK(option: 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, the Open and Foreground events can be collected during ongoing sessions.

    All collected Foreground events are recorded as Open events.

    123456
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setTrackInSessionLifecycleEventEnabled(true)
        .build()
    Airbridge.initializeSDK(option: option)

    Collect events using Action extension

    Airbridge iOS SDK v.4.0.0 or later is required.

    The Airbridge SDK supports event collection using Action extension. You can collect events using the trackEvent function in an Action extension following the steps below.

    1. Add App Group.

    2. Navigate to [YOUR_PROJECT]>[Signing & Capabilities] in Xcode. Click + Capability and add App Groups. Enter a value in the following format in the App Groups field:

    • group.YOUR_DOMAIN.YOUR_DOMAIN.YOUR_PRODUCT.airbridge

    3. Add the SDK initialization code under the viewDidLoad function.

    123456789
    import Airbridge
    ...
    override func viewDidLoad() {
        super.viewDidLoad()
        let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
            .setAppGroup("group.YOUR_DOMAIN.YOUR_DOMAIN.YOUR_PRODUCT.airbridge")
            .build()
        Airbridge.initializeSDK(option: option)
    }

    Attention

    You must carefully decide on setAppGroup settings. You need to delete all information related to the existing Airbridge SDK to remove or change the setAppGroup settings. This may cause unexpected results, such as previously collected install events being collected again.

    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.

    1234567891011121314151617
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        // make sdk require start tracking explicitly
        .setAutoStartTrackingEnabled(false)
        .build()
    // initialize sdk
    Airbridge.initializeSDK(option: option)
    ...
    // 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

    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 before the Airbridge deferred deep links. If there are no Meta deferred app links, the Airbridge deferred deep links are collected.

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

    1. Refer to the Meta ads document and install the Facebook SDK.

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

    123456
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setTrackMetaDeferredAppLinkEnabled(true)
        .build()
    Airbridge.initializeSDK(option: 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.

    123456
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setSDKEnabled(false)
        .build()
    Airbridge.initializeSDK(option: option)

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

    12345
    import Airbridge
    ...
    Airbridge.isSDKEnabled
    Airbridge.enableSDK()
    Airbridge.disableSDK()

    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 entering a specific log level as the value for setLogLevel function, the logs from that specified level up to the Fault level will be available.

    123456
    import Airbridge
    ...
    let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
        .setLogLevel(.debug)
        .build()
    Airbridge.initializeSDK(option: option)

    How to view Airbridge SDK logs only

    Enter Subsystem: co.ab180.airbridge into the filter at the bottom right in Xcode to view only Airbridge SDK logs.

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

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