Setup

Follow these steps to setup the Didomi iOS and tvOS SDK:

• Requirements

• Add the SDK to your project

• Initialize the SDK

• Setup the SDK UI

• Configure the SDK

• SwiftUI

Requirements

We offer our SDK as a pre-compiled binary package as a XCFramework that you can add to your application. We support iOS versions >= 9 and tvOS versions >= 11.

Add the SDK to your project

The package can be added using CocoaPods or manually.

Using CocoaPods

The package can be added using CocoaPods:

Xcode >= 12 (XCFramework)

1. If you haven't already, install the latest version of CocoaPods. 2. Add this line to your Podfile:

pod 'Didomi-XCFramework', '2.17.1'

Using Swift Package Manager

The iOS SDK is available through Swift Package Manager as a binary library. In order to integrate it into your iOS or tvOS project follow the instructions below:

• Open your Xcode project

• Select your project in the navigator area

• Select your project in the PROJECT section

• Select the Package Dependencies

• Click on the + button

• Copy the package url https://github.com/didomi/didomi-ios-sdk-spm into the search bar

• Select the didomi-ios-sdk-spm package from the list

• Click on Add Package

• From the Choose Package Products for the didomi-ios-sdk-spm screen click on Add Package

Your setup should end up looking like this:

Swift Package Manager setup

Manually

The package can also be added manually as explained below:

1. Download and unzip the latest version of our framework for Xcode >= 12: https://sdk.didomi.io/ios/didomi-ios-sdk-2.17.1-xcframework.zip

2. In Xcode, select your project.

3. In Xcode, select your project.

4. Then, select your app target.

5. Click on the General tab.

6. Scroll down to the Embedded binaries section.

7. From finder, drag the Didomi.framework file into the Embedded binaries section.

8. Make sure the Copy items if needed box is checked and click on finish

9. Your configuration should end up looking as follows:

Objective-C projects only

The iOS Didomi SDK is written in Swift so if your app is written in Objective-C, please make sure that the Always Embed Swift Standard Libraries flag is set to YES as shown in the image below:

Initialize the SDK

Once our SDK has been added to your project, you need to initialize it. The initialization process will prepare the SDK for interactions with the user and your application. It is important to launch the SDK initialization as soon as possible.

In the AppDelegate, make sure to import the Didomi module, then call the initialize method and pass your API key:

Swift

import UIKit
import Didomi

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        let parameters = DidomiInitializeParameters(
            apiKey: "<Your API key>",
            localConfigurationPath: "<Your local config path>",
            remoteConfigurationURL: "<Your remote config url>",
            providerID: "<Your provider ID>",
            disableDidomiRemoteConfig: true|false,
            languageCode: "<Your language code>",
            noticeID: "<Your notice ID>"
        )
        Didomi.shared.initialize(parameters)
        
        // Important: views should not wait for onReady to be called.
        // You might want to execute code here that needs the Didomi SDK
        // to be initialized such us: analytics and other non-IAB vendors.
        Didomi.shared.onReady {
            // The Didomi SDK is ready to go, you can call other functions on the SDK
        }
        
        return true
    }
}

Objective-C

#import <UIKit/UIKit.h>
#import <Didomi/Didomi.h>

@interface AppDelegate : UIResponder <UIApplicationDelegate>

@property (strong, nonatomic) UIWindow *window;

@end

#import "AppDelegate.h"

@interface AppDelegate ()

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];

    Didomi *didomi = [Didomi shared];
    DidomiInitializeParameters *parameters = [[DidomiInitializeParameters alloc] initWithApiKey: @"<Your API key>"
                                                                         localConfigurationPath: nil
                                                                         remoteConfigurationURL: nil
                                                                                     providerID: nil
                                                                      disableDidomiRemoteConfig: NO
                                                                                   languageCode: nil
                                                                                       noticeID: @"<Your notice ID>"];
    
    [didomi initialize: parameters];
    // Important: views should not wait for onReady to be called.
    // You might want to execute code here that needs the Didomi SDK
    // to be initialized such us: analytics and other non-IAB vendors.
    [didomi onReadyWithCallback:^{
        // The Didomi SDK is ready to go, you can call other functions on the SDK
    }];

    return YES;
}

@end

