MacOS SDK Integration Guide

Integrating the Bright SDK into an app is the first step toward earning revenue. Once you've integrated the SDK, you will start seeing revenue in our dashboard in 24 hours.

This document will walk you through the steps needed to be taken in order to properly integrate Bright SDK into your app.

Step 1: Updating your Terms of service

Bright SDK works tirelessly to make sure users are fully aware of what it means to become a peer in Bright Data network. Please follow the terms of service additions that need to be done below.

Add the following text to your Terms of service doc:

In return for some of the premium features of ‘[name of Partner Solution]’, you may choose to be a peer on the Bright Data network. By doing so you agree to have read and

accepted the Terms of Service of the Bright SDK EULA:

https://brightdata.com/legal/sdk-eula and Bright Data’s Privacy Policy https://brightdata.com/legal/sdk-privacy.

You may opt out of the Bright Data network by clicking [add clear description for how to opt-out].

BrightSDK does not collect any personal information, except for the user’s IP address. Bright Data knows that a certain IP *exists* but not who owns it, or any other information.

Step 2: Extract SDK framework from the distribution

Download the latest Bright SDK from the Bright SDK Control Panel (soon) or by clicking the link provided in the latest release email.
Once you unzip the SDK, you will find:

brdsdk.framework - SDK control api
net_updater.app - SDK background control service

Before using net_updater.app and its launcher they must be re-sign with your account's certificate and entitlements for your account.

codesign -f --timestamp -s "<certificate title>" net_updater.app

Step 3: Integrate Bright SDK in your code (swift)

By now you have updated your TOS, downloaded the latest SDK distributive. Now you are ready to implement the SDK in your code.

Step 3.1: Prerequisites

Make sure you have the following:

Latest Bright SDK version for macOS
Minimal supported macOS version is 10.15.

Step 3.2: Project setup

Add SDK framework and net_updater.app into your app project:

In Xcode select your target and navigate to tab General
In Framework, Libraries and Embedded Content section add the framework and net_updater

You'll see both items in the project structure:

Navigate to Build Phases and in section Copy Bundle Resources remove net_updater.

Add new copy files script there, select destination Wrapper and subpath Contents/Library/LoginItems. Add net_updater there.

In tab Signing & Capabilities add App Group entitlement with value com.brdsdk.shared.
If you have app sandbox entitlement, select incoming and outgoing network connections there. (Note the SDK doesn't support distributing through AppStore)

As net_updater and its launcher are signed by our account, they must be resigned by your certificate. So firstly create a plist entitlements file which contains the same property for App Group:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<dict>

<key>com.apple.security.application-groups</key>

<array>

<string>XXXXXXXXXX.com.brdsdk.shared</string>

</array>

</dict>

</plist>

Replace XXXXXXXXXX on your apple team id, which is used in the main app.

And add a run-script build phase after copying net_updater in the main app's target, e.g. Resign net_updater

# Type a script or drag a script file from your workspace to insert its path.

NET_UPDATER_ENTITLEMENTS=<path to the plist>

codesign -f --deep --timestamp -o runtime -s "${EXPANDED_CODE_SIGN_IDENTITY_NAME}" --entitlements "${NET_UPDATER_ENTITLEMENTS}" "${TARGET_BUILD_DIR}/${CONTENTS_FOLDER_PATH}/Library/LoginItems/net_updater.app/Contents/Library/LoginItems/net_updater_launcher.app"

Assign to NET_UPDATER_ENTITLEMENTS path to the plist file. And in build settings set ENABLE_USER_SCRIPT_SANDBOXING to YES.

Step 3.3: Import the Bright SDK in your ApplicationMain (AppDelegate)

In your AppDelegate code:

Import Bright SDK:
import brdsdk
See example code on AppDelegate.swift file

import Cocoa

import ....

import brdsdk

Step 3.4: Initialize Bright SDK in your AppDelegate code

Create new function, eg start_bright_sdk to setup the sdk and interaction elements using apis. Should be invoked only once.
See example code on AppDelegate file:

@NSApplicationMain

class AppDelegate NSObject, NSApplicationDelegate {

....

var sdk: brdsdk?

func applicationDidFinishLaunching(_ aNotification: Notification) {

....

// example using MyApp dir in Users Application Support dir

try start_bright_sdk()

....

}
func … {}

func … {}

func start_bright_sdk() throws {

// setting up the SDK dialog

sdk = try brdsdk(campaign: nil,

on_choice_change: { [weak self] new_choice in

// Pseudocode for handling user selection (not mandatory, can
// use sdk.choice directly instead)
switch (choice){

case .peer:
// example code that will update local settings
myapp.options.set_bright_sdk_enabled()
case .notPeer:
// example code that will start

// a subscription process

start_subscription_process();
case .none:

// example code that will update local settings
myapp.options.set_bright_sdk_disabled();
}

})

show_bright_sdk()

}

func show_bright_sdk(){

sdk?.show_consent(force: true, on_choice: { _ in

})

}

Step 3.5: Adding ‘opt-in/out’ option from settings

Add checkbox to your options screen or item to app main menu
Title should represent what the user is getting from the deal (the call-to-action for the users)
- Examples:
  - “Disable ads by sharing my computer idle resources”
  - “Get premium features for free”
- Subtext for the option should read “Share idle resources (brightdata.com)”
Initial checkbox state should be sdk?.choice==.peer
Add control code for checkbox:

@IBOutlet weak var bright_sdk_checkbox: NSButton!

@IBAction func bright_sdk_checkbox_action(_ sender: NSButton) {

if bright_sdk_checkbox.state==NSControl.StateValue.off {

bright_sdk_checkbox.state = .off

} else {

bright_sdk_checkbox.state = .on

// not mandatory just to sync checkbox with sdk in case of error

show_bright_sdk()

}

Step 4: Integrate Bright SDK in your code (objective-C)

Step 4.1: Setup

Follow the same steps to setup your project as in sections 3.1 and 3.2

Step 4.2: Import the Bright SDK in your ApplicationMain (AppDelegate)

In your AppDelegate code:

Import Bright SDK:
#import <brdsdk/brdsdk.h>
See example code on AppDelegate.m file

#import “AppDelegate.h”

#import ....

#import <brdsdk/brdsdk.h>

Step 4.3: Initialize Bright SDK in your AppDelegate code

Create new function, eg start_bright_sdk to setup the sdk and interaction elements using apis. Should be invoked only once.
See example code on AppDelegate file:

....

brdsdk *sdk = NULL;

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {

....

// example using MyApp dir in Users Application Support dir

[self start_bright_sdk];

....

}
....

- (void)start_bright_sdk {

// setting up the SDK dialog

self.sdk = [[brdsdk alloc] initWithApp_name:NULL app_logo:NULL app_image:NULL agree_btn:@"I Agree" disagree_btn:@"I Disagree"

benefit_txt:NULL opt_out_details:NULL campaign:NULL error:NULL

on_choice_change:^(enum Choice choice) {

NSLog(@"INIT CHOICE %ld", choice);

}];

sdk.on_choice_change = ^void(NSInteger choice){

// Pseudocode for handling user selection (not mandatory, can
// use sdk.choice directly instead).

// See example in swift above.
switch (choice) {

case ChoiceNone: break;

case ChoicePeer: break;

case ChoiceNotPeer: break;

}

[self show_bright_sdk];

}

- (void)show_bright_sdk {

// example using logo from app resource dir

[self.sdk show_consentWithForce:YES on_choice:^(enum Choice choice) {

}];

}

Step 4.4: Adding ‘opt-in/out’ option from settings

Add checkbox to your options screen or item to app main menu
Title should represent what the user is getting from the deal (the call-to-action for the users)
- Examples:
  - “Disable ads by sharing my computer idle resources”
  - “Get premium features for free”
- Subtext for the option should read “Share idle resources (brightdata.com)”
Initial checkbox state should be sdk.choice==sdk.CHOICE_PEER
Add control code for checkbox:

(TODO: add ObjC equivalent pseudocode for this)

@IBOutlet weak var bright_sdk_checkbox: NSButton!

@IBAction func bright_sdk_checkbox_action(_ sender: NSButton) {

if bright_sdk_checkbox.state==NSControl.StateValue.off {

bright_sdk_checkbox.state = .off

sdk?.clear_choice()

} else {

bright_sdk_checkbox.state = .on

// not mandatory just to sync checkbox with sdk in case of error

sdk?.clear_choice()

show_bright_sdk()

}

Step 5: Verify your integration

Compile and run your application on your device and click “I Agree” in the sdk dialog
Open shell and run ‘ps -ef | grep [n]et_’, should see 1 process running from inside your app dir: net_updater
Goto /Users/{USER}/Library/Group Containers/<team_id>.com.brdsdk.shared
Look for the cid file with your bundle id, it should look something like this:

10.59.36.4-ccaa3e53/ls17c2p443_10.59.36.4_60015

Submit your app to review

Important: Bright SDK compliance team will verify the UX and functionality of the SDK integration, including consent screen, opt-out, value added to user, etc. Please do some internal QA prior to submitting the app for review.
When you are ready to submit the app, the first step is running a self-check, which takes a few minutes and can save you precious time by identifying implementation issues. Details here.
Submit the app for review by sharing the app build for review through the Bright SDK Dashboard: click the relevant appID and “Submit for Review” button.
As part of the submission process you will go through our checklist questions, to help you validate your app compliance to some of our main guidelines. Paying attention to this checklist, as well as to our quality standards will lead to faster approval.
We also welcome you to watch our guided tour video prior to submission. It highlights critical elements to pay attention to, ensuring a faster review process and transparent communication with your users.
Please note that we will review each app up to 3 times. 3 review rejections, or failure to meet our minimum quality standards may lead to a final rejection of your app.
How to submit the app build: You can upload a file (zip, pkg, dmg) into the “submit for review” window on our dashboard.

After Bright Data approves your build, legal documents etc you may publish it and start monetizing!

Custom 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 text as well as our links to our terms and privacy, this is what it looks like on the default Bright SDK screen:

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

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

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

- The link to "End User License Agreement" leads to "https://brightdata.com/legal/sdk-eula"

- Clicking/tapping on "will only use" -> opens a popup with the following info:

- Clicking/tapping on "never" -> opens a popup with the following info:

MacOS SDK Integration Guide

General

Step 1: Updating your Terms of service

Step 2: Extract SDK framework from the distribution

Step 3: Integrate Bright SDK in your code (swift)

Step 3.1: Prerequisites

Step 3.2: Project setup

Step 3.3: Import the Bright SDK in your ApplicationMain (AppDelegate)

Step 3.4: Initialize Bright SDK in your AppDelegate code

Step 3.5: Adding ‘opt-in/out’ option from settings

Step 4: Integrate Bright SDK in your code (objective-C)

Step 4.1: Setup

Step 4.2: Import the Bright SDK in your ApplicationMain (AppDelegate)

Step 4.3: Initialize Bright SDK in your AppDelegate code

Step 4.4: Adding ‘opt-in/out’ option from settings

Step 5: Verify your integration

Submit your app to review

Custom consent screen

Design of your consent screen

Can't find what you're looking for?

In this article

Toggle navigation menu

Toggle navigation menu

<%= category.name %>

<%= section.name %>

General

Step 1: Updating your Terms of service

Step 2: Extract SDK framework from the distribution

Step 3: Integrate Bright SDK in your code (swift)

Step 3.1: Prerequisites

Step 3.2: Project setup

Step 3.3: Import the Bright SDK in your ApplicationMain (AppDelegate)

Step 3.4: Initialize Bright SDK in your AppDelegate code

Step 3.5: Adding ‘opt-in/out’ option from settings

Step 4: Integrate Bright SDK in your code (objective-C)

Step 4.1: Setup

Step 4.2: Import the Bright SDK in your ApplicationMain (AppDelegate)

Step 4.3: Initialize Bright SDK in your AppDelegate code

Step 4.4: Adding ‘opt-in/out’ option from settings

Step 5: Verify your integration

Submit your app to review

Custom consent screen

Design of your consent screen

Can't find what you're looking for?

In this article

Toggle navigation menu

Toggle navigation menu

<%= category.name %>

Toggle navigation menu

Categories

<%= section.name %>