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

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.

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
let config = OguryChoiceManagerConfig.default()
OguryChoiceManager.shared().setup(withAssetKey: "ASSET_KEY", andConfig: config)
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.

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
OguryChoiceManager.shared().ask(with: viewController) { (error, response) in
}
[[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
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
}
}
}
#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

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
OguryChoiceManager.shared().edit(with: viewController) { (error, response) in
}
[[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.

Advanced topics

Check the availability of the edit method

The edit option might not be available and then calling the edit method will return an error in the following cases:
  • if the user is not located in the EU, i.e. not in a country where the GDPR applies;
  • if the user has already paid to access your app using the Fair Choice feature;
  • as a result of a specific configuration on the Ogury Dashboard;
Before displaying the edit button, you should check this option with the following method:
Swift
Objective-C
OguryChoiceManager.shared().editAvailable()
[[OguryChoiceManager sharedManager] editAvailable];
We recommend to use this method once the synchronization triggered by ask method has completed. Otherwise this method returns true by default.

Answer

In the reponse parameter of completion block, you can get the answer of the user through an Answer object. The Answer has one of the following values:
Answer values
Definition
FULL_APPROVAL
The user has approved all vendors and all purposes displayed in the consent notice.
PARTIAL_APPROVAL
The user has approved some vendors and/or some purposes displayed in the consent notice.
REFUSAL
The user has refused all vendors and all purposes displayed in the consent notice.
NO_ANSWER
The user has not responded.

Error handling

If Ogury Choice Manager fails to get the consent signal for any reason during an ask or an edit, the completion block provides an error parameter. This parameter contains the cause of the failure.‌
To get the error code, you can call the following method:
error.code
The error can be one of the following:
Code
Value
Definition
OGYConsentErrorNoInternetConnection
0
The device has no internet connection. Try again when the device is connected to Internet.
OGYConsentErrorTypeNoSuchAssetKey
1
The Asset Key passed in the method is unknown. Make sure to copy the exact Asset Key from the Ogury Dashboard (see the getting started section for more information). It may also occur while new configurations are propagating immediately following the creation of the application.
OGYConsentErrorTypeBundleNotMatching
2
The bundle registered on the Ogury Dashboard does not match the iOS bundle of the running application. Check that you have copied the Asset Key corresponding to the current application from the Ogury Dashboard (see the getting started section for more information).
OGYConsentErrorTypeServerError
3
The server has failed to respond because of an internal error. Please try again.
OGYConsentErrorTypeInternalSDKError
4
An internal SDK error has occurred. Please try again.
OGYConsentErrorTypeRegionRestricted
1000
The device is in a region not allowed to show the consent.
OGYConsentErrorTypeSdkAskNotCalled
1001
The ask method has not been called.
OGYConsentErrorTypeSdkTimeOut
1002
The request has time out.
Please try again.
OGYConsentErrorTypeFormError
1003
Form side error has occurred. Please try again.
OGYConsentErrorTypeParsingError
1004
Data parsing error has occurred. Please try again.
OGYConsentErrorTypeFairChoiceFetchProduct
1005
Error occurred trying to fetch Fair Choice Product from Store.
OGYConsentErrorTypeEditDisabledUserHasPaid
1006
The edit option is disabled because the user has paid.
OGYConsentErrorTypeIOSUserRestricted
1007
iOS user restricted from consent
OGYConsentErrorTypeUserGeoRestricted
1008
The current user is geo-restricted from consent.
OGYConsentErrorTypeSetupNotCalled
1009
The setup method has not been called.
Last modified 1mo ago
Copy link
On this page
Step 1: Register your application
Step 2: Import the Ogury SDK
Step 3: Configure your application
Step 4: Setup Choice Manager
Step 5: Get the user consent
Integration example
Step 6: Allow users to edit their consent
Advanced topics
Check the availability of the edit method
Answer
Error handling