• Developer Guide
  • SDK Integration
  • iOS SDK

iOS SDK

GitHub Tag

Install SDK

Attention

Due to known issues in the Airbridge SDK versions earlier than v1.35.1, we advise installing the Airbridge SDK v.1.35.1 or later.

Install package

Install using CocoaPods

  1. Create a Podfile file with the below commands.

    12
    cd path/to/project
    touch Podfile

  2. Edit the Podfile as below.

    Podfile
    123
    target '[Project Name]' do
        pod 'AirBridge', '1.40.0'
    end

    To install the Airbridge iOS SDK version 1.18.0 or later, CocoaPods version 1.11.0 or later is required.

  3. Run the following commands in your terminal.

    12
    cd path/to/project
    pod install --repo-update

    When no pod command is found, install cocoapods with the below command.

    • sudo gem install cocoapods

Install using Swift Package Manager (SPM)

The Airbridge iOS SDK v1.23.0 and later versions can be installed using the SPM.

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

  2. Search for "https://github.com/ab180/airbridge-ios-sdk-deploy" in the "Add Packages" window. Select the version you want to install and click Add Package.

  3. Select Target and click Add Package.

  4. AirBridge will show under "Package Dependencies" if the SDK is properly installed.

Install manually

Add the AirBridge.xcframework

  1. Download the AirBridge.xcframework.

  2. Navigate to [Xcode]>[Project file]>[General]>[Frameworks, Libraries, and Embedded Content] and click +.

  3. Click Add Other.. → Add Files.. at the bottom right.

  4. Add the AirBridge.xcframework folder in the file downloaded in Step 1.

  5. Set AirBridge.xcframework to "Embed & Sign."

Add Dependency Frameworks

  1. Click [Xcode]>[Project file]>[General]>[Frameworks, Libraries, and Embedded Content] and click +.

  2. Add the frameworks in the table below.

  3. Set the frameworks as "Do not Embed."

  4. Go to [Xcode]>[Project file]>[Build Phase]>[Link Binary with Libraries].

  5. Set the status of the framework below to Optional.

Framework

Description

AdSupport.framework

Used to collect IDFA.

CoreTelephony.framework

Used to collect the carrier information.

StoreKit.framework

Used to collect the SKAdNetwork information.

AppTrackingTransparency.framework

Used to collect the user's consent status.

AdServices.framework

Used to collect Apple Search Ads attribution information. (iOS 14.3+)

Set up project

Initialize SDK

Initialize the SDK by adding the following code at the beginning of the application:didFinishLaunchingWithOptions: method in the AppDelegate file.

123456
#import <AirBridge/AirBridge.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
    [AirBridge getInstance:@"YOUR_APP_SDK_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];
    ...
}

If you're using SwiftUI where AppDelegate doesn't exist, initialize the SDK through the App class with @main.

1234567891011121314151617
// YourprojectApp.swift

import SwiftUI
import AirBridge