Keep in mind that the SDK initialization is an asynchronous process so you must avoid interacting with the Didomi object until it is actually ready to handle your requests. Use the onReady closure in Swift or the onReadyWithCallback method in Objective-C to register a listener for the ready event.

Setup the SDK UI

Note: the setupUI method should be called only from your main/entry UIViewController which in most cases should be once per app launch.

You do not need to call onReady, isReady or shouldConsentBeCollected before calling setupUI because they are called internally. Therefore, by calling this method the consent notice and preference views will only be displayed if it is required and only once the SDK is ready.

In order for the SDK to be able to display UI elements and interact with the user, you must provide a reference to your main UIViewController. Make sure to import the Didomi module and call the setupUI method in Swift, setupUIWithContainerController in Objective-C, of the SDK in the viewDidLoad method of your main UIViewController:

Swift

import UIKit
import Didomi

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        Didomi.shared.setupUI(containerController: self)
    }
}

Objective-C

#import <UIKit/UIKit.h>
#import <Didomi/Didomi.h>

@interface ViewController : UIViewController

@end

#import "ViewController.h"

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    Didomi *didomi = [Didomi shared];
    [didomi setupUIWithContainerController:self];
}

@end

Deep links

If you are using deep links or have multiple main activities in your app make sure that the setupUI function is called on every activity that the user can launch the app on. This will ensure that consent is always collected as needed and there is no path where the user can launch the app without consent being collected. If setupUI is missing at some entry points, you will see lower consent rates as users will be using the app without giving consent.

Configure the SDK

We support three options for configuring the UI and the behavior of the SDK:

• Didomi Console: the SDK is configured remotely from the Didomi Console

• Local file: the SDK is configured from a didomi_config.json file embedded in your app package

• Remote file: the SDK is configured from a remote didomi_config.json file

From the Console (Recommended)

You can configure the consent notice in your app by creating a notice in your Didomi Console. It will automatically be linked to your app through your API Key and, optionally, your app package name. You can access the Didomi console here.

In order to enable this option, make sure to pass the disableDidomiRemoteConfig parameter as false when calling the initialize method as shown below.

Swift

Didomi.shared.initialize(
    apiKey: "<Your API key>",
    localConfigurationPath: nil,
    remoteConfigurationURL: nil,
    providerId: nil,
    disableDidomiRemoteConfig: false
)

Objective-C

[didomi initializeWithApiKey:@"<Your API key>" localConfigurationPath:nil remoteConfigurationURL:nil providerId:nil disableDidomiRemoteConfig:NO languageCode:nil];

The SDK will automatically use the remote configuration hosted by Didomi and cache it locally. The cached version is refreshed every 60 minutes.

Local file (deprecated)

Using your own remote file automatically disables the TCF integration. If your app uses the TCF, you must use a configuration from the Didomi Console.

Using a local file will prevent you to support multiple regulations.

With this option, you create your own SDK configuration file and embed in your app package.

The SDK behavior is configured in a didomi_config.json file that must be placed somewhere under your project folder (see the image below for reference). Create a file with the following content to get started:

didomi_config.json

{
    "app": {
        "name": "My App Name",
        "privacyPolicyURL": "http://www.website.com/privacy",
        "vendors": {
            "iab": {
                "all": true
            }
        },
        "gdprAppliesGlobally": true,
        "gdprAppliesWhenUnknown": true
    }
}

You also need to disable loading the remote configuration to ensure that only the local file is loaded and that no HTTP request is sent. Update your initialize call to set the disableDidomiRemoteConfig parameter to true:

Swift

Didomi.shared.initialize(
    apiKey: "<Your API key>",
    localConfigurationPath: nil,
    remoteConfigurationURL: nil,
    providerId: nil,
    disableDidomiRemoteConfig: true
)

Objective-C

[didomi initializeWithApiKey:@"<Your API key>" localConfigurationPath:nil remoteConfigurationURL:nil providerId:nil disableDidomiRemoteConfig:YES languageCode:nil];

Your SDK is now setup. Read the Getting started section to learn more about how to configure it to match your app UI and requirements.

Remote file

Using your own remote file automatically disables the TCF integration. If your app uses the TCF, you must use a configuration from the Didomi Console.

Enabling this option will prevent the configuration from being loaded from the Didomi Console.

