Getting started

Ogury Choice Manager handles user consent collection and storage for all your vendors, with a simple integration, ensuring compliance with the US Privacy initiatives and GDPR regulation. Your users are shown a single consent notice giving them the choice of the data they want to share, if any.

As an IAB Transparency and Consent Framework (TCF) and IAB California Consumer Privacy Act (CCPA) approved solution, Ogury Choice Manager not only meets the letter of the law, but is also aligned with all relevant best practice standards.

But where other solutions draw the line here, Ogury Choice Manager goes one step further by incorporating vendors that fall outside of IAB jurisdiction, including Facebook and Google. The net result is a definitive, one-stop consent notice that covers most vendors available on the market today.

Step 1: Register your application

The Asset Key follows the pattern: OGY-XXXXXXXXXXXX, where X is an uppercase letter or digit. In all the following code samples, we will refer to this Asset Key by using the string ASSET_KEY.

Step 2: Import the Ogury SDK

To import the latest version of the Ogury SDK into your project, Ogury provides two methods:

  • Automated integration using Ogury's CocoaPods repository (recommended).

  • Manual integration of the Ogury SDK.

CocoaPods
Manual integration
CocoaPods

Configure your Podfile

Open the podfile of your application and add the following lines into your target:

pod 'OguryChoiceManager'

If you are using Xcode 12+, please use CocoaPods 1.10+ to avoid build errors due to the migration of our SDK to XCFramework.

To know more about the latest release of the Ogury SDK, you can check the release notes.

Manual integration

Download the Ogury SDK

Configure your IDE

Drag the following Frameworks into your Xcode project:

  • OguryChoiceManager.framework

Check if the frameworks are added to Linked Frameworks and Libraries on Target properties under General Tab of your project

To know more about the latest release of the Ogury SDK, you can check the release notes.

Step 3: Configure your application

In your project Build Settings, do the following changes:

  • add the -ObjC flag to Other Linker Flags.

Step 4: Setup Choice Manager

In order to use OguryChoiceManager you have to setup the SDK first. This method must be called before any other Choice Manager method. We recommend to call setup in AppDelgeate class, function didFinishLaunchingWithOptions before starting any UIViewController.

You can call the setup method as follows:

Swift
Objective-C
Swift
let config = OguryChoiceManagerConfig.default()
OguryChoiceManager.shared().setup(withAssetKey: "ASSET_KEY", andConfig: config)
Objective-C
OguryChoiceManagerConfig * config = [OguryChoiceManagerConfig defaultConfig];
[[OguryChoiceManager sharedManager] setupWithAssetKey:@"ASSET_KEY" andConfig:config];

The setup method takes the following parameters:

  • the Asset Key of your application. If you do not have one, please refer to the first step.

  • anOguryChoiceManagerConfig object, needed to pass versions of frameworks that should be used in SDK. If you instantiate it with default() then TCF version 2 will be used, but there is an option to pass the parameter to the constructor to setup Choice Manager for needed TCF version.

Step 5: Get the user consent

To collect the user consent for the all registered vendors, call the ask method in the viewDidLoad of your ViewController.

This method displays a consent notice allowing the user to choose with which vendors and purposes they agree to share data. This notice is only displayed when there is no existing consent status for this user. Otherwise the ask method synchronizes the consent signal and makes it available through the SDK methods.

You can call the ask method as follows:

Swift
Objective-C
Swift
OguryChoiceManager.shared().ask(with: viewController) { (error, response) in
}
Objective-C
[[OguryChoiceManager sharedManager] askWithViewController:viewController andCompletionBlock:^(NSError *error, OguryChoiceManagerAnswer answer) {
}];

The ask method takes the following parameters:

  • the current ViewController

  • a completionBlock to listen to changes of the consent signal. This completion block provides two parameters :

Parameters

Definition

response

A consent notice has been displayed to the user or the consent status has been synchronized. The next steps go through how to handle the user consent with your vendors' SDKs.

error

An error occurred. In this case, nothing is displayed to the user and the consent status is not synchronized. Learn more about consent error handling.

Theask method must be called at each launch of your application to be sure to have an up-to-date consent status. Pay attention to call setup prior to calling ask.

Integration example

Swift
Objective-C
Swift
import UIKit
import OguryChoiceManager
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
//Setup SDK
let config = OguryChoiceManagerConfig.default()
OguryChoiceManager.shared().setup(withAssetKey: "ASSET_KEY", andConfig: config)
// get user consent
OguryChoiceManager.shared().ask(with: self) { (error, response) in
// will serve ads when the user consents
}
}
}
Objective-C
#import <OguryChoiceManager/OguryChoiceManager.h>
@interface ViewController : UIViewController
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
//Setup SDK
OguryChoiceManagerConfig *config = [OguryChoiceManagerConfig defaultConfig];
[[OguryChoiceManager sharedManager] setupWithAssetKey:@"ASSET_KEY" andConfig:config];
// get user consent
[[OguryChoiceManager sharedManager] askWithViewController:self andCompletionBlock:^(NSError *error, OguryChoiceManagerAnswer answer) {
// will serve ads when the user consents
}];
}
@end