@main
struct OnlyUIApp: App {
    init() {
        AirBridge.getInstance("YOUR_APP_SDK_TOKEN", appName: "YOUR_APP_NAME")
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

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

Accept IDFA Terms and Conditions

To use the SDK, you must agree to the "IDFA terms and conditions" when publishing your app to the App Store. Refer to the table below to fill out the form.

Question and Checkboxes

Action

Does this app use the Advertising Identifier (IDFA)?

Yes

Serve advertisements within the app

Don't check

Attribute this app Install to a previously served advertisement

Check

Attribute an action taken within this app to a previously served advertisement

Check

Limit Ad Tracking Setting in iOS

Check

SDK testing

After completing the Airbridge iOS SDK setup, you can test whether it works properly by following the methods below.

Using the Airbridge dashboard

  1. Install and open the app on a test device.

  2. Navigate to [Raw Data]>[App Real-time Logs] in the Airbridge dashboard.

  3. Enter the IDFA of the test device into the search bar to find it in the logs.

It may take up to 5 minutes for the logs to be visible in the dashboard.

Using the logs

The logs will be printed to Xcode if you insert the following at the beginning of the SDK initialization code in your AppDelegate file.

12
[AirBridge setLogLevel:AB_LOG_ALL];
[AirBridge getInstance:@"YOUR_APP_SDK_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

Deep Linking

Set up dashboard

The following information must be entered on the [Tracking Link]>[Deep Links] page in the Airbridge dashboard.

  • iOS URI Scheme

  • iOS App ID

Enter the iOS URI Scheme

Enter the URI scheme into the iOS URI Scheme field, including ://.

Attention

To redirect users as intended, submit the URI scheme differently for the production app and the development app.

Enter the iOS App ID

  1. Go to Identifiers at https://developer.apple.com/account/resources.

  2. Click the identifier of the app that you want to track.

  3. Copy the identifier information and paste it to the iOS App ID field in the following format.

  • App ID Prefix + . + Bundle ID (Example: 9JA89QQLNQ.com.apple.wwdc)

Set up project

Scheme

  1. Go to [Xcode]>[Project file]>[Info]>[URL Types].

From the Airbridge dashboard, copy "iOS URI Scheme" and paste it to the URL Schemes field in Xcode. Make sure not to include ://.

  1. Go to [Xcode]>[Project file>[Signing & Capabilities].

  2. Click + Capability and add Associated Domains.

  3. Add applinks:YOUR_APP_NAME.airbridge.ioto Associated Domains.

  4. Add applinks:YOUR_APP_NAME.abr.geto Associated Domains.

YOUR_APP_NAME can be found on the [Settings]>[Token] page in the Airbridge dashboard.

Refer to Troubleshooting → Webcredentials if you want to use the autofill feature.

When using AppDelegate

For apps that support iOS 12 and earlier, events are usually sent through the application(_:open:options:) method in AppDelegate.

  1. Open ios/[Project name]/AppDelegate.

  2. Call the handleURLSchemeDeeplink function at the top of the below function to pass the deep link information to the SDK when the app is opened with a scheme.

    12345678
    - (BOOL)application:(UIApplication *)application
                openURL:(NSURL *)url
                options:(NSDictionary<UIApplicationOpenURLOptionsKey, id>*)options
    {
        [AirBridge.deeplink handleURLSchemeDeeplink:url];
    
        return YES;
    }

  3. Call the handleUserActivity function at the top of the below function to pass the deep link information to the SDK when the app is opened with a Universal Link.

    12345678
    -  (BOOL)application:(UIApplication*)application
    continueUserActivity:(NSUserActivity*)userActivity
      restorationHandler:(void (^)(NSArray* _Nullable))restorationHandler
    {
        [AirBridge.deeplink handleUserActivity:userActivity];
    
        return YES;
    }

    Attention

    When using SceneDelegate, the deep link is passed to SceneDelegate instead of AppDelegate. Refer to the next section on how to receive the deep link in SceneDelegate.

When using SceneDelegate

For apps that support iOS 13 and later, deep links are passed to the following methods.

  • When the app was loaded from a "Not running" status: scene(_:willConnectTo:options:)

  • In all other situations (e.g., background)

    • Universal link: scene(_:continue:)

    • Scheme link: scene(_:openURLContexts:)

123456789101112131415161718192021222324252627282930313233343536
import UIKit
import AirBridge

@available(iOS 13, *)
class SceneDelegate: UIWindowSceneDelegate {
    var window: UIWindow?

    // Receive links after the app's killed 
    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        if let schemeLinkURL = connectionOptions.urlContexts.first?.url {
            // Scheme
            AirBridge.deeplink()?.handleURLSchemeDeeplink(schemeLinkURL)
        } else if let userActivity = connectionOptions.userActivities.first {
            // Universal
            AirBridge.deeplink()?.handle(userActivity)
        }
        
        // ...
    }
  
    // Receive universal link
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        AirBridge.deeplink().handle(userActivity)
        // ...
    }
  
    // Receive scheme link
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let schemeLinkURL = URLContexts.first?.url else {
             return
        }
        
        AirBridge.deeplink().handleURLSchemeDeeplink(schemeLinkURL)
        // ...
    }
}

When using SwiftUI without SceneDelegate

If you are using SwiftUI without SceneDelegate, deep links are passed to onOpenURL. Add this method to the App class with @main.

123456789101112131415161718192021222324252627
import SwiftUI
import AirBridge

@main
@available(iOS 14, *)
struct OnlyUIApp: App {

    ...
    
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    if url.scheme != "http" && url.scheme != "https" {
                        // Scheme Link
                        AirBridge.deeplink()?.handleURLSchemeDeeplink(url)
                    }
                    else {
                        // Universal Link
                        let userActivity = NSUserActivity(activityType: NSUserActivityTypeBrowsingWeb)
                        userActivity.webpageURL = url
                        AirBridge.deeplink().handle(userActivity)
                    }
                }
        }
    }
}

Attention

If you are using SwiftUI with SceneDelegate, onOpenUrl cannot be used. In such a case, refer to this section.

When using AppDelegate

  1. Open ios/[Project file]/AppDelegate.

  2. Use the setDeeplinkCallback function to set up the callback that should be called when the app is opened through a deep link.

123456789
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
    [AirBridge getInstance:@"YOUR_APP_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

    [AirBridge.deeplink setDeeplinkCallback:^(NSString* deeplink) {
        // Code to run when opening app with a deep link
        // Deeplink from airbridge = YOUR_SCHEME://...
        NSLog(@"DeeplinkCallback : %@", deeplink);
    }];
}

When using SwiftUI

If you are not using AppDelegate or SceneDelegate, add the following method to the App class with @main.

12345678910111213141516171819
import SwiftUI
import AirBridge

