Skip to main content

Requirements

  • Windows operating system.
  • .NET Framework 4.5 or newer.
  • Visual Studio (recommended).
  • Assigned App ID from Bright SDK Dashboard.
1

Create App ID on Dashboard

If you haven’t done this yet, log in to your Bright SDK Dashboard and create your app ID first.Format: Your assigned App ID uniquely identifies your application and associates the peers provided by your application with you in the Bright Data network.
2

Install SDK Files

You can set up the Bright SDK in your .NET Windows app in two ways:
  • Using the Bright SDK integration CLI tool Recommended - automatically downloads the SDK, copies the required files, and patches your .csproj with the necessary references.
  • Manually - download the SDK from the sdk downloader and copy the files yourself.
Either way, you will still need to add the SDK initialization code to your app.
Download the latest Bright SDK using the Bright SDK downloader, unzip it.SDK Structure
FileDescription
net_updater32.exeBright Data Windows service installer, uninstaller and entry point
lum_sdk.dll.NET API, targeting .NET Framework 4.5 (AnyCPU)
brd_config.jsonconsent configuration and customization
lum_sdk.xml.NET API documentation for Visual Studio
Important: lum_sdk.dll, net_updater32.exe and brd_config.json files must be located next to each other when running the application.
3

Integrate Bright SDK in Your Code

Add SDK Files to Your SolutionBuild-time Dependencies
  1. Copy the following files to any location inside your repository:
    • lum_sdk.dll
    • lum_sdk.xml
  2. Add them to your source control.
  3. Add reference from your main project to lum_sdk.dll (Copy Local = true).
lum_sdk.xml is for Visual Studio to display documentation of the API and must be located next to the referenced lum_sdk.dll. It is not needed at runtime.
If you used the CLI tool in Option A, skip copying lum_sdk.dll and adding the reference - it is already copied into BrightSDK/ and referenced in your .csproj.
Run-time Dependencies
  1. Copy the following files to the root of your main project:
    • net_updater32.exe
    • brd_config.json
  2. Add them to your source control.
  3. Add them to your project as Content.
  4. Set them to be copied to the output folder.
If you used the CLI tool in Option A, skip copying net_updater32.exe and brd_config.json - they are already in place. You still need to add net_updater32.exe to your project as Content and set it to be copied to the output folder.
Add SDK Initialization to Your Code
  1. Instantiate BrightData.Api.
  2. Initialize it during your application’s startup initialization.
    • Set required fields now and you can customize the consent screen later.
  3. Use brd_config.json and/or set them programmatically (see API Documentation).
  4. Write handler code for the user choice changed event.
    • For example: enable/disable ads or premium features.
  5. Close the SDK when your application is exiting.
Note: Init will show consent screen to the user only if they haven’t seen it before (didn’t agree or disagree). You can disable consent on Init completely with Setting.SkipConsent=true and manually show it later with Api.ShowConsent().
See Code Example and use cs_winform_anycpu and cs_wpf_anycpu from samples directory for reference.
4

Add Opt-In/Out Settings Option

Critical Requirement: The user must always be able to opt-out of Bright SDK after giving their initial consent.
Regardless of the user’s initial choice, you must add an option for users to opt-in/out at any time. This is usually placed in the settings menu.
Every time the user toggles Web Indexing ON, the consent screen must reappear — regardless of any previous opt-in.
Adding Opt-In/Out to Your Existing Settings Menu:
  1. Add a switch (checkbox/toggle button) labeled “Web Indexing”:
    • Must clearly reflect current status (opted-in or opted-out).
    • Should be checked if BrightData.Api.ConsentChoice is true.
    • Unchecking it should call BrightData.Api.OptOut().
    • Checking it should call BrightData.Api.ShowConsent().
  2. Add value text below the switch:
  3. Include a “Learn More” option:
  4. UX Guidelines:
    • You’re free to choose the UX (radio button, switch, etc.).
    • The opt-out option must be clearly labeled.
    • Users must be able to freely opt-out.
See Code Examples at the end of the guide:
Ensure the opt-out functionality is fully implemented before submitting for review. Bright Data will verify both UX and functionality during the approval process.
Examples of opted-in and opted-out scenarios:
opt-in-out-windows-1

opt-in-out-windows-2

opt-in-out-windows-3

opt-in-out-windows-4

Value Text Examples:
When opted-out:When opted-in:
Enable to see fewer adsWhen enabled you see fewer ads
Enable to get 100 extra coinsWhen enabled you get 100 extra coins
Enable to enjoy premium featuresWhen enabled you enjoy premium features
Enable to get 2 free carsWhen enabled you get 2 free cars
Enable to unlock more levelsWhen enabled you unlock more levels
Common Mistakes to Avoid:
ExampleIssue
Label: “Bright SDK”❌ Label should be “Web Indexing”, not “Bright/Bright SDK”
Switch without value text❌ Missing text emphasizing value to users
Switch without status indicator❌ Switch should clearly show current opt-in/opt-out status
No “Learn More” option❌ Missing link/QR code to information page
You may add pop-up/confirmation dialogs to:
  • Discourage opt-out: “If you disable Web Indexing, you will start seeing ads. Do you want to see ads?”
  • Confirm opt-out: “You have successfully disabled Web Indexing. You may enable it again anytime from the settings menu.”
You are responsible for the text and design. These will be reviewed before publishing.
Opt-Out Messages examples:
opt-in-out-windows-5

opt-in-out-windows-6

5

Update Application Installer

Install:
  1. Add the following text to your installation wizard under “License agreement”:
{App name} installs Bright Data components (no execution).
You will be able to view the component details in full before you accept this offer, as well as being able to turn Bright Data on and off directly from the 'App Settings'. Read more about Bright Data's EULA here.
  1. Add step to deploy the following to your install directory:
    • lum_sdk.dll
    • net_updater32.exe
    • Brd_config.json
  2. Add step to execute Bright Data service installer during app installation (recommended, optional):
    • Process to start: net_updater32.exe --install-ui APPID It will show the consent screen and if agreed, install the service.
  3. Run net_updater32.exe -h in command prompt to see available --dlg- parameters, or set them in brd_config.json.
  4. Wait for the process to finish before proceeding.
Uninstall:Add the following to your application’s uninstall script:
  1. Make sure no process uses lum_sdk.dll (terminate your application).
  2. Uninstall Bright Data service and remove all SDK files by executing  net_updater32.exe --uninstall APPID.
  3. Wait for uninstall to finish before proceeding.
Update:Add the following to your application’s update script:
  1. Stop your application (which is using lum_sdk.dll).
  2. Stop Bright Data service: luminati_net_updater_APPID
    • Where APPID is your assigned APPID with . (dot) replaced with _ (underscore).
    • Example: win_abc.myapp.comluminati_net_updater_win_abc_myapp_com.
  3. Deploy new files:
    • net_updater32.exe
    • lum_sdk.dll
    • Brd_config.json your
  4. Choose one option:
    1. Option A: Install new net_updater : net_updater32.exe --install-ui APPID 
      • Shows consent to user (they can accept or decline).
      • Requires admin privileges.
      • Use brd_config.json for consent customization.
    2. Option B: Restart service if it exists
      • Does not require admin privileges.
      • Does not show consent.
6

Add SDK Service Status Notifications (Optional)

NotificationsYou can register your app for notifications about the SDK service status. This allows you to:
  • Know if the SDK is in a valid usable state.
  • Prevent users from receiving benefits until they restore the SDK service.
Implementation: Add delegate for the BrightData.Api.ServiceStatusChanged event, the handler for the event is an EventHandler that receives the BrightData.Api.ServiceStatusChangedEventArgs as event data.See ServiceStatus enum for more information on the different status.
The callback function can be called from a different thread than the one used to register the callback.
RecoveryIf the ServiceStatus is NotInstalled, Installed, or NotRunning, you can use the FixServiceStatus API to trigger automatic recovery.You can also trigger this on user action (e.g., “Click here to fix Bright Data SDK and regain benefit”).
8

Self-Check Your Integration

Testing ModeYou may set BrightData.Api.Settings.TestMode = true while developing. This way the BrightData service will not be installed when you accept the consent screen, making it easier to develop.Resetting During TestingWhile testing, you can:Option 1: Opt-out through settings
  • Remove Bright Data service by opting out through your application settings.
  • Delete the luminati folder (or your entire output folder).
  • This resets your consent choice.
  • Consent screen will display next time you run the application.
Option 2: Uninstall via command
  • Execute net_updater32.exe --uninstall APPID in your output folder.
  • This deletes all SDK files.
9

Update Your Terms of Service