Step 6: Allow users to edit their consent

As per the GDPR regulation, publishers need to ensure the users can access and edit their consent choices through their application at any time.

The edit method forces the display of the consent notice and let users update their choices. If an error occurred, nothing is displayed to the user. In this case, you need to handle the error to inform the user.

Swift
Objective-C
Swift
OguryChoiceManager.shared().edit(with: viewController) { (error, response) in
}
Objective-C
[[OguryChoiceManager sharedManager] editWithViewController:viewController andCompletionBlock:^(NSError *error, OguryChoiceManagerAnswer answer) {
}];

The edit method takes the following parameters:

  • the current ViewController

  • a completionBlock to listen to changes of the consent signal. This completion block provides two parameters :

Parameters

Definition

response

A consent notice has been displayed to the user or the consent status has been synchronized. The next steps go through how to handle the user consent with your vendors' SDKs.

error

An error occurred. In this case, nothing is displayed to the user and the consent status is not synchronized. Learn more about consent error handling.

We recommend to expose a button to edit the consent in the application settings.

Step 7: Transmit the consent to vendors' SDKs

There are several options to access and pass the consent signal to your partners, with a precise status on each vendor and purpose. You can get and transmit the IAB string if your vendor's SDK is able to handle it, as the IAB string contains the complete consent signal. Alternatively, you can check the list of vendors and/or purposes that were accepted by the user and transmit that specific information.

Transmit the IAB string

The consent signal is stored in a specific UserDefaults and is automatically passed to the vendors supporting the IAB Transparency and Consent Framework (TCF).

While being registered to the IAB TCF, some vendors need to explicitly receive the IAB string. Check with your vendors to ensure that they process the consent signal by themselves. Otherwise, you can use the following method to obtain and pass the IAB string:

Swift
Objective-C
Swift
OguryChoiceManager.shared().tcfV2.getIABConsentString()
Objective-C
[[[OguryChoiceManager sharedManager] tcfV2] getIABConsentString];

We recommend to use this method only in the completion block of the ask andedit methods to get the updated value of the consent signal.

If there is no consent signal for a given user, this method returns an empty string as default value. In this case, you should start the vendor's SDK as if the user had not provided their consent. The consent notice will be displayed at the next ask call, and the consent status will then be updated.

Depending on the user consent choices, you may need to enable/disable some functionalities or vendor's SDK. You can check whether the user has accepted the usage of personal data for a particular vendor by calling the following method:

Swift
Objective-C
Swift
OguryChoiceManager.shared().tcfV2.isAccepted(vendorId)
Objective-C
[[[OguryChoiceManager sharedManager] tcfV2] isAccepted:vendorId];

The isAccepted method takes the following parameter:

  • a vendorId integer which uniquely identifying each vendor. As an example, the vendor id is 277 for Ogury. You can find the list of all vendor ids in the Ogury Choice Manager vendor list.

Note that you can identify yourself as a vendor if you need specific consent for some use cases involving personal data. In this case, you first need to add yourself as a vendor in the consent notice, and then use the vendor id 0 in the isAccepted method.

We recommend to use this method only in the completion block of the ask and edit methods to get the updated value.

If there is no consent signal for a given user, this method returns falseas default value. In this case, you can start the vendor's SDK as if the user had not provided their consent. The consent notice will be displayed at the next ask call and the consent status will then be updated.

Similarly to vendors, you can access consent status for each IAB purposes, and pass this signal to your vendors and your own processes accordingly. Users can consent to all purposes at once or opt-in to only a few of them.

You can check whether the user has accepted to share their data for a given purpose by calling the following method:

Swift
Objective-C
Swift
OguryChoiceManager.shared().tcfV2.isPurposeAccepted(purpose)
Objective-C
[[[OguryChoiceManager sharedManager] tcfV2] isPurposeAccepted: purpose];

The isPurposeAccepted method takes the following parameter:

  • a OguryChoiceManagerPurpose representing a purpose. It can take one of the following values:

Purpose values

IAB purpose names

OguryChoiceManagerPurposeStoreInformation

Information storage and access

OguryChoiceManagerPurposeSelectBasicAds

Select basic ads

OguryChoiceManagerPurposeCreatePersonalisedAds

Create personalised ads

