MacOS SDK Integration Guide

  • Updated

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:  Verify your integration 

Submit your app to review 

Custom consent screen 

 



 

 

General

This guide is for App developers who want to monetize a Mac app with Bright SDK.

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
  • net_updater.entitlements
  • resign_net_updater.sh - script to use in build phases to resign net_updater for your Apple team

Before using SDK and net_updater.app there're additional steps in Xcode project needed.


 

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:

  • Add net_updater.entitilements and resign_net_updater.sh files to your project folder (you don't need to add them to any target or Xcode). net_updater.entitlements must be placed under ${PROJECT_DIR} value.
  • 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.

  • If you have app sandbox entitlement, you won't be able to use SDK as it doesn't support sandboxing.
  • In Build Settings tab of main app target create custom setting NET_UPDATER_ENTITLEMENTS with a path to the net_updater.entitlements file relative to ${PROJECT_DIR} value. Set ENABLE_USER_SCRIPT_SANDBOXING to NO.\
  • Add a run-script build phase after copying net_updater in the main app's target, e.g. Resign net_updater.  Assign to it resign_net_updater.sh file or its content.
     

 

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: brd_api?


 

  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 brd_api(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

 

⚠️ 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 will usually first show the consent screen to the user on first run (or after a short “trial” period), the user will make a choice and SDK will act according to that choice.

 

Regardless of the user’s choice you must add an option for the user to opt-in/out of using SDK at any time. The user must always be able to opt-out of Bright SDK after giving their initial consent. 

 

This means that you must add an opt-out option in your app - this is usually placed in the settings menu

 

  1. Add a switch with the label “Web Indexing”. The switch should clearly reflect the current status (is the user opted-in or not?).
  2. Below Web Indexing add your own text to emphasize the value users get when opting in.
  3. Include a way to give more information to the user (“Learn more”). The hyperlink should open a browser window with the following URL: https://bright-sdk.com/users#learn-more-about-bright-sdk-web-indexing.
  4. In general, you are free to choose the UX (radio button, switch, etc) but the opt-out option must be clearly labeled so users can freely opt-out.

 

See the examples below, illustrating both opted-in and opted-out scenarios:



 

6 off.png 6 on.png
4 off.png 4 on.png

 

Some ideas for value text:

 

When opted-out When opted-in
Enable to see fewer ads When enabled you see fewer ads
Enable to get 100 extra coins When enabled you get 100 extra coins
Enable to enjoy premium features When enabled you enjoy premium features
Enable to get 2 free cars When enabled you get 2 free cars
Enable to unlock more levels When enabled you unlock more levels

 

  • Refrain from using the technical term “opt in” / “opt out”. We always prefer speaking value to users.
  • FYI: You are free to add a pop up / confirmation dialog box to discourage the user from opting out (for example: “if you disable Web Indexing, you will start seeing ads. Do you want to see ads?”), as well as a confirmation message that shows after opting out (for example: “You have successfully disabled Web Indexing. !you may enable it again anytime from settings menu”)

 

You are responsible for the text and design for this implementation and it will be reviewed before publishing. Please refrain from using the technical term “opt in” / “opt out” here as well. 

Use the SDK’s public API to implement the UI responsible for switching on and off the Bright SDK.

 

 

  • 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:  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: