Unity SDK Integration Guide (Android)

General 

Step 1: Add the Android AAR file 

Step 2: Add Main Gradle and Gradle Properties files 

Step 3: Update the dependencies in mainTemplate 

Step 4: Update gradleTemplate 

Step 5: Implement ChoiceListener interface 

Step 6: Instantiate necessary objects 

Step 7: Set the behavior of the SDK 

Step 8: Customize the Consent Screen UI (optional)

Step 9: Initialize the SDK  

Step 10: Show the Consent Screen 

Step 11: Adding ‘opt-out’ option from settings

How to update SDK

Migrating from API V1 to V2

API documentation 

BrightApi

Settings

Choice

ConsentLanguage

General

For full integration you should follow the Android SDK Integration Guide. 

The purpose of this document is to assist Unity developers with Unity-specific considerations in conjunction with the Android SDK Integration Guide.

Step 1: Add the Android AAR file

In the Assets folder, create a sub-folder named Plugins and inside this folder a sub-folder named Android. (Assets > Plugins > Android)

Drag the AAR file into the Android folder.

Step 2: Add Main Gradle and Gradle Properties files

Check the following options

1. Editor > Player > Publishing Settings > Build > Custom Main Gradle Template
2. Editor > Player > Publishing Settings > Build > Custom Gradle Properties Template

This will create the following files in Assets > Plugins > Android

1. gradleTemplate (gradleTemplate.properties)
2. mainTemplate (mainTemplate.gradle)

Step 3: Update the dependencies in mainTemplate 

Add the following dependencies to mainTemplate dependencies section

    implementation 'androidx.appcompat:appcompat:1.1.0'

    implementation 'androidx.core:core:1.9.0'

    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'

    implementation 'androidx.multidex:multidex:2.0.1'

The dependencies part should look like this

Step 4: Update gradleTemplate

Add the following to gradleTemplate

android.useAndroidX=true

android.enableJetifier=true

Step 5: Implement ChoiceListener interface

First create a ChoiceListener class

class ChoiceListener : AndroidJavaProxy

{

    public ChoiceListener() : base("com.android.eapx.Settings$OnStatusChange") { }

    void onChange(int choice)

    {

        //Here you'll get the callback with the user's choice

        // 1 - user agreed

        // 4 - user declined

    }

}

Step 6: Instantiate necessary objects

    AndroidJavaClass unityPlayerClass = new       AndroidJavaClass("com.unity3d.player.UnityPlayer");

/*Important when testing the code: currentActivity will be available only on a device/emulator and not inside Unity*/

    AndroidJavaObject currentActivity =  unityPlayerClass.GetStatic<AndroidJavaObject>("currentActivity");

//Use the full package name, If you have a dedicated package name update it accordingly

    AndroidJavaObject brightApi = new  AndroidJavaObject("com.android.eapx.BrightApi");

//create a settings object
    AndroidJavaObject settings = new AndroidJavaObject("com.android.eapx.Settings", currentActivity);

Step 7: Set the behavior of the SDK 

//Refer to the API documentation for all settings available.

//Benefit will appear at the start of the consent text. 

settings.Call("setBenefit", "To get free daily tokens");

//Set the buttons text. If not set default values will be used

settings.Call("setAgreeBtn", "Yes, sure!");

settings.Call("setDisagreeBtn", "No, thanks!");

//don’t show the consent screen automatically

settings.Call("setSkipConsent", true); 

//to use choice ChoiceListener and register the callback

ChoiceListener choiceListener = new ChoiceListener();

settings.Call("setOnStatusChange", choiceListener);

Step 8: Customize the Consent Screen UI (optional)

While you are always invited to use the standard consent screen built into the Bright SDK, we highly encourage you to customize its design. Modifying the design to integrate smoothly with your app's interface and reflect its look & feel, typically leads to higher conversion rates.

There are two customization options you can choose from:

1. CustomConsentSettings class allows you to modify Bright Data’s consent screen. 
2. Use external consent -  this option allows you to create a view in your app to get the user’s consent, with your own design. Our API allows you to pass the user’s consent to the SDK.

CustomConsentSettings

Please find all available settings for consent screen customization here.

AndroidJavaObject customConsentSettings = new        AndroidJavaObject("com.android.eapx.CustomConsentSettings");

customConsentSettings.Call("setConsentTextColor", "#FFFFFF");

        customConsentSettings.Call("setAgreeButtonBackgroundColor", "#d0510c");