OguryChoiceManagerPurposeSelectPersonalisedAds

Select personalised ads

OguryChoiceManagerPurposeCreatePersonalisedContent

Create personalised content

OguryChoiceManagerPurposeSelectPersonalisedContent

Select personalised content

OguryChoiceManagerPurposeMeasureAdPerformance

Measure ad performance

OguryChoiceManagerPurposeMeasureContentPerformance

Measure content performance

OguryChoiceManagerPurposeMarketResearch

Market research

OguryChoiceManagerPurposeDevelopAndImproveProducts

Develop and improve products

We recommend to use this method only in the completion block of the ask and edit methods to get the updated value.

If there is no consent signal for a given user, this method returns falseas default value. In this case, you can start the vendor's SDK as if the user had not provided their consent. The consent notice will be displayed at the next ask call and the consent status will then be updated.

Transmit purpose and vendor specific status for a particular vendor

Depending on users consent choices you can check status for a particular vendor and all IAB purposes declared under Consent by that vendor to, for example enable/disable that vendor’s SDK.

You can check whether all consent based purposes declared by this vendor are accepted by the user along with the vendor itself.

Swift
Objective-C
Swift
OguryChoiceManager.tcfV2.isVendorAndItsPurposesAccepted(vendorId);
Objective-C
[[[OguryChoiceManager sharedManager] tcfV2] isVendorAndItsPurposesAccepted: vendorId];

The isVendorAndItsPurposesAccepted method takes the following parameter:

  • a vendorId integer which uniquely identifying each vendor. As an example, the vendor id is 277 for Ogury. You can find the list of all vendor ids in the Ogury Choice Manager vendor list.

Note that you can identify yourself as a vendor if you need specific consent for some use cases involving personal data. In this case, you first need to add yourself as a vendor in the consent notice, and then use the vendorId 0 in the isVendorAndItsPurposesAccepted method.

We recommend to use this method only in the completion block of the ask and edit methods to get the updated value.

If there is no consent signal for a given user, this method returns falseas default value. In this case, you can start the vendor's SDK as if the user had not provided their consent. The consent notice will be displayed at the next ask call and the consent status will then be updated.

Integration example

Find below an example of user consent handling for several vendors.

Swift
Objective-C
Swift
import UIKit
import OguryChoiceManager
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
// you can initialize SDK here or in AppDelegate
let config = OguryChoiceManagerConfig.default()
OguryChoiceManager.shared().setup(withAssetKey: "ASSET_KEY", andConfig: config)
// get user consent
OguryChoiceManager.shared().ask(with: self) { (error, response) in
// pass user consent to vendors' SDKs
self.passConsentToVendorSdks()
}
}
func passConsentToVendorSdks() {
// pass consent through IAB string
let iabString = OguryChoiceManager.shared().tcfV2.getIABConsentString()
vendorSdk.setConsentFromIABString(iabString)
// check if a vendor is accepted
let vendorAccepted = OguryChoiceManager.shared().tcfV2.isAccepted(vendorId)
anotherVendorSdk.setConsent(vendorAccepted)
// check consent for yourself and for your analytics solution
let meAccepted = OguryChoiceManager.shared().tcfV2.isAccepted(yourVendorId)
let analyticsVendorAccepted = OguryChoiceManager.shared().tcfV2.isAccepted(analyticsVendorId)
// for analytics we check the MEASUREMENT purpose
let measurementPurposeAccepted = OguryChoiceManager.shared().tcfV2.isPurposeAccepted(.measureAdPerformance)
analyticsSdk.setConsent(meAccepted && analyticsVendorAccepted && measurementPurposeAccepted)
}
}
Objective-C
#import <OguryChoiceManager/OguryChoiceManager.h>
@interface ViewController : UIViewController
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
// you can initialize SDK here or in AppDelegate
OguryChoiceManagerConfig *config = [[OguryChoiceManagerConfig defaultConfig];
[[OguryChoiceManager sharedManager] setupWithAssetKey:@"ASSET_KEY" andConfig:config];
// get user consent
[[OguryChoiceManager sharedManager] askWithViewController:self andCompletionBlock:^(NSError *error, OguryChoiceManagerAnswer answer) {
// pass user consent to vendors' SDKs
[self passConsentToVendorSdks];
}];
}
- (void) passConsentToVendorSdks {
// pass consent through IAB string
NSString *iabString = [[[OguryChoiceManager sharedManager] tcfV2] getIABConsentString];
[vendorSdk setConsentFromIABString:iabString];
// check if a vendor is accepted
BOOL vendrAccepted = [[[OguryChoiceManager sharedManager] tcfV2] isAccepted:vendorId];
[anotherVendorSdk setConsent:vendrAccepted];
// check consent for yourself and for your analytics solution
BOOL meAccepted = [[[OguryChoiceManager sharedManager] tcfV2] isAccepted:yourVendorId];
BOOL analyticsVendorAccepted = [[[OguryChoiceManager sharedManager] tcfV2] isAccepted:analyticsVendorId];
// for analytics we check the MEASUREMENT purpose
BOOL mesurementPurposeAccepted = [[[OguryChoiceManager sharedManager] tcfV2] isPurposeAccepted:OguryChoiceManagerPurposeMeasureContentPerformance];
[analyticsSdk setConsent:meAccepted && analyticsVendorAccepted && mesurementPurposeAccepted];
}
@end