@main
@available(iOS 14, *)
struct OnlyUIApp: App {
    init() {
        AirBridge.getInstance("YOUR_APP_SDK_TOKEN", appName: "YOUR_APP_NAME")
        AirBridge.deeplink()?.setDeeplinkCallback { deeplink in
            print(deeplink)
        }
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

  • For Airbridge iOS SDK v1.10.0 to 1.10.9: The Airbridge deep link is sent in the format of https://YOUR_APP_NAME.airbridge.io/....

  • For Airbridge iOS SDK v.1.20.0 to v1.9.10: The Airbridge deep link is sent in the format of either https://YOUR_APP_NAME.airbridge.io/... or YOUR_SCHEME://....

Set up deferred deep linking

When setting up a deep link callback, information about deferred deep links will also be sent through that deep link callback. Refer to "Set up deep link callback" to set up deferred deep link callbacks.

The deferred deep link callback is sent only once when the app is installed.

Check whether the app opens and the deep link event is sent when the Airbridge deep link is clicked on. The Airbridge deep link should follow the YOUR_SCHEME://... format. Your_Scheme is the iOS URI Scheme entered in your Airbridge dashboard.

  1. Click the deep link.

  2. Check whether the deep link event appears on the [Raw Data]>[App Real-time Logs] page in the Airbridge dashboard.

User Data

Set up user identifier

You can set up the SDK so that once a user identifier is sent to the SDK, all events collected thereafter contain the same user identifier.

12345678
[AirBridge.state setUserID:@"personID"];
[AirBridge.state setUserEmail:@"persondoe@airbridge.io"];
[AirBridge.state setUserPhone:@"1(123)123-1234"]

// user alias changed with inserted dictionary.
[AirBridge.state setUserAlias:@{@"key": @"value"}];
// key, value is inserted to existed user alias.
[AirBridge.state addUserAliasWithKey:@"key" value:@"value"];

Name

Description

Limitations

ID

User ID

-

Email

User Email

Hashed by default
(SHA256, can be disabled)

Phone

User phone number

Hashed by default
(SHA256, can be disabled)

Alias

User alias

- Maximum 10 aliases
- keytype is NSString, maximum 128 characters supporter
- keymust satisfy ^[a-zA-Z_][a-z0-9_]*$regex
valuetype is NSString, maximum 128 characters supported

Set up user attributes

Additional user attributes can be collected for a more accurate multi-touch attribution and in-depth data analysis.

1234
// user attributes changed with inserted dictionary.
[AirBridge.state setUserAttributes:@{@"key": @"value"}];
// key, value is inserted to existed user attributes.
[AirBridge.state addUserAttributesWithKey:@"key" value:@"value"];

Name

Description

Limit

Attributes

User attributes

- Maximum 100 attributes
- keytype is NSString, maximum 128 characters supported
keymust satisfy ^[a-zA-Z_][a-z0-9_]*$regex
valuetype is NSString or NSNumber
- Maximum 1024 characters supported for NSString type

User data setup testing

Check whether the user data setup has been successfully completed by following the steps below.

  1. Complete the user setup.

  2. Send an event through the SDK.

  3. Navigate to [Raw Data]>[App Real-time Logs] in the Airbridge dashboard, find the event sent, and check whether the user data is included under the user block in the JSON.

Device Data

Set up device alias

Set up the Airbridge SDK to collect device alias when collecting events. The alias won't be deleted even after the user closes the app unless the user deletes the app.

123
[AirBridge.state setDeviceAliasWithKey: "ADD_YOUR_KEY", value: "AND_YOUR_VALUE"];
[AirBridge.state removeDeviceAliasWithKey: "DELETE_THIS_KEY"];
[AirBridge.state clearDeviceAlias];

Method

Description

setDeviceAlias(withKey: String, value: String)

Adds the key-value pair to the device identifier.

removeDeviceAlias(withKey: String)

Deletes the device alias of the key. If there is no identifier, no action is executed.

clearDeviceAlias()

Deletes all device aliases.

In-app Events

When important user actions occur, those actions can be collected as in-app events.

Attention

The setCategory function must be called to send events.

Send in-app events

You can send in-app events through the SDK to Airbridge for ad performance measurement.

123456789101112131415161718192021
#import <AirBridge/ABInAppEvent.h>

ABInAppEvent* event = [[ABInAppEvent alloc] init];

[event setCategory:@"category"];
[event setAction:@"action"];
[event setLabel:@"label"];
[event setValue:@(123)];
[event setCustoms:@{@"key": @"value"}];

// Semantic Attributes Option 1
ABSemanticAttributes* semanticAttributes = [[ABSemanticAttributes alloc] init];
semanticAttributes.transactionID = @"transaction_123";
[event setSemanticAttributes:semanticAttributes];

// Semantic Attributes Option 2
// For more details, please check following page
// https://developers.airbridge.io/docs/event-structure#semantic-attributes
[event setSemantics:@{@"transactionID": @"transaction_123"}];

[event send];

Parameter

Description

setCategory

Event name (required)

setAction

Event attribute 1

setLabel

Event attribute 2

setValue

Event attribute value

setCustoms

Additional custom attributes

setSemanticAttributes

Additional semantic attributes (Map)

Send Standard Events

User Sign-Up

123456789101112131415161718192021
#import <AirBridge/ABUser.h>
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>

ABUser* user = [[ABUser alloc] init];
user.ID = @"testID";
user.email = @"testID@ab180.co";
user.phone = @"000-0000-0000";
user.alias = @{
    @"key": @"value",
};
user.attributes = @{
    @"key": @"value",
};

[AirBridge.state setUser:user];

ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.signUp];

[event send];

User Sign-In

123456789101112131415161718192021
#import <AirBridge/ABUser.h>
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>

ABUser* user = [[ABUser alloc] init];
user.ID = @"testID";
user.email = @"testID@ab180.co";
user.phone = @"000-0000-0000";
user.alias = @{
    @"key": @"value",
};
user.attributes = @{
    @"key": @"value",
};

[AirBridge.state setUser:user];

ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.signIn];

[event send];

User Sign-Out

1234567
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>

ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.signOut];

[AirBridge.state setUser:[[ABUser alloc] init]];

View Home Screen

1234567
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>
  
ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.viewHome];

[event send];

View Product Detail

1234567891011121314151617181920
#import <AirBridge/ABProduct.h>
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>
#import <AirBridge/ABSemanticsKey.h>

ABProduct* product1 = [[ABProduct alloc] init];
product1.idx = @"idx1";
product1.name = @"name1";
product1.price = @100;
product1.currency = @"USD";
product1.orderPosition = @1;
product1.quantity = @1;

ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.viewProductDetail];
[event setSemantics:@{
    ABSemanticsKey.products: @[product1.toDictionary],
}];

[event send];

View Product List

1234567891011121314151617181920212223242526272829303132
#import <AirBridge/ABProduct.h>
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>
#import <AirBridge/ABSemanticsKey.h>

ABProduct* product1 = [[ABProduct alloc] init];
product1.idx = @"idx1";
product1.name = @"name1";
product1.price = @100;
product1.currency = @"USD";
product1.orderPosition = @1;
product1.quantity = @1;

ABProduct* product2 = [[ABProduct alloc] init];
product2.idx = @"idx2";
product2.name = @"name2";
product2.price = @200;
product2.currency = @"USD";
product2.orderPosition = @2;
product2.quantity = @2;

ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.viewProductList];
[event setSemantics:@{
    ABSemanticsKey.products: @[
        product1.toDictionary,
        product2.toDictionary,
    ],
    ABSemanticsKey.productListID: @"listID",
}];

[event send];

View Search Result

1234567891011121314151617181920212223242526272829303132
#import <AirBridge/ABProduct.h>
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>
#import <AirBridge/ABSemanticsKey.h>

ABProduct* product1 = [[ABProduct alloc] init];
product1.idx = @"idx1";
product1.name = @"name1";
product1.price = @100;
product1.currency = @"USD";
product1.orderPosition = @1;
product1.quantity = @1;

ABProduct* product2 = [[ABProduct alloc] init];
product2.idx = @"idx2";
product2.name = @"name2";
product2.price = @200;
product2.currency = @"USD";
product2.orderPosition = @2;
product2.quantity = @2;

ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.viewSearchResult];
[event setSemantics:@{
    ABSemanticsKey.products: @[
        product1.toDictionary,
        product2.toDictionary,
    ],
    ABSemanticsKey.query: @"query",
}];

[event send];

Add to Cart

1234567891011121314151617181920212223242526272829303132333435
#import <AirBridge/ABProduct.h>
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>
#import <AirBridge/ABSemanticsKey.h>

ABProduct* product1 = [[ABProduct alloc] init];
product1.idx = @"idx1";
product1.name = @"name1";
product1.price = @100;
product1.currency = @"USD";
product1.orderPosition = @1;
product1.quantity = @1;

ABProduct* product2 = [[ABProduct alloc] init];
product2.idx = @"idx2";
product2.name = @"name2";
product2.price = @200;
product2.currency = @"USD";
product2.orderPosition = @2;
product2.quantity = @2;

ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.addToCart];
[event setSemantics:@{
    ABSemanticsKey.products: @[
        product1.toDictionary,
        product2.toDictionary,
    ],
    ABSemanticsKey.cartID: @"cartID",
    ABSemanticsKey.currency: @"currency"
}];

[event setValue:@300];

[event send];

Order Complete

123456789101112131415161718192021222324252627282930313233343536
#import <AirBridge/ABProduct.h>
#import <AirBridge/ABInAppEvent.h>
#import <AirBridge/ABCategory.h>
#import <AirBridge/ABSemanticsKey.h>

