# Setup Follow these steps to set up the Didomi iOS and tvOS SDK: * [Requirements](#requirements) * [Add the SDK to your project](#add-the-sdk-to-your-project) * [Initialize the SDK](#initialize-the-sdk) * [Set up the SDK UI](#setup-the-sdk-ui) * [Configure the SDK](#configure-the-sdk) * [SwiftUI](#swiftui) ## Requirements We offer our SDK as a pre-compiled XCFramework that you can add to your application. We support iOS versions >= 10 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: {% tabs %} {% tab title="Xcode >= 12 (XCFramework)" %} 1\. If you haven't already, install the latest version of [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).\ 2\. Add this line to your `Podfile`: ``` pod 'Didomi-XCFramework', '2.40.0' ``` {% endtab %} {% endtabs %} ### 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 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: where `X.Y.Z` corresponds to the version number that you want to add. 2. In Xcode, select your project. 3. Then, select your app target. 4. Click on the `General` tab. 5. Scroll down to the `Embedded binaries` section. 6. From Finder, drag the `Didomi.framework` file into the `Embedded binaries` section. 7. Make sure the `Copy items if needed` box is checked and click on `Finish`. 8. Your configuration should end up looking as follows: ![](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-e426838e71c4ae878c90557079ac25c18fa3fee1%2Fimage.png?alt=media) ### 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: ![](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-86c7b2d00a0bf09be21e3332790f5dbee6341e06%2Fimage.png?alt=media) ## 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: {% tabs %} {% tab title="Swift" %} ```swift import UIKit import Didomi @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { let parameters = DidomiInitializeParameters( apiKey: "", localConfigurationPath: "", remoteConfigurationURL: "", providerID: "", disableDidomiRemoteConfig: true|false, languageCode: "", noticeID: "" ) 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 as: 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 } } ``` {% endtab %} {% tab title="Objective-C" %} ```objectivec #import #import @interface AppDelegate : UIResponder @property (strong, nonatomic) UIWindow *window; @end ``` ```objectivec #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: @"" localConfigurationPath: nil remoteConfigurationURL: nil providerID: nil disableDidomiRemoteConfig: NO languageCode: nil noticeID: @""]; [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 as: 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 ``` {% endtab %} {% endtabs %} 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. ## Set up the SDK UI {% hint style="info" %} 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. {% endhint %} 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`: {% tabs %} {% tab title="Swift" %} ```swift import UIKit import Didomi class ViewController: UIViewController { override func viewDidLoad() { super.viewDidLoad() Didomi.shared.setupUI(containerController: self) } } ``` {% endtab %} {% tab title="Objective-C" %} ```objectivec #import #import @interface ViewController : UIViewController @end ``` ```objectivec #import "ViewController.h" @implementation ViewController - (void)viewDidLoad { [super viewDidLoad]; Didomi *didomi = [Didomi shared]; [didomi setupUIWithContainerController:self]; } @end ``` {% endtab %} {% endtabs %} ### Deep links If you are using deep links or have multiple entry points in your app, make sure that the `setupUI` function is called on every entry point 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](#from-the-console-recommended): the SDK is configured remotely from the Didomi Console * [Local file](#local-file): the SDK is configured from a `didomi_config.json` file embedded in your app package * [Remote file](#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 notice ID. Values for the API key and notice ID can be retrieved directly from the [Didomi console](https://console.didomi.io/). {% tabs %} {% tab title="Swift" %} ```swift Didomi.shared.initialize( apiKey: "", localConfigurationPath: nil, remoteConfigurationURL: nil, providerId: nil, disableDidomiRemoteConfig: false, noticeID: "" ) ``` {% endtab %} {% tab title="Objective-C" %} ```objectivec [didomi initializeWithApiKey:@"" localConfigurationPath:nil remoteConfigurationURL:nil providerId:nil disableDidomiRemoteConfig:NO languageCode:nil noticeID:@""]; ``` {% endtab %} {% endtabs %} 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) {% hint style="danger" %} 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. {% endhint %} {% hint style="warning" %} Using a local file will prevent you from supporting multiple regulations. {% endhint %} With this option, you create your own SDK configuration file and embed it 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: {% tabs %} {% tab title="didomi\_config.json" %} ```javascript { "app": { "name": "My App Name", "privacyPolicyURL": "http://www.website.com/privacy", "vendors": { "iab": { "all": true } }, "gdprAppliesGlobally": true, "gdprAppliesWhenUnknown": true } } ``` {% endtab %} {% endtabs %} ![](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-0a333e142f754fa14cdd3a2f727409677b2c08bc%2Fimage.png?alt=media) 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`](https://developers.didomi.io/cmp/mobile-sdk/reference/api#initialize) call to set the `disableDidomiRemoteConfig` parameter to `true`: {% tabs %} {% tab title="Swift" %} ```swift Didomi.shared.initialize( apiKey: "", localConfigurationPath: nil, remoteConfigurationURL: nil, providerId: nil, disableDidomiRemoteConfig: true ) ``` {% endtab %} {% tab title="Objective-C" %} ```objectivec [didomi initializeWithApiKey:@"" localConfigurationPath:nil remoteConfigurationURL:nil providerId:nil disableDidomiRemoteConfig:YES languageCode:nil]; ``` {% endtab %} {% endtabs %} Your SDK is now set up. [Read the Getting started section](https://developers.didomi.io/cmp/mobile-sdk/consent-notice/getting-started) to learn more about how to configure it to match your app UI and requirements. ### Remote file {% hint style="danger" %} 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. {% endhint %} {% hint style="info" %} Enabling this option will prevent the configuration from being loaded from the Didomi Console. {% endhint %} 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 your 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](https://developers.didomi.io/cmp/mobile-sdk/reference/api#initialize) to provide the remote file URL: {% tabs %} {% tab title="Swift" %} ```swift Didomi.shared.initialize( apiKey: "", localConfigurationPath: nil, remoteConfigurationURL: "http://www.website.com/didomi_config.json", providerId: nil, disableDidomiRemoteConfig: false ) ``` {% endtab %} {% tab title="Objective-C" %} ```objectivec [didomi initializeWithApiKey:@"" localConfigurationPath:nil remoteConfigurationURL:@"http://www.website.com/didomi_config.json" providerId:nil disableDidomiRemoteConfig:NO languageCode:nil]; ``` {% endtab %} {% endtabs %} Also see the [reference documentation of the initialize function](https://developers.didomi.io/cmp/mobile-sdk/reference/api#initialize) 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 behavior, provide the `app.vendors.iab.requireUpdatedGVL` flag 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 `viewDidLoad` method is called. 3. Inside the same file, create a struct that implements the `UIViewControllerRepresentable` protocol as shown below: ```swift 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 `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. ```swift import SwiftUI import Didomi // 2) class AppDelegate: NSObject, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { let parameters = DidomiInitializeParameters( apiKey: "", localConfigurationPath: "", remoteConfigurationURL: "", providerID: "", disableDidomiRemoteConfig: true|false, languageCode: "", noticeID: "" ) Didomi.shared.initialize(parameters) return true } } // 3) @main struct YourSwiftUIApp: App { @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate var body: some Scene { WindowGroup { DidomiWrapper() } } } ```