Step 8: Initialize vendors' SDKs

You are ready to initialize vendors' SDKs and load ad formats. You should initialize them in the completion block of the ask method to have the user consent for the first ad impression.

Integration example

Swift
Objective-C
Swift
import OguryChoiceManager
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
// you can initialize SDK here or in Application.onCreate() method
let config = OguryChoiceManagerConfig.default()
OguryChoiceManager.shared().setup(withAssetKey: "ASSET_KEY", andConfig: config)
// get user consent
OguryChoiceManager.shared().ask(with: self) { (error, response) in
// pass user consent to vendors' SDKs
self.passConsentToVendorSdks()
// initialize vendors' SDKs
self.startSdks()
// load ad formats
self.loadAdFormats()
}
}
func passConsentToVendorSdks() {
// pass consent through IAB string
let iabString = OguryChoiceManager.shared().tcfV2.getIABConsentString()
vendorSdk.setConsentFromIABString(iabString)
// check if a vendor is accepted
let vendorAccepted = OguryChoiceManager.shared().tcfV2.isAccepted(vendorId)
anotherVendorSdk.setConsent(vendorAccepted)
// check consent for yourself and for your analytics solution
let meAccepted = OguryChoiceManager.shared().tcfV2.isAccepted(yourVendorId)
let analyticsVendorAccepted = OguryChoiceManager.shared().tcfV2.isAccepted(analyticsVendorId)
// for analytics we check the MEASUREMENT purpose
let measurementPurposeAccepted = OguryChoiceManager.shared().tcfV2.isPurposeAccepted(.measureAdPerformance)
analyticsSdk.setConsent(meAccepted && analyticsVendorAccepted && measurementPurposeAccepted)
}
func startSdks() {
// call the start methods of vendors' SDKs
vendorSdk.start()
anotherVendorSdk.start()
analyticsSdk.start()
}
func loadAdFormats() {
// load ad formats
yourAdFormat.load();
}
}
Objective-C
#import <OguryChoicetManager/OguryChoiceManager.h>
@interface ViewController : UIViewController
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
// you can initialize SDK here or in AppDelegate
OguryChoiceManagerConfig *config = [[OguryChoiceManagerConfig defaultConfig];
[[OguryChoiceManager sharedManager] setupWithAssetKey:@"ASSET_KEY" andConfig:config];
// get user consent
[[OguryChoiceManager sharedManager] askWithViewController:self andCompletionBlock:^(NSError *error, OguryChoiceManagerAnswer answer) {
// pass user consent to vendors' SDKs
[self passConsentToVendorSdks];
// initialize vendors' SDKs
[self startSdks];
// load ad formats
[self loadAdFormats];
}];
}
- (void) passConsentToVendorSdks {
// pass consent through IAB string
NSString *iabString = [[[OguryChoiceManager sharedManager] tcfV2] getIABConsentString];
[vendorSdk setConsentFromIABString:iabString];
// check if a vendor is accepted
BOOL vendrAccepted = [[[OguryChoiceManager sharedManager] tcfV2] isAccepted:vendorId];
[anotherVendorSdk setConsent:vendrAccepted];
// check consent for yourself and for your analytics solution
BOOL meAccepted = [[[OguryChoiceManager sharedManager] tcfV2] isAccepted:yourVendorId];
BOOL analyticsVendorAccepted = [[[OguryChoiceManager sharedManager] tcfV2] isAccepted:analyticsVendorId];
// for analytics we check the MEASUREMENT purpose
BOOL mesurementPurposeAccepted = [[[OguryChoiceManager sharedManager] tcfV2] isPurposeAccepted:OguryChoiceManagerPurposeMeasureContentPerformance];
[analyticsSdk setConsent:meAccepted && analyticsVendorAccepted && mesurementPurposeAccepted];
}
- (void)startSdks {
// start vendors' SDKs
[vendorSdk start];
[anotherVendorSdk start];
[analyticsSdk start];
}
- (void)loadAdFormats {
// load ad formats
[yourAdFormat load];
}
@end