Getting started

As of November 13, 2023, Ogury Choice Manager is deprecated, meaning it will no longer be supported or updated.

Consequently, no new consent notices will be delivered through Ogury Choice Manager's APIs. Therefore, it is strongly advised against using Ogury Choice Manager in new versions of applications. In case you have migrated to a new Consent Management Platform (CMP), ensure that Ogury and its partners are included as vendors.

For earlier versions of applications still using Ogury Choice Manager, the API will maintain its functionality, continuing to return consent for users who have previously responded to a consent notice. This will remain in effect until their consent expires.

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.

Also, Ogury Choice Manager facilitates CCPA compliance by IAB California Consumer Privacy Act (CCPA) framework.

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 applications

• Create an account on the Ogury Dashboard.

In case you publish your application on both Android and iOS, you should do the following steps twice, once for the Android application and once for the iOS application. Otherwise just select the platform you publishes for.

• Go to your Dashboard and register your application.

• Copy the Asset Key from the Asset details, as shown in the screenshot below:

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 into your project, Ogury provides a Unity Package.

Download the Unity Package

• Download the latest Ogury SDK Unity Package.

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

If you are upgrading to the latest version of the Ogury SDK, make sure to first delete the OgurySdk folder in your project Assets folder before following next steps.

Import the Unity Package into your project

• Open your Unity Project.

• Choose Assets > Import Package > Custom Package.

• In the file explorer, select the package you have downloaded. The Import Unity Package dialog box appears, with all the items in the package checked.

• Click on Import . The package content is added to the Assets folder

The Ogury Unity SDK uses External Dependency Manager for Unity to download some dependencies. You can use the version already imported in your project and ignore the PlayServicesResolver folder during import in case of conflict.

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

Import Ogury SDK namespace into your scripts

• Import the OgurySdk namespace at the beginning of every script where you interacts with the Ogury SDK.

using OgurySdk;

Step 3: Create OguryCallbacks game object

In the first scene of your application:

• Right-click in the Hierarchy panel and click on Create Empty option.

• Select the new GameObject.

• In the Inspector panel:

  • Rename it to OguryCallbacks.

  • Click on Add Component button and search for Ogury Callbacks script.

Step 4: Initialize Ogury SDK

Before calling any method of the Ogury SDK, you must configure the Asset Key as following:

Ogury.Start("ANDROID_ASSET_KEY", "IOS_ASSET_KEY");

The Start method takes the following parameter:

• the Asset Key of your application for the Android platform. You can use null if your application is not available on Android.

• the Asset Key of your application for the iOS platform. You can use null if your application is not available on iOS.

If you do not have any Asset Key yet, you can refer to the first step to create them.

Step 5: Get the user consent

To collect the user consent for the all registered vendors, call the Ask method in the Start of your first scene.

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 method as follows:

OguryChoiceManager.Ask();

You can register to following events, before calling the Ask method, to receive the consent status of the user:

Events	Definition
OnAskComplete	A consent notice has been displayed to the user or the consent status has been synchronized. You can handle the status of the consent to use it with vendors' SDKs. Learn more about user consent handling.
OnAskError	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.

The Ask 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 the Start method prior to calling the Ask method.

Integration example

using OgurySdk;

public class MyScene : MonoBehaviour {

    void Start() {
        Ogury.Start("ANDROID_ASSET_KEY", "IOS_ASSET_KEY");
        
        // implement choice manager events
        OguryChoiceManager.OnAskComplete += OnCMComplete;
        OguryChoiceManager.OnAskError += OnCMError;
        
        // get user consent
        OguryChoiceManager.Ask();
    }
    
    private void OnDestroy() {
        OguryChoiceManager.OnAskComplete -= OnCMComplete;
        OguryChoiceManager.OnAskError -= OnCMError;
    }
    
    private void OnCMComplete(OguryChoiceManager.Answer answer) {
        // will serve personalized or non-personalized ads, depending on the answer
    }

    private void OnCMError(OguryError error) {
        // will serve non-personalized ads
    }
}

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.

OguryChoiceManager.Edit();

You can register to following events, before calling the Edit method, to receive the consent status of the user:

Events	Definition
OnEditComplete	A consent notice has been displayed to the user or the consent status has been synchronized. You can handle the status of the consent to use it with vendors' SDKs. Learn more about user consent handling.
OnEditError	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: Handle the user consent

‌After you have obtained the user consent, you are able to handle it according to your needs:

• Transmit the user consent to your partner's SDKs processing user data;

• You are under the CCPA, use the Ogury's CCPA API;

• Implement the Fair Choice functionality.

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

OguryChoiceManager.EditAvailable;

Answer

In the onComplete method of the OguryConsentListener interface, you can get the answer of the user through theAnswer 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 onError method of the OguryConsentListener is called. This method provides an OguryError object that contains an error code and an error message.

To get the error code, you can call the getErrorCode. You can retrieve a more explicit message by calling the getMessage method.

You can find predefined values for each error code in OguryChoiceManagerErrorCode object. For example, you can check if error occurred because there is no Internet connection by usingNO_INTERNET_CONNECTION error code as following:

if (error.getErrorCode() == OguryChoiceManagerErrorCode.NO_INTERNET_CONNECTION) {
    // ...
}

Here is the list of all error codes in OguryChoiceManagerErrorCode object:

Name	Value	Definition
NO_INTERNET_CONNECTION	0	No Internet connection The device has no Internet connection. Try again once the device is connected to the Internet.
ASSET_KEY_UNKNOWN	1	Asset Key unknown 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 configuration are propagating immediately following the creation of the application.
BUNDLE_NOT_MATCHING	2	Bundle not matching The bundle registered on the Ogury Dashboard does not match the Android package 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).
SERVER_NOT_RESPONDING	3	Server not responding The server has failed to respond because of an internal error. Please try again.
SYSTEM_ERROR	4	System error The SDK has encountered an internal error. Please try again.
REGION_RESTRICTED	1000	Region restricted The user is in the restricted region.
TIMEOUT_ERROR	1002	Timeout error Timeout error happened while waiting for the response. See the error message for more details.
FORM_ERROR	1003	Form error The error occurs when trying to show Consent notice. See the error message for more details.
PARSING_ERROR	1004	Parsing error The error occurs when parsing data. Probably some field in JSON is missing or is invalid. See the error message for more details.
FAIR_CHOICE_ERROR	1005	Fair choice error The error occurs when fetching details about product for Fair Choice. See the error message for more details.
EDIT_DISABLED_USER_HAS_PAID	1006	Edit disabled because user has paid Edit consent is disabled because user has paid for Fair Choice. See the error message for more details.
EDIT_DISABLED_DEVICE_ID_RESTRICTED	1007	Edit function is disabled because device id is restricted See the error message for more details.
EDIT_DISABLED_GEORESTRICTED_USER	1008	Edit function is disabled because of the users' geolocation See the error message for more details.