ABProduct* product1 = [[ABProduct alloc] init];
product1.idx = @"coke_zero";
product1.name = @"Coke Zero";
product1.price = @100;
product1.currency = @"USD";
product1.orderPosition = @1;
product1.quantity = @1;

ABProduct* product2 = [[ABProduct alloc] init];
product2.idx = @"burger_cheese_double";
product2.name = @"Double Cheeseburger";
product2.price = @200;
product2.currency = @"USD";
product2.orderPosition = @2;
product2.quantity = @2;

ABInAppEvent* event = [[ABInAppEvent alloc] init];
[event setCategory:ABCategory.purchase];
[event setSemantics:@{
    ABSemanticsKey.products: @[
        product1.toDictionary,
        product2.toDictionary,
    ],
    ABSemanticsKey.transcationID: @"transcationID",
    ABSemanticsKey.currency: @"currency",
    ABSemanticsKey.inAppPurchased: @YES
}];

[event setValue:@300];

[event send];

Event transmission testing

Send an event through the SDK and check whether the event is available in the Airbridge dashboard.

  1. Send an event through the SDK.

  2. Navigate to [Raw Data]>[App Real-time Logs] and search for the event.

Advanced Settings

Install 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. The Restricted SDK is supported in v1.34.9 and later.

Install using CocoaPods

1. Create a Podfile with the following command.

12
cd path/to/project
touch Podfile

2. Fill in the Podfile as follows.

Podfile
123
target '[Project Name]' do
    pod 'AirBridgeRestricted'
end

To install the Airbridge iOS SDK version 1.18.0 or later, CocoaPods version 1.11.0 or later is required.

3. Open the terminal and enter the following command.

12
cd path/to/project
pod install --repo-update

When no pod command is found, install cocoapods with the below command.

  • sudo gem install cocoapods

Install manually

AirBridge.framework(restricted): Download

Set up SDK Signature

With the SDK Signature, you can ensure SDK spoofing prevention and use verified events for ad performance measurement. Call the setSDKSignatureSecret function above the initialization code.

