Getting started

Ogury Choice Manager handles user consent collection and storage for all your vendors, with a simple integration, ensuring compliance with the 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) 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:

  • the Asset Key of the Android application by using the string ANDROID_ASSET_KEY

  • the Asset Key of the iOS application by using the string IOS_ASSET_KEY.

Step 2: Import the Ogury SDK

To import the latest version of the Ogury SDK Cordova plugin into your project, Ogury provides a ZIP archive containing the Cordova plugin.

Download the Cordova Plugin

Import the Ogury SDK into your project

  • Unzip the archive.

  • Open a command prompt or terminal window at the root of your project.

  • Run the following command to add Ogury SDK to your project:

Cordova
Phonegap
Ionic platform
Cordova
cordova plugin add <path to unzipped archive>/cordova-plugin-ogury-choicemanager
Phonegap
phonegap plugin add <path to unzipped archive>/cordova-plugin-ogury-choicemanager
Ionic platform
ionic plugin add <path to unzipped archive>/cordova-plugin-ogury-choicemanager

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

Step 3: Initialize Choice Manager

For proper way to use Choice Manager first you need to call initialize method. This method must be called before any other Choice Manager method. Recommendation is to do initialization of Choice Manager in then onDeviceReady() method, when the deviceReady is dispatched. Pay attention to call it prior to calling any other method from the SDK.

function getAssetKey(){
let platform = device.platform;
let assetkey;
if (platform == "Android") {
return assetkey = "ANDROID_ASSET_KEY";
} else if (platform == "iPhone" || platform == "iPad" || platform == "iPhone Simulator" || platform == "iPad Simulator" || platform == "iOS") {
return assetkey = "IOS_ASSET_KEY";
}
}
onDeviceReady: function() {
OguryChoiceManager.TCFV2.initialize(getAssetKey());
}

The initialize method takes the following parameter:

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

Step 4: Get the user consent

To collect the user consent for the all registered vendors, call the ask method in the onDeviceRedy method.

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:

OguryChoiceManager.ask(onConsentEvent, onErrorEvent);

The ask method takes the following parameters:

  • anonConsentEvent callback to listen to changes of the consent signal

  • anonErrorEvent callback to listen to any errors that might appear

Methods

Definition

onConsentEvent

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.

onErrorEvent

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 initialize prior to calling ask.

Integration example

function getAssetKey(){
let platform = device.platform;
let assetkey;
if (platform == "Android") {
return assetkey = "ANDROID_ASSET_KEY";
} else if (platform == "iPhone" || platform == "iPad" || platform == "iPhone Simulator" || platform == "iPad Simulator" || platform == "iOS") {
return assetkey = "IOS_ASSET_KEY";
}
}
function onConsentEvent(answer){
//...
}
function onErrorEvent(consentError){
//...
}
onDeviceReady: function() {
app.receivedEvent('deviceready');
//...
OguryChoiceManager.TCFV2.initialize(getAssetKey());
OguryChoiceManager.ask(onConsentEvent, onErrorEvent);
}

Step 5: 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.

OguryChoiceManager.edit(onConsentEvent, onErrorEvent);

The edit method takes the following parameters:

  • anonConsentEvent callback to listen to changes of the consent signal

  • anonErrorEvent callback to listen to any errors that might appear

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

Step 6: 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 SharedPreferences on Android;

  • a specific UserDefaults on iOS.

It 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:

OguryChoiceManager.TCFV2.getIabString().then(function(IABString){
//...
});

We recommend to use this method only in the onConsentEvent callback 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:

OguryChoiceManager.TCFV2.isAccepted(vendorId).then(function(isVendorAccepted){
//...
});

The isAccepted method takes the following parameter:

  • a vendorId integer, 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 in the isAccepted method.

We recommend to use this method only in theonConsentEvent callbacks 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 or more than one purpose by calling the method isPurposeAccepted. You can check for single and for multiple purposes.

Check single purpose

OguryChoiceManager.TCFV2.isPurposeAccepted(purposeInt).then(function(isPurposeAccepted){
//...
});

The isPurposeAccepted method takes the following parameter:

  • a purposeInt is integer value identifies a purpose.

Check multiple purposes

OguryChoiceManager.TCFV2.isPurposeAccepted(purposeInt).then(function(isPurposeAccepted){
//...
});

The isPurposeAccepted method takes the following parameter:

  • a purposesInt is integer value identifies a group of purposes. If you want to check if there is more than one purpose accepted you can pass sum of values of that purposes. You should use predefined values from our SDK.

The purposes you can use are Int numbers and you can pass it alone for single purpose check or as a sum of few of them for multiple purposes check. They are located in the OguryChoiceManager.Purposes.TCFV2, so when you want to use for example SELECT_BASIC_ADS, it should looks like this OguryChoiceManager.Purposes.TCFV2.SELECT_BASIC_ADS.

Purpose values can take one of the following values (or sum of them):

Purpose values

IAB purpose names

STORE_INFORMATION

Information storage and access

SELECT_BASIC_ADS

Select basic ads

CREATE_PERSONALIZED_ADS

Create personalized ads

SELECT_PERSONALIZED_ADS

Select personalized ads

CREATE_PERSONALIZED_CONTENT

Create personalized content

SELECT_PERSONALIZED_CONTENT

Select personalized content

MEASURE_AD_PERFORMANCE

Measure ad performance

MEASURE_CONTENT_PERFORMANCE

Measure content performance

MARKET_RESEARCH

Market research

DEVELOP_AND_IMPROVE_PRODUCTS

Develop and improve products

You can call a method as followed to check if one purpose is accepted:

OguryChoiceManager.TCFV2.isPurposeAccepted(OguryChoiceManager.Purposes.TCFV2.SELECT_BASIC_ADS)
.then(function(isPurposeAccepted){
//...
});

You can call a method as followed to check if more than one purposes are accepted:

OguryChoiceManager.TCFV2.isPurposeAccepted(OguryChoiceManager.Purposes.TCFV2.SELECT_BASIC_ADS
|OguryChoiceManager.Purposes.TCFV2.MARKET_RESEARCH)
.then(function(isPurposeAccepted){
//...
});

We recommend to use this method only in the onConsentEvent callback 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.

OguryChoiceManager.TCFV2.isVendorAndItsPurposesAccepted(vendorId)
.then(function(isPurposeAccepted){
//...
});

The isVendorAndItsPurposesAccepted method takes following parameter:

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.

Integration example

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

function getAssetKey(){
let platform = device.platform;
let assetkey;
if (platform == "Android") {
return assetkey = "ANDROID_ASSET_KEY";
} else if (platform == "iPhone" || platform == "iPad" || platform == "iPhone Simulator" || platform == "iPad Simulator" || platform == "iOS") {
return assetkey = "IOS_ASSET_KEY";
}
}
onDeviceReady: function() {
app.receivedEvent('deviceready');
OguryChoiceManager.TCFV2.initialize(getAssetKey());
OguryChoiceManager.ask(onConsentEvent,onErrorEvent);
}
function onConsentEvent(answer){
// pass user consent to vendors' SDKs
passConsentToVendorSdks();
}
function onErrorEvent(error){
//pass user consent to vendors' SDKs
passConsentToVendorSdks();
}
function passConsentToVendorSdks(){
Promise.all([OguryChoiceManager.TCFV2.getIabString(),
// check if a vendor is accepted
OguryChoiceManager.TCFV2.isAccepted(vendorId),
OguryChoiceManager.TCFV2.isAccepted(yourVendorId),
OguryChoiceManager.TCFV2.isAccepted(analyticsVendorId),
// for analytics we check the MEASUREMENT purpose
OguryChoiceManager.TCFV2.isPurposeAccepted(
OguryChoiceManager.Purposes.TCFV2.MEASURE_AD_PERFORMANCE),
// this is the other way how you can check if vendor and all its purposes are accepted
OguryChoiceManager.TCFV2.isVendorAndItsPurposesAccepted(analyticsVendorId)])
.then((values) =>{
values = values + ' ';
let resultArr = values.split(',');
// pass consent through IAB string
let iabString = resultArr[0];
vendorSdk.setConsentFromIABString(iabString);
// check if a vendor is accepted
let vendorAccepted = resultArr[1];
anotherVendorSdk.setConsent(vendorAccepted);
// check consent for yourself and for your analytics solution
let meAccepted = resultArr[2];
let analyticsVendorAccepted = resultArr[3];
let measurementPurposeAccepted = resultArr[4];
// this is the other way how you can check if vendor and all its purposes are accepted
let isAnalyticsVendorAndItsPurposesAccepted = resultArr[5];
// instead analyticsVendorAccepted && measurementPurposeAccepted you can put isAnalyticsVendorAndItsPurposesAccepted
analyticsSdk.setConsent(meAccepted && analyticsVendorAccepted && measurementPurposeAccepted);
});
}

Step 7: Initialize vendors' SDKs

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

Integration example

function getAssetKey(){
let platform = device.platform;
let assetkey;
if (platform == "Android") {
return assetkey = "ANDROID_ASSET_KEY";
} else if (platform == "iPhone" || platform == "iPad" || platform == "iPhone Simulator" || platform == "iPad Simulator" || platform == "iOS") {
return assetkey = "IOS_ASSET_KEY";
}
}
onDeviceReady: function() {
app.receivedEvent('deviceready');
OguryChoiceManager.TCFV2.initialize(getAssetKey());
OguryChoiceManager.ask(onConsentEvent,onErrorEvent);
}
function onConsentEvent(answer){
// pass user consent to vendors' SDKs
passConsentToVendorSdks();
// initialize vendors' SDKs
startSdks();
// load ad formats
loadAdFormats();
}
function onErrorEvent(error){
//pass user consent to vendors' SDKs
passConsentToVendorSdks();
// initialize vendors' SDKs
startSdks();
// load ad formats
loadAdFormats();
}
function loadAdFormats(){
// load ad formats
yourAdFormat.load();
}
function startSdks(){
// start vendors' SDKs
vendorSdk.start();
anotherVendorSdk.start();
analyticsSdk.start();
}
function passConsentToVendorSdks(){
Promise.all([OguryChoiceManager.TCFV2.getIabString(),
// check if a vendor is accepted
OguryChoiceManager.TCFV2.isAccepted(vendorId),
// check consent for yourself and for your analytics solution
OguryChoiceManager.TCFV2.isAccepted(yourVendorId),
OguryChoiceManager.TCFV2.isAccepted(analyticsVendorId),
// for analytics we check the MEASUREMENT purpose
OguryChoiceManager.TCFV2.isPurposeAccepted(
OguryChoiceManager.Purposes.TCFV2.MEASURE_AD_PERFORMANCE)])
.then((values) =>{
values = values + ' ';
let resultArr = values.split(',');
// pass consent through IAB string
let iabString = resultArr[0];
// check if a vendor is accepted
let vendorAccepted = resultArr[1];
anotherVendorSdk.setConsent(vendorAccepted);
// check consent for yourself and for your analytics solution
let meAccepted = resultArr[2];
let analyticsVendorAccepted = resultArr[3];
let measurementPurposeAccepted = resultArr[4];
analyticsSdk.setConsent(meAccepted && analyticsVendorAccepted && measurementPurposeAccepted);
});
}