customConsentSettings.Call("setDisagreeButtonTextColor", "#FFFFFF");

customConsentSettings.Call("setConsentTextLinksColor", "#FFFFFF");

customConsentSettings.Call("setAppTitleTextColor", "#facd00");

customConsentSettings.Call("setHideNetworkIcons", true);

customConsentSettings.Call("setPrivacyMessageLinksColor", "#facd00");

customConsentSettings.Call("setPrivacyMessageTextColor", "#ffffff");



//you can also set the font

AndroidJavaClass consentFont = new AndroidJavaClass("com.android.eapx.CustomConsentSettings$CustomFontFamily");

        AndroidJavaObject consentFontEnumValue = consentFont.GetStatic<AndroidJavaObject>("monospace");




        AndroidJavaClass consentFontStyle = new AndroidJavaClass("com.android.eapx.CustomConsentSettings$CustomTextStyle");

        AndroidJavaObject consentFontStyleEnumValue = consentFontStyle.GetStatic<AndroidJavaObject>("italic");




        AndroidJavaObject customTypeface = new AndroidJavaObject("com.android.eapx.CustomTypeface");

        customTypeface.Call("setFontFamily", consentFontEnumValue);

        customTypeface.Call("setTextStyle", consentFontStyleEnumValue);

        customConsentSettings.Call("setCustomTypeface", customTypeface);


//set customConsentSettings in the general settings of the SDK

settings.Call("setCustomConsentSettings", customConsentSettings);

To use custom images in the consent screen, copy them to the StreamingAssets folder of the app.
On Android images in StreamingAssets are not accessible directly, but through a local webrequest.
The following is an example loading custom images for the consent icon, background and buttons.
This is a possible implementation, you can use your own.

    public static string CUSTOM_CONSENT_BACKGROUND_IMAGE = "background_image";

    public static string CUSTOM_CONSENT_ICON_IMAGE = "icon_image";

    public static string CUSTOM_CONSENT_AGREE_BUTTON_IMAGE = "agree_button_image";

    public static string CUSTOM_CONSENT_DISAGREE_BUTTON_IMAGE = "disagree_button_image";

    void setCustomConsent()

    {

        customConsentSettings = new AndroidJavaObject("com.android.eapx.CustomConsentSettings");

        Dictionary<string, StreamingAsset> imagesDictionary = createImagesDictionary();

        settings.Call("setCustomConsentSettings", customConsentSettings);

        StartCoroutine(LoadFiles(imagesDictionary));

    }

    Dictionary<string, StreamingAsset> createImagesDictionary()

    {

        //get the path to the images

        string backgroundImagePath = System.IO.Path.Combine(Application.streamingAssetsPath, "your_background_image.png");

        string iconImagePath = System.IO.Path.Combine(Application.streamingAssetsPath, "your_icon.jpg");

        string agreeButtonImagePath = System.IO.Path.Combine(Application.streamingAssetsPath, "agree_button.png");

        string disagreeButtonImagePath = System.IO.Path.Combine(Application.streamingAssetsPath, "disagree_button.png");

        //create a dictionary to help you set the correct images after the web request

        Dictionary<string, StreamingAsset> imagesDictionary = new Dictionary<string, StreamingAsset>();

        imagesDictionary.Add(CUSTOM_CONSENT_ICON_IMAGE, new StreamingAsset(iconImagePath, iconImageBytes));

        imagesDictionary.Add(CUSTOM_CONSENT_BACKGROUND_IMAGE, new StreamingAsset(backgroundImagePath, backgroundImageBytes));

        imagesDictionary.Add(CUSTOM_CONSENT_AGREE_BUTTON_IMAGE, new StreamingAsset(agreeButtonImagePath, agreeButtonImageBytes));

        imagesDictionary.Add(CUSTOM_CONSENT_DISAGREE_BUTTON_IMAGE, new StreamingAsset(disagreeButtonImagePath, disagreeButtonImageBytes));

        return imagesDictionary;

    }

    IEnumerator LoadFiles(Dictionary<string, StreamingAsset> imagesDictionary)

    {

        List<StreamingAsset> imagesList = new List<StreamingAsset>(imagesDictionary.Values);

        StreamingAsset streamingAsset;

        for (int i=0; i < imagesList.Count; i++)

        {

            streamingAsset = imagesList[i];

            WWW www = new(streamingAsset.Url);

            yield return www;

            streamingAsset.ImageBytes = www.bytes; 

        }

        updateConsentImages(imagesDictionary);

        brightApi.CallStatic("init", currentActivity, settings);

    }

    private void updateConsentImages(Dictionary<string, StreamingAsset> imagesDictionary)

    {

        customConsentSettings.Call("setBodyBackgroundImageBytes", imagesDictionary[CUSTOM_CONSENT_BACKGROUND_IMAGE].ImageBytes);

        customConsentSettings.Call("setAgreeButtonImageBytes", imagesDictionary[CUSTOM_CONSENT_AGREE_BUTTON_IMAGE].ImageBytes);

        customConsentSettings.Call("setDisagreeButtonImageBytes", imagesDictionary[CUSTOM_CONSENT_DISAGREE_BUTTON_IMAGE].ImageBytes);

        settings.Call("setShowAppIcon", true, imagesDictionary[CUSTOM_CONSENT_ICON_IMAGE].ImageBytes);

    }

    public class StreamingAsset

    {

        public StreamingAsset(string url, byte[] imageBytes)

        {

            this.Url = url;

            this.ImageBytes = imageBytes;

        }

        public string Url;

        public byte[] ImageBytes;

    }