12
[AirBridge setSDKSignatureSecretWithID: "YOUR_SDK_SIGNATURE_SECRET_ID", secret: "YOUR_SDK_SIGNATURE_SECRET"];
[AirBridge getInstance:@"YOUR_APP_SDK_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

The SDK Signature Credentials are required for the SDK Signature setup. Refer to this article to learn how to create them.

Set up user identifier hashing

By default, the user email and phone number information is hashed using SHA256 before being sent to Airbridge.
To disable hashing, call the setIsUserInfoHashed function at the beginning of the SDK initialization code.

1234
// Disable user information hashing
[AirBridge setIsUserInfoHashed:NO];

[AirBridge getInstance:@"YOUR_APP_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

Set up session timeout

You can set up the session timeout by calling the setSessionTimeout function at the beginning of the SDK initialization code.

  • Session timeout is in milliseconds, and the value must range between 0 and 604800000 (7 days).

  • Default value is 1000 * 60 * 5 (5 minutes).

123
[AirBridge setSessionTimeout:1000 * 60 * 5];

[AirBridge getInstance:@"YOUR_APP_SDK_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

Opt-in setup

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

Use the method below for collecting and transmitting data after obtaining consent for personal data tracking from users, especially when GDPR or CCPA applies.

If the autoStartTrackingEnabled function is set to false before the SDK initialization code, events are not sent before the startTracking function is called.

For example, if a lifecycle event such as Deeplink Open occur while the app is not opened, and this event is sent before the startTracking function is called, the event may not be collected.

12345
AirBridge.autoStartTrackingEnabled = NO;

[AirBridge getInstance:@"YOUR_APP_SDK_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

[AirBridge startTracking];

Opt-out setup

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 where event data cannot be collected. From the moment the stopTracking function is called, the SDK will stop collecting events.

1234567
#import <AirBridge/AirBridge.h>

AirBridge.autoStartTrackingEnabled = YES;

[AirBridge getInstance:@"YOUR_APP_SDK_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];
    
[AirBridge stopTracking];

Set the setIsTrackAirbridgeDeeplinkOnly function to true at the beginning of the SDK initialization code so that only Airbridge deep links are collected.

1234
// Send deeplink events only when application is opened with `Airbridge deeplinks`
[AirBridge setIsTrackAirbridgeDeeplinkOnly:YES];

[AirBridge getInstance:@"YOUR_APP_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

Follow the steps below to collect Facebook deferred app links through the SDK.

  1. Install the Facebook SDK by following this Facebook document.

  2. Open ios/[Project name]/AppDelegate.

  3. Call the setIsFacebookDeferredAppLinkEnable at the beginning of the SDK initialization code. When isFacebookDeferredAppLinkEnabled is set to YES(true) and the Facebook SDK is installed, the SDK collects the Facebook deferred app link.

123
[AirBridge setIsFacebookDeferredAppLinkEnabled:YES];

[AirBridge getInstance:@"YOUR_APP_SDK_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

Set up Uninstall tracking

Airbridge sends a silent push daily between 3:00 PM and 4:00 PM (UTC) to users whose app event has been collected at least once in the last 6 months to check for uninstalls. Uninstall events can be monitored through Airbridge reports and raw data export files.

Refer to the article below for the detailed setup instructions.

When a user clicks a push notification, the handleNotificationDeeplink function should be called to pass the deep link in the push notification payload to the SDK.

1234567891011121314151617181920212223
- (void)application:(UIApplication *)application 
didReceiveRemoteNotification:(NSDictionary *)userInfo 
      fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler 
{
    if (UIApplication.sharedApplication.applicationState == UIApplicationStateInactive || UIApplication.sharedApplication.applicationState == UIApplicationStateBackground) {
        NSURL* url = // deeplink of push notification's payload
        
        [AirBridge.deeplink handleNotificationDeeplink:url];
    }
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center 
didReceiveNotificationResponse:(UNNotificationResponse *)response 
         withCompletionHandler:(void (^)(void))completionHandler API_AVAILABLE(ios(10.0)) 
{
    if ((UIApplication.sharedApplication.applicationState == UIApplicationStateInactive || UIApplication.sharedApplication.applicationState == UIApplicationStateBackground)
        && [response.actionIdentifier isEqual:UNNotificationDefaultActionIdentifier])
    {
        NSURL* url = // deeplink of push notification's payload
        
        [AirBridge.deeplink handleNotificationDeeplink:url];
    }
}

Tracking authorize prompt

In iOS 14.5+, the IDFA can only be collected if users consent to data tracking via the App Tracking Transparency (ATT) prompt using the AppTrackingTransparency.framework.

12345
if (@available(iOS 14, *)) {
    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
        NSLog(@"ATTrackingManagerAuthorizationStatus: %lu", (unsigned long)status);    
    }];
}

Tracking authorize timeout

When using the AppTrackingTransparency.framework to display the ATT prompt to the user, the IDFA is not collected when the install event occurs because the ATT prompt only appears after the user installs the app.

By calling the trackingAuthorizeTimeout function before the SDK initialization code, the sending of the install event will be delayed for the set timeout period to wait for the user to finish responding to the ATT prompt.

  • trackingAuthorizeTimeout is in milliseconds.

  • The sending of the Install event can be delayed for as long as the trackingAuthorizeTimeout period.

  • The trackingAuthorizeTimeout is initialized every time the app is relaunched.

When the user finishes responding to the ATT prompt, A deferred deep link is sent to the callback.

By default, the trackingAuthorizeTimeout is initialized every time the app is relaunched. To prevent this, set isRestartTrackingAuthorizeTimeout to false.

1234
AirBridge.setting.trackingAuthorizeTimeout = 30 * 1000;
AirBridge.setting.isRestartTrackingAuthorizeTimeout = NO;

[AirBridge getInstance:@"YOUR_APP_SDK_TOKEN" appName:@"YOUR_APP_NAME" withLaunchOptions:launchOptions];

Attention

For iOS SDK v.1.32.1 and later, the trackingAuthorizeTimeout is 30 seconds by default. To optimize user experience, make sure to configure the value to a sufficient time period.

Event buffer limit

When an event transmission failure occurs, the Airbridge SDK will store the event and retry later. The following settings will allow you to limit the storage used for such events. The new settings will apply starting from the next SDK initialization.

1234
// Event count limit
[AirBridge.setting setEventMaximumBufferCount:newValue]
// Event size limit (Byte)
[AirBridge.setting setEventMaximumBufferSize:newValue]

Event transmission cycle

You can configure the event transmission cycle so that when the event transmission succeeds once, the next event transmission will take place in the next cycle. The default value is set to 0 milliseconds.

12
// 이벤트 전송 주기 (Millisecond 단위)
[AirBridge.setting setEventTransmitInterval:newValue]

Delete unprocessed events

Clear the device's internal database of unprocessed events that have not been sent to Airbridge.

12345
// 활성화
Airbridge.setResetEventBufferEnabled(true)

// 비활성화
Airbridge.setResetEventBufferEnabled(false)

Attention

The code above must be run before Airbridge starts tracking. If autoStartTracking is set to true, the code must be run before getInstance, and if autoStartTracking is set to false, the code must be run before startTracking. If not, the function won't work.

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.

You can use tracking links within the app. Note that custom domain tracking links with custom short IDs cannot don't function within the app. Use the method below to redirect users to specific in-app locations without sending them to an external browser.

12
Airbridge.placement().click("https://abr.ge/~~~")
Airbridge.placement().impression("https://abr.ge/~~~")

Click

When a user clicks on the tracking link within the app, the Airbridge.click function is called. A click event is collected, and the user is redirected to the configured app or web fallback path.

Impression

When a user engages with a tracking link within the app, the Airbridge.click function is called. An impression event is collected.

Set up attribution result callback

To get the attribution result from the Airbridge iOS SDK, the callback closer must be passed to the attributionCallback.

The attribution result callback is provided only once after the app install.

1234
AirBridge.setting().attributionCallback = { (attribution: [String : String]) in
    // Process attribution data...

}

The table below lists the data fields that will be retrieved through the callback.

Field

Description

attributedChannel

Channel (String)

attributedCampaign

Campaign (String)

attributedAdGroup

Ad Group (String)

attributedAdCreative

Ad Creative (String)

attributedContent

Content (String)

attributedTerm

Keyword (String)

attributedSubPublisher

Sub Publisher (String)

attributedSubSubPublisher1

Sub-sub Publisher 1 (String)

attributedSubSubPublisher2

Sub-sub Publisher 2 (String)

attributedSubSubPublisher3

Sub-sub Publisher 3 (String)

If an event is unattributed, meaning that there is no attribution result, you will get the following response.

123
  {
    "attributedChannel": "unattributed"
  }

Guidelines for using attribution result data

When the attribution data exists

  • Attribution data is forwarded within 40 seconds of SDK initialization.

  • If the app is closed and the attribution data cannot be received, the attribution data is forwarded within 40 seconds when the app is opened again.

  • On very rare occasions, it could take up to 5 minutes for the attribution data to be received.

When the attribution data does not exist

  • The attribution data will be sent when the app is opened again after at least three hours have passed since the SDK was initialized.

  • Note that it is not recommended to use the attribution data for real-time processing.

Guidelines for using attribution result data

When the attribution data exists

  • Attribution data is forwarded within 40 seconds of SDK initialization.

  • If the app is closed and the attribution data cannot be received, the attribution data is forwarded within 40 seconds when the app is opened again.

  • On very rare occasions, it could take up to 5 minutes for the attribution data to be received.

When the attribution data does not exist

  • The attribution data will be sent when the app is opened again after at least three hours have passed since the SDK was initialized.

  • Note that it is not recommended to use the attribution data for real-time processing.

Collect in-session lifecycle events

The following code allows you to collect lifecycle events (ORGANIC_REOPENFOREGROUND) within the session timeframe.

1
[AirBridge.setting setTrackInSessionLifeCycleEventEnabled:YES];

Deactivate Airbridge

All Airbridge functions can be turned off using the following method.

12345
// 활성화
Airbridge.setSDKEnabled(true)

// 비활성화
Airbridge.setSDKEnabled(false)

Attention

The above function must be run before the initialization code (getInstance). If not, the function won't work.

Event collection in iOS Extension

Initialize the SDK using the viewDidLoad function in the iOS Extension and collect events using the functions listed here.

1234
override func viewDidLoad() {
  super.viewDidLoad()
    AirBridge.getInstance("YOUR_APP_SDK_TOKEN", appName:"YOUR_APP_NAME", withLaunchOptions:launchOptions)
}

Attention

The following limitations exist when utilizing the Airbridge SDK in iOS Extensions.

  • In iOS Extensions, lifecycle events such as Install, Open, Deeplink Open, and Foreground events are not collected.

  • If event transmission from the iOS Extension is abruptly terminated, it will resume later when the Extension is launched again. The event transmission is not attempted when the app is launched.

  • SKAN measurement is not recommended when using the Airbridge SDK in the iOS Extension, as the conversion value measurement may not work correctly.

Compliance with Google DMA

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

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

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 there are consent values stored, continue to Step 3.

If the end user launched the app from outside the EEA, it is not necessary to collect user consent.

Note

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

2. If there are no consent values stored, proceed to obtain user consent, such as with a privacy prompt. You must collect the adPersonalization and adUserData values in this step.

3. Initialize the Airbridge SDK and share the consent values with Airbridge before collecting the end user’s personal data.

Attention

Take note of the following items.

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

  • Input 0 or 1 in accordance with the consent data collected.

1234567891011121314151617
// AppDelegate.swift
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]?
) {
    AirBridge.setAutoStartTrackingEnabled(false)
    AirBridge.getInstance("YOUR_APP_SDK_TOKEN", appName:"YOUR_APP_NAME", withLaunchOptions:launchOptions)

    // Based on actual region
    AirBridge.state()?.UserAlias(withKey:"eea", value:"0" or "1")
    
    // Based on actual user consent
    AirBridge.state()?.UserAlias(withKey:"adPersonalization", value:"0" or "1")
    AirBridge.state()?.UserAlias(withKey:"adUserData", value:"0" or "1")
    
    AirBridge.startTracking()
}

Hybrid App Setup

Sending events in WebView environments

Attention

Note that to utilize this feature, both SDKs must be installed: the Android SDK on the mobile native environment and the WebView SDK on the WebView environment's website.

The iOS SDK can handle event transmission occurring within the in-app website of a hybrid app instead of the Web SDK installed on the website.

Refer to the configuration below.

12345678
WKWebViewConfiguration* configuration = [[WKWebViewConfiguration alloc] init];

WKUserContentController* controller = [[WKUserContentController alloc] init];
[AirBridge.webInterface injectTo:controller withWebToken:@"YOUR_WEB_TOKEN"];

configuration.userContentController = controller;
    
WKWebView* webview = [[WKWebView alloc] initWithFrame:CGRectZero configuration:configuration];

You can find the YOUR_WEB_TOKEN on the [Settings]>[Tokens] page in your Airbridge dashboard.

Troubleshooting

Webcredentials

Users may see the domain of passwords stored with the Password AutoFill feature as airbridge.io or abr.ge. If you want to change the domain to store the password, follow the steps below.

  1. Host the JSON below at https://example.com/.well-known/apple-app-site-association. Your prepared domain should be entered instead of example.com.

    12345
    {
        "webcredentials": {
            "apps": ["TEAM_ID.APP_BUNDLE_ID"]
        }
    }

    Example: 9JA89QQLNQ.com.apple.wwdc

  2. Navigate to [Xcode]>[Project File]>[Signing & Capabilities]>[Associated Domains].

  3. Click + and add webcredentials:example.com.

Bitcode compile error

Airbridge iOS SDK does not support Bitcode from version 1.28.0. Note that Bitcode has been deprecated from Xcode 14. If you use Bitcode in an App project, you may encounter the following compile errors.

Text
1
Textld: XCFrameworkIntermediates/AirBridge/AirBridge.framework/AirBridge(AirBridge-arm64-master.o)' does not contain bitcode. You must rebuild it with bitcode enabled (Xcode setting ENABLE_BITCODE)

To solve this issue, you need to add the following to the Podfile.

Podfile
12345
installer.pods_project.targets.each do |target|
    target.build_configurations.each do |configuration|
        configuration.build_settings['ENABLE_BITCODE'] = 'NO'
    end
end

Or you may set the ENABLE_BITCODE to No.

Note that Bitcode has been deprecated, and the App Store automatically deletes the Bitcode when .ipa files using Bitcode are submitted.

Build issues in Xcode 13

The Airbridge iOS SDK does not support Xcode 13 and iOS 9 or 10 starting from version 1.28.0.
If you need to use Xcode 13, use Airbridge iOS SDK versions 1.27.0 or earlier.

Crashes occurring on iOS versions earlier than 14.2 when installing the SDK using Tuist fetch and SPM

The Airbridge iOS SDK utilizes several built-in iOS frameworks. Among them, AdServices requires the iOS version 14.2 or later. However, the Swift Package Manager has a feature that automatically links a framework as Optional if its minimum OS version is higher than the Target's minimum OS version. In contrast, when using Tuist fetch—which only retrieves metadata instead of utilizing Swift Package Manager—the framework is linked to Required, leading to this issue. You can find the relevant Tuist code here.

In this case, you can resolve the problem by installing the SDK using the method "Xcode Native Package Manager Support" provided by Tuist, or you can simply download AirBridge.xcframework and add it to the SDK.

12345678
.xcframework(path: "${YOUR_PATH}/AirBridge.xcframework")
.sdk(name: "AdSupport", type: .framework, status: .optional)
.sdk(name: "iAd", type: .framework, status: .optional)
.sdk(name: "AdServices", type: .framework, status: .optional)
.sdk(name: "CoreTelephony", type: .framework, status: .optional)
.sdk(name: "StoreKit", type: .framework, status: .optional)
.sdk(name: "AppTrackingTransparency", type: .framework, status: .optional)
.sdk(name: "WebKit", type: .framework, status: .optional)

SDK Migration

When updating the SDK, consider the content regarding versions between the previous version and the later version or your updated version.

1.36.0

For apps registered with Airbridge after November 4, 2023, an issue where the deep link URL provided in the deep link callback was decoded twice from the content entered in the Airbridge dashboard has been resolved. This issue was found in versions 1.34.0 to 1.35.1.

1.34.0

For apps registered with Airbridge after September 4, 2023, the "airbridge_referrer" will no longer be added to the deep link URL provided in the deep link callback and will instead pass it to the information entered in the Airbridge Dashboard.

1.33.0

When a user updates an app with iOS SDK v1.33.0 or earlier to v1.33.0 or later, the last calculated SKAN conversion value will be finalized, and no additional calculation will be processed.

  • For iOS SDK versions earlier than 1.33.0, the SKAN conversion value is calculated for up to 24 hours.

  • There is no issue for users who newly install the SDK.

1.32.1

The default setting for trackingAuthorizeTimeout was changed from 0 seconds to 30 seconds.

Was this page helpful?

Have any questions or suggestions?