Bright Data ensures users are fully informed about joining the peer network.Add the following text to your Terms of Service web page (TOS, EULA, or Privacy Policy):In return for premium features of ‘[Your App Name]’, you may choose to be a peer on the Bright Data network. By doing so, you agree to have read and accepted the Bright SDK EULA and Bright Data’s Privacy Policy.You may opt out of the Bright Data network by [add clear opt-out instructions].Requirements:
  1. Include all text and links as provided above.
  2. Any additional Bright SDK-related content must be shared during the app review process for approval.
10

Submit your integration for review

11

How to Update SDK

  1. Download the latest SDK using the Bright SDK downloader.
  2. Replace the following files with the newer versions:
    • net_updater32.exe (or net_updater64.exe)
    • lum_sdk.dll (or lum_sdk32.dll / lum_sdk64.dll for C/C++)
    • brd_config.json
  3. Clean and rebuild your project.
12

Code Example

Main Application Form:
public partial class ExampleAppMainForm : Form
{
  private BrightData.Api _brightSdk = new BrightData.Api();
  private void BrightSdk_ConsentChoiceChanged(object sender,
      BrightData.Api.ConsentChoiceChangedEventArgs e)
  {
    if (e.Choice == true)
    {
      // user agreed to Bright Data consent
      // you can disable ads here, for example
    }
    else
    {
      // user disagreed to the consent or opted out
      // you can enable ads here, for example
    }
  }
  private void BrightSdk_ServiceStatusChanged(object sender,
      BrightData.Api.ServiceStatusChangedEventArgs e)
  {
    if (!_brightSdk.ConsentChoice)
      return;

    if (e.Status == BrightData.Api.ServiceStatus.NotInstalled)
    {
      // optional: notify user about SDK service not installed and offer to recover
      // optional: automatically try and recover (might cause bad UX)
      if (userWantsToRecover || autoRecoverIsEnabled)
        _brightSdk.FixServiceStatus();
    }
    else if (e.Status == BrightData.Api.ServiceStatus.Installed ||
      e.Status == BrightData.Api.ServiceStatus.NotRunning)
    {
      // optional: notify user about SDK service not running and offer to recover
      // optional: automatically try and recover (might cause bad UX)
      if (userWantsToRecover || autoRecoverIsEnabled)
        _brightSdk.FixServiceStatus();
    }
  }
  protected override void OnFormClosing(FormClosingEventArgs e) 
  {
      _brightSdk.Close();
      base.OnFormClosing(e);
  }
  private void SettingsToolStripMenuItem_Click(object sender, EventArgs e)
  {
    new SettingsForm(_brightSdk).ShowDialog();
  }
}
Settings Form:
public partial class SettingsForm : Form
{
  private readonly BrightData.Api _brightSdk;
  public SettingsForm(BrightData.Api brightSdk)
  {
    InitializeComponent();
    _brightSdk = brightSdk;
    _brightSdk.ConsentChoiceChanged += BrightSdk_ConsentChoiceChanged;
    _chkBrightData.AutoCheck = false;
    _chkBrightData.Checked = _brightSdk.ConsentChoice ?? false;
    _chkBrightData.Click += ChkBrightData_Click;
  }
  protected override void OnClosing(CancelEventArgs e)
  {
    // make sure to avoid event handler leak
    _brightSdk.ConsentChoiceChanged -= BrightSdk_ConsentChoiceChanged;
    base.OnClosing(e);
  }
  private void ChkBrightData_Click(object sender, EventArgs e)
  {
    if (_brightSdk.ConsentChoice == true)
      _brightSdk.OptOut();
    else
      _brightSdk.ShowConsent();
  }
  private void BrightSdk_ConsentChoiceChanged(object sender,
    BrightData.Api.ConsentChoiceChangedEventArgs e)
  {
    _chkBrightData.Checked = e.Choice ?? false;
  }
}
13

API Documentation

  • Settings in brd_config.json are shared by both lum_sdk.dll and net_updater32.exe.
  • You can use the config file together with the programmatic API.
  • Programmatic API settings take precedence over config file settings.
