Skip to main content
For the full Android integration reference, see the Android SDK Integration Guide. This document covers only Unity-specific steps and should be used in conjunction with that guide.

Requirements

  • Latest Bright SDK AAR for Android.
  • Unity Editor (latest recommended).
  • Android build support installed in Unity.

Important Notes

  • Users must always voluntarily decide to opt in after seeing the consent screen, and must always have an easy way to opt out.
  • Bright Data reviews SDK integration after initial release and regularly thereafter. Your account will be terminated if you violate the guidelines in this document.
  • Bright Data recommends offering value in exchange for opting in (e.g., fewer ads, bonus coins, premium features). However, simply asking for user support is also acceptable.
  • Do not upload your APK with Bright SDK to the Google Play Store without prior approval.
1

Create App ID on Dashboard

If you haven’t done this yet, log in to your dashboard and create your app ID first.
2

Install SDK Files

You can set up the Bright SDK AAR in your Unity project in two ways:
  • Using the Bright SDK Unity Plugin Recommended - automatically downloads, extracts, and places the latest bright_sdk.aar into the correct Unity directory before every build.
  • Manually - download the AAR from the dashboard and copy it yourself into the project.
Either way, you will still need to configure your Gradle files and add the SDK initialization code to your app.
Install the plugin by following the Bright SDK Unity Plugin guide.The plugin will:
  • Fetch the latest bright_sdk.aar via the authenticated BrightSDK API (SDK_API_KEY) and place it into Assets/Plugins/Android/.
  • Cache the file locally to avoid redundant re-downloads.
  • Run automatically on every build (File → Build Settings → Build).
Once the plugin is set up, skip to Step 3 - Add Main Gradle and Gradle Properties Files.
Download the latest Bright SDK AAR using the Bright SDK downloader.In the Assets folder, create a sub-folder named Plugins and inside it a sub-folder named Android:
Assets > Plugins > Android
Drag the bright_sdk.aar file into the Android folder.Drag AAR file into Android folder
3

Add Main Gradle and Gradle Properties Files

Regardless of which option you chose above, the following Gradle steps must be done manually.
Enable the following options in Unity:
  • Editor → Player → Publishing Settings → Build → Custom Main Gradle Template
  • Editor → Player → Publishing Settings → Build → Custom Gradle Properties Template
This will create the following files in Assets > Plugins > Android:
  • mainTemplate.gradle
  • gradleTemplate.properties
Enable Custom Gradle Templates
4

Update Dependencies in mainTemplate

Add the following dependencies to the dependencies section of mainTemplate.gradle:
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    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'
}
5

Update gradleTemplate

Add the following to gradleTemplate.properties:
android.useAndroidX=true
android.enableJetifier=true
6

Implement ChoiceListener Interface

Create a ChoiceListener class to handle the user’s consent choice callback:
class ChoiceListener : AndroidJavaProxy
{
    public ChoiceListener() : base("com.android.eapx.Settings$OnStatusChange") { }

    void onChange(int choice)
    {
        // Callback with the user's choice:
        // 1 - user agreed
        // 4 - user declined
    }
}
7

Instantiate Necessary Objects

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

// Important when testing: currentActivity is only available on a device/emulator,
// not inside the Unity Editor
AndroidJavaObject currentActivity = unityPlayerClass.GetStatic<AndroidJavaObject>("currentActivity");

// Use the full package name - update if you have a dedicated package name
AndroidJavaObject brightApi = new AndroidJavaObject("com.android.eapx.BrightApi");

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

Set the Behavior of the SDK

// Refer to the API documentation for all available settings

// Benefit text appears at the start of the consent text
settings.Call("setBenefit", "To get free daily tokens");

// Set button texts (defaults will be used if not set)
settings.Call("setAgreeBtn", "Yes, sure!");
settings.Call("setDisagreeBtn", "No, thanks!");

// Prevent the consent screen from showing automatically
settings.Call("setSkipConsent", true);

// Register the ChoiceListener callback
ChoiceListener choiceListener = new ChoiceListener();
settings.Call("setOnStatusChange", choiceListener);
10

Initialize the SDK

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

Add Opt-In/Out Settings Option

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 must include a settings option allowing users to opt in or out at any time. This is typically placed in a Settings menu.
Every time the user toggles Web Indexing ON, the consent screen must reappear — regardless of any previous opt-in.
Mobile AppsRequirements:
Alt textAlt text
Implementation:When the user toggles off:
void UserRequestedToTurnOffBrightSdkFromOptions()
{
    // Disable Bright SDK
    brightApi.CallStatic("optOut", currentActivity);
}
When the user toggles on → call brightApi.CallStatic("showConsent", currentActivity) to show the consent screen.
There is no way to directly opt in. Only the user can decide. You must show the consent screen - opt-in happens automatically only if the user agrees.
TV AppsRequirements:Alt text
You may add a confirmation dialog to discourage opting out (e.g., “If you disable Web Indexing, you will start seeing ads. Continue?”)
Alt textAlt text
Value text suggestions (both mobile and TV):
StateExample text
Opted out”Enable to see fewer ads”
Opted out”Enable to get 100 extra coins”
Opted out”Enable to enjoy premium features”
Opted in”When enabled you see fewer ads”
Opted in”When enabled you get 100 extra coins”
Refrain from using technical terms like “opt in” / “opt out” — always speak in terms of user value.Opt-Out Messages (Optional but highly recommended):
ExampleComments
BadAvoid using technical terms “opt in” / “opt out”
BadDefault choice should be the green checkmark (Web Indexing enabled)
GoodDialog box discouraging opt-out, reminding user of value they lose
GoodCorrect messaging, correct default choice
GoodDialog box validating user’s choice, reminding how to opt back in
14

How to Update the SDK

The Bright SDK Unity Plugin handles updates automatically. As long as the version in Assets/Editor/BrightSDK/BrightSDK.json is set to null (latest), the plugin will fetch and replace the SDK on every build. No manual file replacement needed.To trigger an update manually, simply build your project again:
  1. Open File → Build Settings
  2. Click Build or Build and Run
  1. Delete bright_sdk.aar from Assets > Plugins > Android
  2. Copy the new bright_sdk.aar into Assets > Plugins > Android
15

Migrating from API V1 to V2

The V2 API introduces new capabilities and a customizable consent screen. All main V1 methods are deprecated and replaced by BrightApi methods.Instantiate BrightApi (V1 → V2):
// V1:
AndroidJavaObject brightApi = new AndroidJavaObject("com.android.eapx.main");

// V2:
AndroidJavaObject brightApi = new AndroidJavaObject("com.android.eapx.BrightApi");
Initialize with Settings object:
// Instantiate a Settings object
AndroidJavaObject settings = new AndroidJavaObject("com.android.eapx.Settings", currentActivity);

// Initialize the SDK (must be called after all settings are configured)
brightApi.CallStatic("init", currentActivity, settings);
The consent screen will be displayed automatically after init, unless you explicitly call settings.Call("setSkipConsent", true).
Show the consent screen manually:
brightApi.CallStatic("showConsent", currentActivity);
16

API Documentation

1

BrightApi

Public Methods:
MethodDescription
static void init(Context context, Settings settings)Initializes the SDK. Call once in your first activity. Shows consent dialog automatically unless setSkipConsent(true) is set.
static void showConsent(Activity activity)Displays the consent dialog. Use when a user tries to close an ad or re-enables Bright SDK from Settings.
static void showConsent(Activity activity, Settings settings)Displays the consent dialog with a new settings object.
static void optOut(Context context)Revokes the user’s consent and sets Choice.NOT_PEER. Triggers OnStatusChange callback.
static Boolean getConsentChoice(Context context)Returns true if user is peer, false if not peer, null if no choice has been made yet.
static boolean isSvcProcess()Returns true if the current process is the SDK service process.
static void setTrackingId(String trackingId)Adds a unique tracking ID for reports and debugging. Must be called beforeBrightApi.init.
static void reportConsentShown(Context context)
static void reportConsentBackPress(Context context)
static void reportConsentOptOut(Context context)
2

Settings

Constructor:
Settings(Context context)
Public Methods:
MethodDescription
String getAppId()Returns Application ID as defined in ApplicationInfo.packageName
String getAppName()Returns app name as defined in ApplicationInfo.loadLabel
void setSkipConsent(boolean skipConsent)Set true to prevent consent dialog from showing automatically
void setLanguage(ConsentLanguage language)Override the device default language
void setBenefit(String benefit)Prefix text for the consent dialog (e.g., “To use the app with no ads”)
void setAgreeBtn(String agreeBtn)Text for the agree button. Default text used if not set.
void setDisagreeBtn(String disagreeBtn)Text for the disagree button. Default text used if not set.
void setOnStatusChange(OnStatusChange onStatusChange)Register a callback for user choice changes
void setMinJobId(int minJobId)Min job ID for JobScheduler. Default range: 1–1000
void setMaxJobId(int maxJobId)Max job ID for JobScheduler. Default range: 1–1000
void setCustomConsentSettings(CustomConsentSettings ccs)Apply custom consent screen settings
void setShowAppIcon(boolean showAppIcon)Show the default app icon on the consent screen
void setShowAppIcon(boolean showAppIcon, int appLogoResourceId)Show a custom image resource as the app icon
void setShowAppIcon(boolean showAppIcon, byte[] imageBytes)Show a custom image (bytes) as the app icon
void setOptOutInstructions(String optOutInstructions)Custom opt-out instructions text
void setCampaignId(String campaignId)Set a campaign ID
void setBackPressListener(Runnable backPressListener)Listener for back press on consent screen
3

