iOS CMP Integration Manual

1 1. Overview
2 2. Before you start
3 3. Simple Consent Message
4 4. Privacy Manager
5 5. Support for PUR layer
6 6. Reacting to App User Actions
7 7. Clear Consent

Important Notice
Starting from Version 10, all libraries will share the same version number to prevent mismatches and reduce confusion.

Additionally, the SDK configuration has been updated. Please verify that all configurations are correctly set in your project.

Ensure you are using the correct version for all dependencies.

Release Note (v10.2.1)

SourcePoint library is updated (v7.7.7)
Use “import YieldloveAdIntegration” instead of “import YieldloveConsent”
Document exclude objective-C

1. Overview

SDK provides an optional Consent Collection feature or CMP. The SDK currently implements TCF v2. The TC string generated by the SDK is available to callers and can be found in the standard location as per TCF v2 specification.

2. Before you start

2.1 Cocoapods

Add CMP pod to your Podfile

pod 'YieldloveAdIntegration/Consent', '10.2.1'

Install

$ pod install

Receive an APPLICATION_NAME for the app, where you would like to collect consent from users. Set the application name:

Set application name

YLConsent.instance.setAppName(appName: "APPLICATION_NAME")

2.2 Swift Package Manager SPM

Follow the instructions here: iOS integration documentation | 4.2. Swift Package Manager (SPM) integration

Add the Core and Consent procuts to your Target, as pictured. (YieldloveAdIntegration & YieldloveAdIntegration_Consent)

Click Add Package.

Receive an APPLICATION_NAME for the app, where you would like to collect consent from users. Set the application name:

Set application name

YLConsent.instance.setAppName(appName: "APPLICATION_NAME")

NOTE: When integrating via SPM, import both YieldloveAdIntegration and YieldloveAdIntegration_Consent. you need both for the Consent features to work.

3. Simple Consent Message

Simple Consent Message displays a view that contains legal information about how user data are collected and handled. It has two buttons, “Accept All” and “Manage My Options” (exact wording may vary and may appear translated).

To collect consent in this manner call YLConsent.instance.collect()

Collect consent in Swift

import YieldloveAdIntegration
// ...

YLConsent.instance.setAppName(appName: "APPLICATION_NAME")
let viewController = UIViewController()
YLConsent.instance.collect(viewController: viewController, delegate: self)

// or with AuthId
let options = ConsentOptions()
options.authId = "uniqueAuthId"
YLConsent.instance.collect(viewController: self, delegate: self, options: options)

// or with language setting
let myOptions = ConsentOptions()
myOptions.language = .German
YLConsent.instance.collect(viewController: self, delegate: self, options: myOptions)

To react to user actions and manage your app UI use a class that implements ConsentDelegate protocol and listen for onConsentReady(consents: SPUserData) callback. To use this method please import ConsentViewController. If it returns, a consent has been given, and app can resume; it will also contain the consent information returned by SourcePoint. See Reacting to App User Actions for details on how to implement this. Pass ConsentDelegate as second argument to YLConsent.instance.collect().

NOTE: Depending on settings of CMP feature for your app, which are done outside the SDK, Simple Consent Message might not appear if consent has already been given by the user in the past. In such case, calling this method again after consent was provided will NOT show the Simple Consent Message.

4. Privacy Manager

Privacy Manager displays a more detailed view, where user can consent to individual purposes of their data collection and handling, and choose to share their data with specific vendors. Usually it is the same view that is also accessible using “Manage My Options” button in the Simple Consent Message view.

To display Privacy Manager call YLConsent.instance.showPrivacyManager()

Display Privacy manager in Swift

import YieldloveAdIntegration

// ...

YLConsent.instance.setAppName(appName: "APPLICATION_NAME")
let viewController = UIViewController()
YLConsent.instance.showPrivacyManager(viewController: viewController, delegate: consentDelegate)

// or with language setting
let myOptions = ConsentOptions()
myOptions.language = .German
YLConsent.instance.showPrivacyManager(viewController: self, delegate: self, options: myOptions)

To react to users actions and manage your app UI use a class that implements ConsentDelegate protocol and listen for onConsentReady(consents: SPUserData) callback. To use this method please import ConsentViewController. If it returns, a consent has been given, and app can resume; it will also contain the consent information returned by SourcePoint. See Reacting to App User Actions for details on how to implement this. Pass ConsentDelegate as a second argument to YLConsent.instance.showPrivacyManager().

5. Support for PUR layer

To show PUR layer, pass variant parameter into ConsentOptions object and call collect() or showPrivacyManager(). Ask publisher account management for the value of this property.

