iOS SDK (v4)

GitHub Tag

Note

This is a guide for installing and setting up the iOS SDK v4. For previous versions, refer to the iOS SDK (v1) 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 an 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

Initializing the SDK differs with varying system methods, such as the SceneDelegate Lifecycle, AppDelegate Lifecycle, or SwiftUI Lifecycle.

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

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. 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 time for displaying the ATT prompt.

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

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

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 setAutoStartTrackingEnabled function to false, call the startTracking function at the point of time when you can collect events. From the time the startTracking function is called, events are collected.

12345678
import Airbridge
...
let option = AirbridgeOptionBuilder(name: "YOUR_APP_NAME", token: "YOUR_APP_SDK_TOKEN")
    .setAutoStartTrackingEnabled(false)
    .build()
Airbridge.initializeSDK(option: option)
...
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 setAutoStartTrackingEnabled function 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.

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

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.

You can set the SDK Signature by calling 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)

The following information is required to configure the SDK.

  • YOUR_APP_NAME: This is the Airbridge app name, which can be found at [Settings]>[Tokens] in the Airbridge Dashboard.

  • YOUR_APP_SDK_TOKEN: This is the Android SDK token, which can be found at [Settings]>[Tokens] in the Airbridge Dashboard.

  • YOUR_SDK_SIGNATURE_SECRET_ID: This is the Secret ID, which can be found at [Management]>[Fraud Validation Rules]>[SDK Signature] in the Airbridge Dashboard.

  • YOUR_SDK_SIGNATURE_SECRET: This is the Secret, which can be found at [Management]>[Fraud Validation Rules]>[SDK Signature] in the Airbridge Dashboard.

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

Use the Airbridge.handleDeferredDeeplink function to converts the stored Airbridge deep link into a scheme deep link after acquisition and delivers it to the app. The converted scheme deep link is 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 acquisition, and converts it to a scheme deep link to pass it to onSuccess. You can use this scheme deeplink to send users to the set destination.

If there is no stored Airbridge deep link, it will deliver nil to onSuccess. If the SDK is not initialized or if the Airbridge.handleDeferredDeeplink function has not been called for the first time, it will return false.

The scheme deep link delivered is generally in the format of YOUR_SCHEME://... URL. If you use services like Meta Deferred App Links, it may be delivers 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

Setting up a Hybrid App

In the hybrid app, you can set the iOS 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.

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 Code

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.

Send additional user information by setting user attributes.

#{"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

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

When you set up Airbridge SDK to use tracking links within apps, every time a tracking link is used in 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 default attribution window settings for Deeplink Pageviews is 3 days. If you want to change the attribution window for Deeplink Pageviews, contact the Airbridge CSM. If you don't have a designated CSM, click here to contact us.

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.

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 transmitted 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 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.

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

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 function setTrackInSessionLifecycleEventEnabled to true, SDK collects Open, Foreground events while the session is continued.

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 in Action Extensions

Airbridge iOS SDK 4.0.0 or higher is required.

Airbridge SDK supports event collection in Action Extension. You can collect events with the trackEvent function in Action Extension as follows:

1. Add App Group.

2. Navigate to [YOUR_PROJECT]>[Signing & Capabilities] in Xcode. Click on + Capability and add App Groups. Enter the following values in App Groups.

  • group.YOUR_DOMAIN.YOUR_DOMAIN.YOUR_PRODUCT.airbridge

group.YOUR_DOMAIN.YOUR_DOMAIN.YOUR_PRODUCT.airbridge is not a fixed value. You can use the value that you want.

3. Initialize the SDK in the viewDidLoad function of the App Extension.

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 installation events being collected again.

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.

Note

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

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. Initialise the Airbridge SDK and pass user response information to the Airbridge before collecting user information.

Attention

Pay attention to the following.

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

  • Fill in 0 or 1 in accordance with 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

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

You can provide deferred deeplink in Meta Ads in the following way. The Airbridge SDK collects meta-deferred app links first. If there are no meta-deferred app links, it collects Airbridge deferred deep links.

SKAdNetwork campaigns in Meta Ads do not support meta deferred app links.

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

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 in Deactivation 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 enables all features. You can initialize the Airbridge SDK with all features disabled by setting the setSDKEnabled function to false.

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

Or you can check the activation status of the Airbridge SDK in the following way, and you can activate or deactivate all functions.

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

Set Up Uninstall Event Tracking

Airbridge sends a silent push every day between 0:00 and 1:00 KST (Korea Standard Time) to users who have tracked an app event at least once in the last 6 months to check if the app has been deleted. You can check the app deletion event through Airbridge reports and raw data extraction.

Refer to the Airbridge guide for detailed setup methods and explanations.

Integrate with Third-party Solutions

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

Refer to the guide below for the settings required for each third-party solution integration.

SDK Log Setting

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

By default, the Airbridge SDK provides logs at the Warning, Error, and Fault level. If you input a log level into the setLogLevel function, you can check logs from that log level to the Fault level.

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

Checking Airbridge SDK logs only

You can only see the Airbridge SDK log by entering Subsystem: co.ab180.airbridge in the filter at the bottom right of Xcode.

Was this page helpful?

Have any questions or suggestions?