Integration

1. Prerequisites

• Latest version of Xcode
• Register and log in to TopOn account and add the application in application management
• Download the Demo Project

You can download or update Xcode in the AppStore , or log in to the Apple Developer Resource Center to download a specific version. (Third-party download tools may not be supported).

2. Import TopOn iOS SDK into the project

We provide the following two ways to import TopOn iOS SDK:

• CocoaPods (preferred)
• Manual download and import

The easiest way to import the SDK into an iOS project is to use CocoaPods. If you are new to CocoaPods, please refer to the official CocoaPods website.

2.1 CocoaPods (preferred)

Please click here to go to the SDK Download Center. You can refer to the following picture steps to select and generate the code in the Podfile according to your needs.

Please do not leave the SDK Download Center page after generating the relevant code, as the content will be used in the subsequent docking process.

After switching to the path where the podfile is located, execute pod install --repo-update in the terminal to install it

2.2 Manual download and import

2.2.1 Manually download TopOn iOS SDK

Please click here to go to the SDK Download Center. You can refer to the following sample images, select the advertising platform according to your needs and then download the TopOn iOS SDK.

• Please do not leave the SDK Download Center page after downloading the SDK, as the content will be used in the subsequent docking process.
• After you click "Generate Access Code", the system will process your request immediately. After your patient waiting, the download link will be successfully generated and you can click the "Download" button.

2.2.2 Manually import the TopOn iOS SDK

① Please unzip the ZIP file you downloaded in the previous step, and then drag it into your Xcode project.

② Modify the Xcode project Build Setting (please refer to the picture below).

③ Please return to the SDK Download Center page, check the "SDK Import Tips" column, and add the dependencies listed in the column to the Xcode project.

Depending on the type of advertising platform you have selected, the "SDK Introduction Prompt" column may appear additionally (as shown below). If the "SDK Introduction Prompt" column does not appear after you have selected the advertising platform and clicked "Generate Access Code", you can skip this step and continue with the subsequent access process.

At this point, you have completed the introduction of TopOn iOS SDK, but please do not leave the "SDK Download Center" page, as the subsequent docking process will still use its content.

3. Update your Info.plist

3.1 Open Info.plist

3.2 Add SKAdNetworkItems key

The SKAdNetwork ID of UnityAds is different for each project. If you choose this advertising platform, please refer to the one generated by the UnityAds background. You need to go to the UnityAds management background to check it.

Please return to the " SDK Download Center" page opened above and add the content listed in the "SKAdNetwork IDs Code" column to your Info.plist file, as shown below:

3.3 Add LSApplicationQueriesSchemes key

Please return to the " SDK Download Center" page opened above, or directly copy the code below and add the contents listed in the following columns to your Info.plist file. Please refer to the figure below:

3.4 Add NSUserTrackingUsageDescription key

Starting from iOS14.5, applications can only access users' IDFA data and deliver targeted ads to users with the user's explicit permission.

The IDFA will not be available until the app calls the App Tracking Transparency framework to request app tracking authorization from the end user. If an app does not make this request, the IDFA read will return a string of all 0s.

<key>NSUserTrackingUsageDescription</key>
<string>Write Your ATT Desc</string>

3.5 Add NSAppTransportSecurity key

After iOS 10, the Allow Arbitrary Loads in Web Content key is ignored when it exists.

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

3.6 Adding the GADApplicationIdentifier key to the AdMob platform

Due to AdMob requirements, this key is only added if you check the box to use the platform. For more information, go here .

<key>GADApplicationIdentifier</key>
<string>Your GADApplicationIdentifier </string>
<!-- format eg：ca-app-pub-9488501426181082~7319780494   -->

4. Request app tracking permission from users to obtain IDFA

You need to apply for app tracking permissions from users through App Tracking Transparency.

• Before you use the following method, you need to set the NSUserTrackingUsageDescription key in your Info.plist file. Click here for details.
• If you need to adapt GDPR or Google UMP in your project, please go here to configure it without adding the following code.

#import <AppTrackingTransparency/AppTrackingTransparency.h>
#import <AdSupport/AdSupport.h>
#import <AnyThinkSDK/AnyThinkSDK.h>

@implementation AppDelegate
 
- (void)applicationDidBecomeActive:(UIApplication *)application {
    if (@available(iOS 14, *)) {
        //iOS 14
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {

        }];
    } else {
        NSString * idfaStr = [ASIdentifierManager sharedManager].advertisingIdentifier.UUIDString;
    }
}

@end

In iOS 15 and above, calling this API will prompt for authorization only when the application state is UIApplicationStateActive. If another permission request is waiting for user confirmation, the authorization prompt will not be displayed. Therefore, you can choose one of the following options as a backup solution:

• After launching the app, wait 1 to 2 seconds to check and apply for permissions.
• Check and apply for permissions in the main controller's ViewDidAppear method.

5. Enable debug logging

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    //....
    //SDK log switch
    [ATAPI setLogEnabled:YES];//Turn on debug logs
    //....
     
    return YES;
}

6. SDK integration verification

You can check whether the SDK integration of each advertising platform is normal based on the log output by this method.

Please note that this feature needs to be removed before the package can be put on the shelves.

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    //....
    //Open SDK logs
    [ATAPI setLogEnabled:YES];//Turn on debug logs

    //After logs open
    [ATAPI integrationChecking];

    return YES;
}

Sample output:

7. Initialize SDK

1. If your app is launched in the EU, please configure GDPR before initialization . If you choose the Admob platform, you need to set up Google UMP for launch in the EU . After setting up Google UMP, you do not need to perform additional GDPR configuration.

2. If your app needs to display a privacy policy and request user consent when the user first launches the app, please refer to TopOn Privacy Policy .

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Init SDK
    [[ATAPI sharedInstance] startWithAppID:@"Your AppID" appKey:@"Your appKey" error:nil];
    //....
     
    return YES;
}