Pass variant to Privacy manager

import YieldloveAdIntegration

// ...

let options = ConsentOptions()
options.variant = "purLayer" // example, not real value
YLConsent.instance.showPrivacyManager(viewController: self, delegate: self, options: options)

Passing a variant will display a different view in the CMP. App will still get notifications through the consentDelegate, as if it was a usual simple message or privacy manager flow.

6. Reacting to App User Actions

After user makes their choices “dismiss” method is called by the SDK on the view controller that was passed into the API call:

Dismiss method signature

func dismiss(animated flag: Bool, completion: (() -> Void)? = nil)

with values dismiss(animated: true, completion: nil)

This dismisses the view controller that was presented modally and causes the view to disappear, allowing user to carry on using your app. If you do not present the Simple Consent Form or Privacy Manager modally, in a “pop-up” kind of way, you may need to navigate the user back to some other view after they make their choices.

To do this, have a class implement ConsentDelegate protocol, specifically onSPUIFinished() method. SDK will call this method every time the user finishes making their choices, either using Simple Consent Message or Privacy Manager.

For example:

ConsentDelegate implementation in Swift

import UIKit
import YieldloveAdIntegration

class AppConsentDelegate: ConsentDelegate {

    var viewRouter: ViewRouter

    init(viewRouter: ViewRouter) {
        self.viewRouter = viewRouter
    }

    func onSPUIFinished() {
        self.viewRouter.currentPage = "homeScreen"
    }

    func onError(error: ConsentError?) {
        print("Consent Error: \(error.debugDescription)")
        self.viewRouter.currentPage = "homeScreen"
    }
}

Then pass this class into the delegate property to the API calls. For example:

Collect consent with delegate

let delegate = AppConsentDelegate(viewRouter: viewRouter)
YLConsent.instance.collect(viewController: viewController, delegate: delegate)

or

Show Privacy manager with delegate

...
let delegate = AppConsentDelegate(viewRouter: viewRouter)
YLConsent.instance.showPrivacyManager(viewController: viewController, delegate: delegate)

Currently the SDK implements the following delegate methods (listeners):

Delegate methods

import ConsentViewController

// called when the consent view is ready to show
public func onSPUIReady()

// called when the consent view has been dismissed
public func onSPUIFinished()

// called when consent is available
public func onConsentReady(consents: SPUserData)

// called when something wrong happens in the consent view
public func onError(error: ConsentError?)

/// called when the user takes an action in the SP UI
public func onAction(action: SPAction)

Additionally, onAction(action: SPAction) can be called where action is one of:

case SaveAndExit = 1
case PMCancel = 2
case Custom = 9
case AcceptAll = 11
case ShowPrivacyManager = 12
case RejectAll = 13
case Dismiss = 15
case RequestATTAccess = 16
case IDFAAccepted = 17
case IDFADenied = 18
case Unknown = 0

7. Clear Consent

To clear a previously stored consent this method is available:

Clear a previously stored consent

...
let delegate = AppConsentDelegate(viewRouter: viewRouter)
clearConsentData(delegate: delegate)
...

7.1. Programmatically consenting a user

This API method is forwarding to the SourcePoint method customConsentTo. The ids passed will be appended to the list of already accepted vendors, categories and leg. int. categories. The method is asynchronous so you must pass a completion handler that will receive back an instance of GDPRUserConsent in case of success or it’ll call the delegate method onError in case of failure.

It’s important to notice, this method is intended to be used for custom vendors and purposes only. For IAB vendors and purposes, it’s still required to get consent via the consent message or privacy manager.

import YieldloveAdIntegration

...

let customConsentData = CustomConsentData(
    vendors: ["vendor1", "vendor2"],
    categories: ["cat1", "cat2"],
    legIntCategories: ["legacyCat1", "legacyCat2"]
)

YLConsent.instance.customConsentTo(
    customConsentData,
    completionHandler: { gdprUserConsent in
        // your code for the callback
    },
    delegate: delegate
)

Please refer to the original manual in the SourcePoint documentation for more information

7.2. Authenticated Consent

If you want to use Authenticated Consent feature, pass authId parameter into ConsentOptions object and call collect().

Authenticated consent

let options = ConsentOptions()
options.authId = "uniqueAuthId"
YLConsent.instance.collect(viewController: self, delegate: self, options: options)

Currently we do not support Authenticated consent for the Privacy manager flow. Even though is it possible to specify authId in ConsentOptions, calling showPrivacyManager(: UIViewController, : ConsentDelegate, : ConsentOptions?) will not cause authenticated consent to be used.