Click here to see an example of a custom consent screen using Unity Editor and code

External consent screen

Subject to Bright SDK approval, you can create and use your own consent screen with Bright SDK. Please follow the following guidelines.

Design of your consent screen

1. Your screen must include the mandatory text below (marked in red), as well as links to our terms and privacy policies. 

2. If you wish to translate your screen into other languages, please find the most common ones here. If there is a language you miss here, contact your partnership manager and ask for it. Make sure you only use these translations precisely, without additions or omissions.

This is what it looks like on the default Bright SDK screen:

Mandatory text

“To [Benefit to user], please allow web indexing by Bright Data to use your device's free resources and IP address to download public web data from the Internet.

None of your personal information is collected, except your IP address. Bright Data does not track you.”

- The link to "Bright Data” leads to "https://www.brightdata.com"

- The link to "Privacy Policy” leads to "https://bright-sdk.com/privacy-policy"

- The link to "End User License Agreement" leads to "https://bright-sdk.com/EULA"

- Clicking/tapping on "public web data" -> opens a popup with the following info:

 For Fire TV:

Replace the links with the following:

"Scan the QR Code to learn more about Bright Data policy and ethical usage". You can use your own branded QR code or hosted version, leading to this URL: https://bright-sdk.com/users#learn-more-about-bright-sdk-web-indexing

See below some examples of a possible custom consent screens:

Integration code

Skip the default consent screen

When showing the consent screen, notify the SDK

brightApi.CallStatic("reportConsentShown", currentActivity);