You can provide a remote URL for the SDK to download the didomi_config.json configuration file from. That allows you to update the SDK configuration without having to re-publish you mobile application.

When that configuration is enabled, the SDK will automatically use the remote configuration and cache it locally. The cached version is refreshed every 60 minutes. If there is no connection available to download the remote file and no locally cached version, the SDK will try to use the local didomi_config.json (provided in the app bundle) as a fallback.

To enable that option, change your call to initialize to provide the remote file URL:

Swift

Didomi.shared.initialize(
    apiKey: "<Your API key>",
    localConfigurationPath: nil,
    remoteConfigurationURL: "http://www.website.com/didomi_config.json",
    providerId: nil,
    disableDidomiRemoteConfig: false
)

Objective-C

[didomi initializeWithApiKey:@"<Your API key>" localConfigurationPath:nil remoteConfigurationURL:@"http://www.website.com/didomi_config.json" providerId:nil disableDidomiRemoteConfig:NO languageCode:nil];

Also see the reference documentation of the initialize function for more information.

Download Global Vendor List (GVL)

Since version 1.40.1 the GVL will be downloaded by default from our API before the SDK is initialized. If you want to stop this behaviour, provide the app.vendors.iab.requireUpdatedGVL flat set to false in the CUSTOM JSON section when editing your notice on the Console app (or in your local didomi_config.json file if that's the case).

{
    "app": {
        "vendors": {
            "iab": {
                "requireUpdatedGVL": false
            }
        }
    }
}

A timeout can also be provided to specify a maximum timeout for the Download of the GVL. This can be done by providing the app.vendors.iab.updateGVLTimeout property (in seconds).

{
    "app": {
        "vendors": {
            "iab": {
                "updateGVLTimeout": 10
            }
        }
    }
}

SwiftUI

When you create a new Apple app, among other things you need to choose if your app is going to use UIKit or SwiftUI. SwiftUI is Apple's new framework for creating user interfaces in a declarative way. In order to use the Didomi SDK in a SwiftUI app we suggest the following steps.

Prepare UIViewController to call setupUI method

1. Create a new Swift file. You can name it for example DidomiWrapper.

2. Inside this new file, create a new class that extends UIViewController. We need this to make sure we call the setupUI method when the viewDidlLoad method is called.

3. Inside the same file, create a struct that implements the UIViewControllerRepresentable protocol as shown below:

import SwiftUI
import Didomi

// If you have your own UIViewController you can use that instead.
class DidomiViewController: UIViewController {
    override func viewDidLoad() {
        // 2)
        Didomi.shared.setupUI(containerController: self)
    }
}

// 3)
struct DidomiWrapper: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        let didomiViewController = DidomiViewController()
        
        return didomiViewController
    }
    
    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
        // We don't need to implement this method
    }
}

Prepare AppDelegate to call initialize method

When using SwiftUI, you might still want to use the UIApplicationDelegate functionality. Since we want to initialize the Didomi SDK as early as possible we recommend creating a class that implements the UIApplicationDelegate.

1. Create a new Swift file. You can name it for example YourSwiftUIApp.

2. Create a new class that extends the UIApplicationDelegate protocol. Inside the applicationDidFinishLaunchingWithOptions method, call the Didomi initialize method.

3. Create a new struct that implements the SwiftUI's App protocol. Use the UIApplicationDelegateAdaptor property wrapper to connect this new struct with the AppDelegate class. Make sure this new struct uses the main annotation. Now you are ready to use the new DidomiWrapper struct that you created in the previous steps.

The snippet below shows the steps explained in the points above.

import SwiftUI
import Didomi

// 2)
class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        let parameters = DidomiInitializeParameters(
            apiKey: "<Your API key>",
            localConfigurationPath: "<Your local config path>",
            remoteConfigurationURL: "<Your remote config url>",
            providerID: "<Your provider ID>",
            disableDidomiRemoteConfig: true|false,
            languageCode: "<Your language code>",
            noticeID: "<Your notice ID>"
        )
        Didomi.shared.initialize(parameters)
        return true
    }
}

// 3)
@main
struct YourSwiftUIApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    
    var body: some Scene {
        WindowGroup {
            DidomiWrapper()
        }
    }
}