Skip to main content

​
Requirements

  • macOS 10.15 or newer.
  • Xcode (latest recommended).
  • Bright SDK for macOS (latest).

​
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.
  • App Sandbox is not supported. If your app has the sandbox entitlement enabled, the SDK will not function.
  • 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.
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 framework in your macOS app in two ways:
  • Using the Bright SDK Integration CLI Tool Recommended - automatically downloads the SDK, extracts the framework, and patches your Xcode project with the necessary references, copy phases, build settings, and re-sign script.
  • Manually - download the SDK from the dashboard, unzip it, and copy the files yourself.
Either way, you will still need to add the SDK initialization code to your app.
Run the tool using the bright-sdk-integration CLI. See the Apple example for full setup instructions.The tool will:
  • Download the latest BrightSDK zip from cdn.bright-sdk.com/static/.
  • Extract brdsdk.framework and net_updater.app into BrightSDK/.
  • Patch your project.pbxproj — adding brdsdk.framework and net_updater.app with Embed & Sign, setting FRAMEWORK_SEARCH_PATHS and LD_RUNPATH_SEARCH_PATHS.
  • Add a Copy Files build phase placing net_updater.app under Contents/Library/LoginItems.
  • Add a Resign run-script build phase using resign_net_updater.sh.
  • Set build settings: NET_UPDATER_ENTITLEMENTS and ENABLE_USER_SCRIPT_SANDBOXING = NO.
  • Save brd_sdk.config.json for future runs.
Once the tool completes, skip to Step 3 - Integrate Bright SDK.
Download the latest Bright SDK using the Bright SDK downloader. Unzip it.SDK Structure
brdsdk.framework
net_updater.app
net_updater.entitlements
resign_net_updater.sh
SDK Overview
ComponentDescription
brdsdk.frameworkSDK control API
net_updater.appSDK background control service
net_updater.entitlementsEntitlements file required for re-signing net_updater
resign_net_updater.shScript used in build phases to re-sign net_updater for your Apple team
Before using brdsdk.framework and net_updater.app, additional Xcode project configuration steps are required — see Project Setup.
3

Integrate Bright SDK

1

Project Setup

CLI Tool users: brdsdk.framework and net_updater.app are already added and fully configured - skip to Import the SDK.
Add the Framework and Service to Your Target
  1. In Xcode, select your target and navigate to the General tab.
  2. In the Frameworks, Libraries, and Embedded Content section, add both brdsdk.framework and net_updater.app.
Alt text
  1. Both items will now appear in the project structure.
Alt textConfigure net_updater Copy Location
  1. Navigate to Build Phases.
  2. In the Copy Bundle Resources section, remove net_updater.
Alt text
  1. Add a new Copy Files build phase:
    • Set Destination to Wrapper.
    • Set Subpath to Contents/Library/LoginItems.
    • Add net_updater to this phase. Alt text
Add Supporting Files
  • Copy net_updater.entitlements and resign_net_updater.sh into your project folder.
  • These files do not need to be added to any Xcode target.
  • net_updater.entitlements must be placed under the ${PROJECT_DIR} path.
Configure Build SettingsIn the Build Settings tab of your main app target, create a custom setting:
  • Key: NET_UPDATER_ENTITLEMENTS
  • Value: Path to net_updater.entitlements relative to ${PROJECT_DIR}
  • Set ENABLE_USER_SCRIPT_SANDBOXING to NO
Add Re-sign Build Phase
  • Add a Run Script build phase after the net_updater copy phase (e.g., name it "Resign net_updater").
  • Assign resign_net_updater.sh as its content (or paste the script contents directly).
Alt text
App Sandbox is not supported. If your app has the sandbox entitlement, the SDK will not function.
2

Import the SDK

In your AppDelegate.swift, import the Bright SDK:
import Cocoa
// ... other imports ...
import brdsdk
3

Initialize the SDK

Initialize the SDK once in your AppDelegate, typically inside applicationDidFinishLaunching. Create a dedicated setup function (e.g., start_bright_sdk) to keep initialization clean. Should be invoked only once.
@NSApplicationMain
class AppDelegate: NSObject, NSApplicationDelegate {

    var sdk: brd_api?

    func applicationDidFinishLaunching(_ aNotification: Notification) {
        // ...
        try? start_bright_sdk()
        // ...
    }

    func start_bright_sdk() throws {
        sdk = try brd_api(campaign: nil,
                         on_choice_change: { [weak self] new_choice in
            // Handle user selection
            switch new_choice {
                case .peer:
                    // e.g. update local settings — SDK enabled
                    myapp.options.set_bright_sdk_enabled()
                case .notPeer:
                    // e.g. start a subscription process
                    start_subscription_process()
                case .none:
                    // e.g. update local settings — SDK disabled
                    myapp.options.set_bright_sdk_disabled()
            }
        })
        show_bright_sdk()
    }

    func show_bright_sdk() {
        sdk?.show_consent(force: true, on_choice: { _ in })
    }
}
4

Add Opt-In/Out Settings Option

6

App Performance

We prioritize user experience. Ensure your app maintains good performance.Performance Guidelines:
  1. ✅ No input lag - ensure responsive UI interactions.
  2. ✅ Average CPU load: ≤ 50%.
  3. ✅ RAM usage: ≤ 90%.
Important: If system load is too high, we cannot use the device’s free resources. Such devices will not be counted as active and will not generate revenue.
7

Verify Your Integration

Before submitting, verify that the SDK is running correctly on your device:
  1. Compile and run your app, then click “I Agree” in the SDK consent dialog.
  2. Open a terminal and run: 
    ps -ef | grep [n]et_
    You should see 1 process running from inside your app directory: net_updater.
  3. Navigate to: 
    /Users/{USER}/Library/Group Containers/<team_id>.com.brdsdk.shared
  4. Look for the cid file matching your Bundle ID. It should look similar to: 
    10.59.36.4-ccaa3e53/ls17c2p443_10.59.36.4_60015
If the SDK isn’t initializing / peer not connecting:
  1. Verify the correct App ID is used, confirm the SDK service is running.
  2. Check there aren’t multiple SDK apps running from the same IP — that can interfere.
  3. If nothing helps, check with our team.
8

Update Your Terms of Service

9

Submit Your Integration for Review

10

How to Update the SDK

11

API Documentation

To be updated