The opt-in button (e.g. "I Agree”) should call

brightApi.CallStatic("externalOptIn", currentActivity);

The opt-out button (e.g. "I Disagree”) should call

brightApi.CallStatic("optOut", currentActivity);

If the user clicked the back button and closed the consent without making a choice call
Important - if you disable closing the consent screen using the back button do not call this method.

brightApi.CallStatic("reportConsentBackPress", currentActivity);

Please contact Bright SDK before implementing in order to get pre-approved.

Step 9: Initialize the SDK

brightApi.CallStatic("init", currentActivity, settings);

Step 10: Show the Consent Screen

brightApi.CallStatic("showConsent", currentActivity);

/*If you need to change the settings of the consent screen after the init, you can use update the settings object and pass it to showConsent */

    brightApi.CallStatic("showConsent", currentActivity, settings);

Step 11: Adding ‘opt-out’ option from settings

⚠️ If you are implementing bright SDK for FireTV apps, see section 11.1

⚠️ Read and implement this section carefully. The user must always be able to opt-out of Bright SDK after giving their initial consent. 

Your app will usually first show the consent screen to the user on first run (or after a short “trial” period), the user will make a choice and SDK will act according to that choice.

Regardless of the user’s choice you must add an option for the user to opt-in/out of using SDK at any time. The user must always be able to opt-out of Bright SDK after giving their initial consent. 

This means that you must add an opt-out option in your app - this is usually placed in the settings menu

1. Add a switch with the label “Web Indexing”. The switch should clearly reflect the current status (is the user opted-in or not?).
2. Below Web Indexing add your own text to emphasize the value users get when opting in.
3. Include a way to give more information to the user (“Learn more”). The hyperlink should open a browser window with the following URL: https://bright-sdk.com/users#learn-more-about-bright-sdk-web-indexing.
4. In general, you are free to choose the UX (radio button, switch, etc) but the opt-out option must be clearly labeled so users can freely opt-out.

See the examples below, illustrating both opted-in and opted-out scenarios:

Some ideas for value text:

• Refrain from using the technical term “opt in” / “opt out”. We always prefer speaking value to users.

• Switching the toggle button ‘OFF’ will trigger a function that will clear prior selection of the user (peer/not peer) using BrightApi.optOut(context);
  See code example from MainActivity:

void UserRequestedToTurnOffBrightSdkFromOptions(Context context){
    // disable Bright SDK
    brightApi.CallStatic("optOut", currentActivity);
}

Step 11.1 Opt-out for TV  apps

Your app will usually first show the consent screen to the user on first run (or after a short “trial” period), the user will make a choice and SDK will act according to that choice.

Regardless of the user’s choice you must add an option for the user to opt-in/out of using SDK at any time. The user must always be able to opt-out of Bright SDK after giving their initial consent. 

This means that you must add an opt-out option in your app - this is usually placed in the settings menu.

1. Add a switch with the label “Web Indexing”. The switch should clearly reflect the current status (is the user opted-in or not?).
2. Below Web Indexing add your own text to emphasize the value users get when opting in.
3. Include a way to give more information to the user. It’s best to include a QR code that will lead to the web page that shows more info https://bright-sdk.com/users#learn-more-about-bright-sdk-web-indexing. The QR code must be accompanied by instructions: "Scan the QR Code to learn more." You can use your own branded QR code to the URL above, or use the QR below, or the  hosted version. 
4. In general, you are free to choose the UX (radio button, switch, etc) but the opt-out option must be clearly labeled so users can freely opt-out. 
5. FYI: You are free to add a pop up / confirmation dialog box to discourage the user from opting out (for example: “if you disable Web Indexing, you will start seeing ads. Do you want to see ads?”). You are responsible for the text and design for this implementation and it will be reviewed before publishing.

See the examples below, illustrating both opted-in and opted-out scenarios:

Some ideas for value text:

Examples for opt-out settings screens:

Web Indexing Switch

Good or bad?	Example	Comments
👎		The label should be Web Indexing, and not Bright/Bright SDK. Missing text to emphasize the value users get when opting in. The switch should clearly reflect the current status (is the user opted-in or not?).
👎		Missing text to emphasize the value users get when opting in.
👎		Missing “Learn more”, which opens a browser window with the following URL: https://bright-sdk.com/users#learn-more-about-bright-sdk-web-indexing. Missing text to emphasize the value users get when opting in.
👍		Mobile device version
👍		Mobile device version
👍		TV version (QR instead of “learn more” link)

Opt-Out Messages (Optional but highly recommended)

Good or bad?	Example	Comments
👎		Refrain from using the technical term “opt in” / “opt out”. We always prefer speaking value to users.
👎		The default choice in that case should be the green checkmark, keeping web indexing enabled.
👍		Dialog box to discourage the user from opting out, reminding him of the value they are losing.
👍		Correct messaging, correct default choice
👍		Dialog box to validate the user’s choice, reminding them how to opt back in.

How to update SDK

Download the latest SDK from our website and follow these simple steps:

• delete bright_sdk.aar from Assets > Plugins > Android
• Copy the new bright_sdk.aar file to Assets > Plugins > Android

Migrating from API V1 to V2

The new API introduces new capabilities and a consent screen that you can customize to match your app’s UI design.

All main methods are deprecated and replaced by BrightApi methods.

The following describes some key point changes.
To use the new API, instead of

AndroidJavaObject brightApi = new  AndroidJavaObject("com.android.eapx.main");

use

AndroidJavaObject brightApi = new  AndroidJavaObject("com.android.eapx.BrightApi");

To initialize the SDK you need to instantiate a Settings object. Settings will let you customize the behavior of the SDK.

AndroidJavaObject settings = new AndroidJavaObject("com.android.eapx.Settings", currentActivity);

To initialize the SDK

brightApi.CallStatic("init", currentActivity, settings);

The consent screen will be displayed automatically, unless you explicitly prevent it.
To show the Consent Screen manually

brightApi.CallStatic("showConsent", currentActivity);

API documentation

BrightApi

Settings

CustomConsentSettings

CustomTypeface

Choice

ConsentLanguage

CustomTypeface