CustomConsentSettings

MethodDescription
setConsentTitle(String)Set the consent screen title
setAppTitleTextColor(String)App title text color
setAppTitleTypeface(CustomTypeface)App title font
setBodyBackgroundColor(String)Body background color
setBodyBackgroundImageResource(int)Body background image (resource ID)
setBodyBackgroundImageBytes(byte[])Body background image (bytes)
setBodyBackgroundShadow(boolean)Enable/disable body background shadow
setScreenBackgroundColor(String)Screen background color
setScreenBackgroundImageResource(int)Screen background image (resource ID)
setScreenBackgroundImageResource(int, boolean fillScreen)Screen background image with fill option
setScreenBackgroundImageBytes(byte[])Screen background image (bytes)
setScreenBackgroundImageBytes(byte[], boolean fillScreen)Screen background image (bytes) with fill option
setConsentTextColor(String)Consent main text color
setConsentTextTypeface(CustomTypeface)Consent main text font
setAgreeButtonImageResource(int)Agree button image (resource ID)
setDisagreeButtonImageResource(int)Disagree button image (resource ID)
setAgreeButtonImageBytes(byte[])Agree button image (bytes)
setDisagreeButtonImageBytes(byte[])Disagree button image (bytes)
setAgreeButtonTextColor(String)Agree button text color
setDisagreeButtonTextColor(String)Disagree button text color
setAgreeButtonTypeface(CustomTypeface)Agree button font
setDisagreeButtonTypeface(CustomTypeface)Disagree button font
setConsentTextLinksColor(String)Consent text links color
setAgreeButtonBackgroundColor(String)Agree button background color
setDisagreeButtonBackgroundColor(String)Disagree button background color
setPrivacyMessageTextColor(String)Privacy message text color
setPrivacyMessageLinksColor(String)Privacy message links color
setPrivacyMessageTextTypeface(CustomTypeface)Privacy message font
setNetworkIconsColorFilter(String)Network icons color filter
setNetworkIconsTextColor(String)Network icons text color
setNetworkIconsTextTypeface(CustomTypeface)Network icons text font
setHideNetworkIcons(boolean)Show/hide network icons
setQrCodeColorFilter(String)QR code foreground color
setQrCodeBackgroundColor(String)QR code background color
setCustomTypeface(CustomTypeface)Apply font to all text elements (specific overrides take precedence)
setTopIconColorFilter(String)Top icon color filter
setHideConsentIcon(boolean)Show/hide the consent icon
4

CustomTypeface

Constructors:
CustomTypeface()
CustomTypeface(Typeface typeface)
CustomTypeface(CustomConsentSettings.CustomFontFamily fontFamily,
               CustomConsentSettings.CustomTextStyle textStyle)
Methods:
MethodDescription
void setTypeface(Typeface typeface)Set a Typeface object directly
void setFontFamily(CustomConsentSettings.CustomFontFamily fontFamily)Set font family
void setTextStyle(CustomConsentSettings.CustomTextStyle textStyle)Set text style
5

Choice

ValueIntDescription
Choice.NONE0Consent screen not shown yet, or user hasn’t made a choice
Choice.PEER1User agreed — reflect in settings so user can opt out
Choice.NOT_PEER4User declined — reflect in settings so user can opt in
6

ConsentLanguage

Supported values: en, de, es, fr, it, ja, pt, ru, tr
7

CustomFontFamily

Supported values: casual, cursive, monospace, sans_serif, sans_serif_black, sans_serif_light, sans_serif_medium, sans_serif_smallcaps, sans_serif_thin, sans_serif_condensed, sans_serif_condensed_light, sans_serif_condensed_medium, serif, serif_monospace
8

CustomTextStyle

Supported values: bold, bold_italic, italic, normal