Bright SDK Gradle Plugin — Integration Guide

Introduction

The Bright SDK Update Plugin automates the process of updating the Bright SDK within your Android project. By integrating this plugin, developers can effortlessly switch between SDK versions, ensuring they are always working with the latest features and fixes. This plugin also simplifies debugging by allowing easy transitions between different versions of the SDK.

Benefits

• Automated Updates: Automatically fetches and installs the latest version of the Bright SDK, reducing manual overhead.
• Seamless Integration: Simplifies adding the Bright SDK as a dependency in your project's build.gradle file.
• Version Management: Allows easy switching between different SDK versions — useful for testing and debugging.
• Local Caching: Supports caching of SDK files, minimizing the need for repeated downloads.

Prerequisites

• Java Development Kit (JDK): Version 17 or higher, with backward compatibility for Java 8.
• Gradle: Version 6.7 or later.
• Internet Access: Required for downloading SDK version information and the SDK itself.
• BrightSDK API Key: Required to authenticate with the SDK releases API. See the API Key section below or obtain an API key.

API Key

Starting from plugin version 1.3.0, the plugin authenticates with the BrightSDK releases API using an API key. This is required — builds will fail without it.

How to obtain an API key

1. Log in to the BrightData Control Panel.
2. Go to Company profile in the left sidebar.
3. Open the API keys section.
4. Click Add API key, give it a name, and copy the generated key.

For step-by-step screenshots, see the obtain-api-key guide.

macOS / Linux

Add to your shell profile (~/.zshrc, ~/.bashrc) or export before each build:

export SDK_API_KEY=my-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Windows (PowerShell)

$env:SDK_API_KEY = "my-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

CI / GitHub Actions

Store the key as a repository secret and expose it as an env var in your workflow:

env:
  SDK_API_KEY: ${{ secrets.SDK_API_KEY }}

Getting Started

System Requirements

1. JDK: Version 17 or higher.
2. Gradle: Version 6.7 or later.
3. Supported Platforms: Any platform where Java and Gradle can run (Windows, macOS, Linux).
4. SDK_API_KEY: Environment variable set to your BrightSDK API key (see API Key).

Installation Instructions

Step 1 — Set your API key

Export SDK_API_KEY before building (see API Key for how to obtain one):

export SDK_API_KEY=my-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2 — Create brightsdk.gradle in the app/ directory

Add a file named brightsdk.gradle in your app/ directory:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'com.brightdata:bright-sdk-gradle:1+'
    }
}

// default values kept for reference
ext.brightsdk = [
    dir: "libs",
    version: "latest",
    ext: "brightsdk",
    consumerProjects: "app",
    useLocalCache: false,
    useMavenLocal: false,
]

apply plugin: 'com.brightdata.brightsdk-gradle'

tasks.named("preBuild").configure {
    dependsOn installBrightSdk
}

Step 3 — Register the plugin in app/build.gradle

apply from: 'brightsdk.gradle'

Step 4 — Verify the integration

Run your Gradle build as usual:

./gradlew build

The installBrightSdk task will automatically execute before preBuild, fetching the latest SDK version via the authenticated integration config API.

Plugin Configuration

Override defaults in the brightsdk configuration block:

• version: The SDK version to use (default: "latest").
• ext: The file extension for SDK files (default: "brightsdk").
• dir: Directory to place the SDK file (default: "libs").
• useLocalCache: Skip download if a cached file exists (default: false).
• useMavenLocal: Auto-inject SDK and its dependencies via MavenLocal (default: false).

Using the Plugin

Checking for Bright SDK updates

The plugin automatically checks for the latest SDK version. It calls GET /sdk/integration/config with your SDK_API_KEY to retrieve available versions and download URLs.

Updating Bright SDK

If version is set to "latest" and a newer version is available, the plugin downloads and replaces the existing SDK files using the URL resolved from the integration config response.

Backward compatibility

The plugin supports backward compatibility with older SDK versions, allowing you to switch between versions as needed.

Documentation

For full API reference, see the Bright SDK Gradle Plugin Documentation.

Best Practices

• Stay up to date: Run Gradle with --refresh-dependencies to keep the plugin and SDK on the latest version.
• Secure your API key: Never commit SDK_API_KEY to source control. Use environment variables, CI secrets, or a secrets manager.
• CI/CD: Store the key as a repository secret (e.g. secrets.SDK_API_KEY in GitHub Actions) and pass it as an env var in your workflow.

FAQ

How do I update the Bright SDK?

Simply run any Gradle build that triggers preBuild — the installBrightSdk task runs automatically.

Can I use this plugin with older SDK versions?

Yes. Set version in the brightsdk block to the specific version string you need.

What should I do if I encounter issues?

Check the plugin documentation and ensure you are using the latest version. If issues persist, contact sdk@brightdata.com.

The build fails with "Android download URL not resolved"

The SDK_API_KEY environment variable is missing or invalid. Set it before running the build — see the API Key section.

How do I get a BrightSDK API key?

Log in to the BrightData Control Panel → Company profile → API keys → Add API key. See the step-by-step guide with screenshots.

Support

Contact our support team at sdk@brightdata.com.

• Bright SDK Gradle Plugin Documentation — full API reference
• Obtain API Key — step-by-step guide with screenshots
• BrightSDK — SDK overview and dashboard