Required Properties
PropertyTypeDescription
app_idstringYour APPID
app_namestringFriendly name of your app that appears on the consent screen
logo_linkstringURL to your app’s logo for the consent screen
Optional Properties
PropertyTypeDescription
benefitstringDescription of benefits user gets when enabling SDK. Changes consent screen wording. Becomes the first part of the first sentence on the consent screen
agree_btnstringText of the consent screen’s agree button
disagree_btnstringText of the consent screen’s disagree button
opt_out_txtstringText of the consent screen’s opt-out instructions
Methods
MethodDescription
void BrightData.Api.Init(Settings settings)Initializes Bright SDK. Should be called during app initialization. All other methods will be accessible afterwards. By default, consent screen will be shown if the user hasn’t made a choice yet, but can be skipped with Settings.SkipConsent = true
void BrightData.Api.ShowConsent()Displays consent screen. (Clears user choice and removes Brightdata service if installed.) Can be used when a user tries to close an ad or clicks the checkbox to activate Bright SDK
void BrightData.Api.OptOut()Disables Bright SDK and removes Brightdata service. ConsentChoice will change to false
void BrightData.Api.Close()Closes Bright SDK. Should be called when the application exits if the SDK cannot automatically detect the application exit and keeps running, keeping the app process running
string BrightData.Api.GetUuid()Returns the peer’s unique identifier. Useful for debugging
Properties
PropertyDescription
bool? BrightData.Api.ConsentChoice { get; }Returns the user’s consent choice. true if the user agreed, false if disagreed and null if no choice has been made
Events
EventDescription
event BrightData.Api.ConsentChoiceChangedOccurs when the user’s consent choice has changed. For example when they accepted the consent or they disabled Bright SDK through your application settings
event BrightData.Api.ConsentDialogShownOccurs when the consent dialog is shown
event BrightData.Api.ConsentDialogClosedOccurs when the consent dialog is closed
Event Example
_brightSdk.ConsentChoiceChanged += (sender, e) => 
{
    if (e.Choice == true)
        // User opted in
    else
        // User opted out
};
class BrightData.Api.SettingsRequired Properties
PropertyTypeDescription
AppIdstringYour APPID. Required if not in brd_config.json
AppNamestringFriendly name for consent screen. Required if not in brd_config.json
AppLogostringURL to your app’s logo. Required if not in brd_config.json
Basic Configuration
PropertyTypeDefaultDescription
SkipConsentboolfalseIf true, Init won’t show consent screen. Use ShowConsent() to display later
Benefitstring-Description of benefits. Changes consent wording. Becomes first part of first sentence
OptOutTextstring-Text of consent opt-out instructions
Campaignstring-Optional parameter for statistics breakdown by campaign
Button Customization
PropertyTypeDescription
AgreeBtnstringText of consent screen’s agree button
DisagreeBtnstringText of consent screen’s disagree button
Visual Customization
PropertyTypeFormatDescription
TextColorstringHex ARGB “#AABBCCDD”Color of consent text
AppNameColorstringHex ARGB “#AABBCCDD”Color of application name text
BrightDataLogoColorstringHex ARGB “#AABBCCDD”Color of BrightData logo background
BackgroundColorstringHex ARGB “#AABBCCDD”Background color of consent screen
ButtonColorstringHex ARGB “#AABBCCDD”Button color of consent screen
Localization
PropertyTypeDefaultDescription
Languagestring”en-US”Language code for consent screen. Supported: en-US, de-De, es-Es, fr-FR, it-IT, pt-PT, ru-RU, zh-CN
Help & Information
ArgumentDescription
-hPrint command descriptions and help
Service Management
ArgumentDescription
--install-ui <appid>Install service with provided appid after showing dialog and getting user permission
--uninstall <appid>Remove service with provided appid (must match appid used during install)
--start-service <appid>Start Bright Data service
--stop-service <appid>Stop Bright Data service
--check-peer <appid>Validate peer
Dialog Customization
ArgumentDescription
--dlg-app-name <name>Friendly name of your app for consent screen
--dlg-logo-link <logo>URL to your app’s logo for consent screen
--dlg-benefit <benefit>Description of benefits. Changes consent wording
--dlg-language <culture>Language code. Default: “en-US”. Supported: en-US, de-De, es-Es, fr-FR, it-IT, pt-PT, ru-RU, zh-CN
Analytics
ArgumentDescription
--campaign <campaign_id>Optional parameter for statistics breakdown by campaign
Command Examples
# Install with dialog
net_updater32.exe --install-ui myapp.example.com
# Install with customization
net_updater32.exe --install-ui myapp.example.com --dlg-app-name "My App" --dlg-logo-link "https://example.com/logo.png"
# Uninstall
net_updater32.exe --uninstall myapp.example.com
# Start/Stop service
net_updater32.exe --start-service myapp.example.com
net_updater32.exe --stop-service myapp.example.com