Overview

Step 1: Updating your Terms of Service 

Step 2: Extract SDK framework from the distribution 

Step 2.1: SDK overview

Step 3: Integrate Bright SDK in your code 

Step 3.1: Prerequisites

Step 3.2: Prepare the files

Step 3.3: Embed SDK dialog in your code

Step 3.4: Details of SDK embedding in case of iFrame

Step 3.5: Add SDK initialization

Step 3.6: Add opt-in/out settings option

3.6.1 Adding opt-in/out to you existing settings menu

3.6.2 In case you do not have a settings menu

Step 3.7: Consent dialog customization (optional)

Step 3.8: App performance

Step 3.9: Build your app

Step 3.10: Self-check before submission

Step 3.11: Submit your integration

Experimental: custom consent screen

How to update SDK 

Updating Hosted Web App

API documentation 

API (JavaScript)

Overview

This guide is for developers who want to monetize WebOS applications with Bright SDK.

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

Note! Bright SDK for WebOS requires WebOS 5.0 or newer. (Here’s how to find out which version your TV is)

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

Step 1: Updating your Terms of Service

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

• Add the following text to your Terms of Service Web page (such as: TOS, EULA, or Privacy Policy):

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://bright-sdk.com/eula and Bright Data’s Privacy Policy: https://bright-sdk.com/privacy-policy

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

• Add the following text to your Frequently Asked Questions Web page:

You will get <value: ads free version/free feature> in exchange for safely using some of your device’s resources, and only in a manner that will not substantially affect the device's operation. You may turn this off from the settings menu. Please see our TOS [Link to TOS] and the SDK Privacy Policy at https://bright-sdk.com/privacy-policy for further information.

Please note: the text above must be added in full to your ToS, including the links. In case you wish to add any addition text that is related to Bright SDK, please share with us as part of the app review process.


Step 2: Extract SDK framework from the distribution

Download the latest Bright SDK from the Bright SDK Dashboard or by clicking the link provided in the latest release email.
Once you unzip the SDK, you will find:

• sample_app
• iframe_sample_app
• sdk
  • consent
    • brd_api.js
  • service
    • peer_node
    • util
    • index.js
    • package.json
    • services.json

Step 2.1: SDK overview

• Two samples (sample_app and iframe_sample_app) demonstrate possible integration options. sample_app represents the general architecture of webOS applications and can also be used for Hosted Web Apps. iframe_sample_app represents an option where your app is rendered in an iFrame.
• The main engine for the WebOS SDK is the service directory, which implements all the logic required to run SDK. Although the controlling interface is on the front-end side, implemented in consent.
• SDK integration is divided into 2 parts:
  • service - need to copy the service directory next to other services that you already use
  • consent screen which has to be integrated with the front-end part of your application brd_api.js

Step 3: Integrate Bright SDK in your code

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

Below you will see a sequence diagram for integrating the most common case:

Step 3.1: Prerequisites

Make sure you have the following:

• The latest Bright SDK version for WebOS (supported versions of webOS 5.0 and above)
• The latest WebOS CLI
• (Recommended) The latest WebOS Emulator or Simulator

Step 3.2: Prepare the files

• open package.json and set a correct name attribute. Preserve .brd_sdk postfix at the end. Leave the rest of the attributes untouched in this file.
• open services.json and set a correct id, services[0].id and services[0].name attributes. Preserve .brd_sdk postfix at the end. Leave the rest of the attributes untouched in this file.

Example: you've been given an appid - 'webos_com.example.app'. Your id in appinfo.json should be 'com.example.app'. The id in package.json and services.json must be 'com.example.app.brd_sdk'. The 'webos_' prefix to form the appid will be added by SDK.

Step 3.3: Embed SDK dialog in your code

You could use sample_app as a reference.

• Copy brd_api.js and webOSTV.js into your app directory and import it from the main file responsible for the initialization of the app. 
• After brd_api.js execution brd_api global object will be added.

Step 3.4: Details of SDK embedding in case of iFrame

In case if you render your app in an iFrame, the brd_api.js library must be included in the HTML page that is located on your server. Additional library brd_iframe.js (iframe_sample_app/lib/brd_iframe.js) must be included on the *.ipk side.

The optional iframe property on the api_settings object must be set to true.

The location of SDK components is presented in the table below.

Step 3.5: Add SDK initialization

• Call brd_api.init() after page load in order to get access to all other methods

Example:

<!DOCTYPE html>

<html>

  <head>

...

    <script>

      window.onload = function(){

  var api_settings = {

    app_name: 'BrightData WebOS Sample',

          app_logo: 'icon_130.png',

        };

        try {

    brd_api.init(api_settings, {

            on_failure: function(message){

              console.log('init failure. Error: ', message);

            },

            on_success: function(){ console.log('init success'); },

          });

        } catch(e){

          console.error(e); 

        }

      };

    </script>

...

  </head>

  <body>

...

  </body>

</html>

• The first time it is called on a device, brd_api.init() will show a consent screen. The user must agree or disagree. You can get the result by setting the on_status_change callback.

Step 3.6: Add opt-in/out settings option

3.6.1 Adding opt-in/out to you existing settings menu

⚠️ 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. 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. It’s best to include a QR code that will lead to the web page that shows more info https://bright-sdk.com/users#learn-more-about-bright-sdk-web-indexing. The QR code must be accompanied by the string "Scan the QR Code to learn more about web indexing by Bright Data". You can use your own branded QR code to the URL above, or use the QR below, or the hosted version.
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.
5. 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?”). You are responsible for the text and design for this implementation and it will be reviewed before publishing.

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

Some ideas for value text:

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

• “checked” state should be determined by call to brd_api.get_status()
  • status.consent is false - unchecked
  • status.consent is true - checked
• Click “uncheck” state should call brd_api.opt_out()
• Click “check” state (or if you’re implementing simple button behavior) should call brd_api.show_consent()

Exact UI and implementation depends on your language/environment/IDE, but these guidelines must be met.

Examples for common mistakes with opt-out settings screens:

Web Indexing Switch

Example	Comments
	The label should be Web Indexing, and not Bright/Bright SDK. Missing text to emphasize the value users get when opting in. The switch should clearly reflect the current status (is the user opted-in or not?).
	Missing text to emphasize the value users get when opting in.
	Missing “Learn more”, which opens a browser window with the following URL: https://bright-sdk.com/users#learn-more-about-bright-sdk-web-indexing. Missing text to emphasize the value users get when opting in.

Opt-Out Messages (Optional but highly recommended)

Example	Comments
	Correct messaging, correct default choice
	Dialog box to validate the user’s choice, reminding them how to opt back in.

3.6.2 In case you do not have a settings menu

You can use the ready to use out of the box UI for opt-out. In order to enable it you can set a simple_opt_out setting (see API). The simple opt-out allows a user to opt-out by pressing the button [5] on the remote control (this will re-open the consent screen).

If a user opted out, the consent screen will be shown after several app restarts (see repeat_consent). In the case of simple_opt_out, the repeat_consent setting is set to 3 by default. The consent screen will be shown after 3 restarts.

After a user closes the consent screen, a small notification will appear in the bottom left corner.

It will be hidden after 10 sec. This notification will be displayed every time the app is started (except the very first one).

You can assign custom text to the buttons on the consent screen invoked by pressing button [5] on the remote control. To do this, you can pass an object as a value of the simple_opt_out parameter. The object should contain the agree_btn and disagree_btn properties. 

These settings accept the same values as settings.agree_btn and settings.disagree_btn.

If the button texts are not overridden, then they will be inherited from the initial consent screen.

Example: 

{

agree_btn: 'Keep Ad-Free’,

disagree_btn: 'ADS',

}

With these settings, the consent screen will look like this:

Step 3.7: Consent dialog customization (optional)

You can customize the consent dialog by setting up additional parameters to the api_settings object passed to init() function.

Please find all available settings for consent screen customization here.

The following screenshot shows the possible fields for customization.

If all optional parameters are skipped, you will see the consent dialog as shown in the following screenshot.

Step 3.8: App performance

We care about the user experience at a high level, so it is important to pay attention to the performance of your app. Make sure that your app doesn't experience input lag, and that the CPU load is not high. We recommend not exceeding the average CPU load over 50% and not exceeding the RAM load over 90%.

If the system load is significant, we will not be able to use the free resources of the device. Such a device will not be counted as active and will not be paid.

To check the load on webOS, you can use the Beanviser from LG.

Step 3.9: Build your app

In order to build your app you must use ares-package CLI command. This command is a part of the WebOS CLI.

You must use “-n” option to disable the process of minifying the source code.

Example: ares-package -n app_folder service_folder

Step 3.10: Self-check before submission

To speed up the verification process, you can carry out a self-check before submitting. Make sure that your app works as described below:

• On the very first call to the init() function, the consent dialog is shown
• Press the disagree button. The consent dialog should close and the get_status() response must contain the consent property set to true
• Close your app and reopen it again. Call the init() function. The consent screen shouldn't be shown and the get_status() response must contain the consent property set to true
• Call show_consent() by pressing the checkbox (see “Add opt-in/out settings option” section). You should see the consent dialog
• Press the agree button. get_status()->consent must be true
• Restart your app one more time. Call the init() function. The consent screen shouldn't be shown and get_status()->consent must be true
• Call opt_out() by pressing the checkbox again. get_status()->consent must be false

If all the requirements described above are true then you are ready to proceed to the last step.

Step 3.11: Submit your integration

• 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 uploading the package (ipk format) 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.
• To help you go through a successful review by LG, we prepared this guide. We highly recommend that you follow it step by step, since the review time by  LG can take around 1 month.

Experimental: 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 mandatory text below (marked in red), as well as links to our terms and privacy policies.
2. If you wish to translate your screen into other languages, please find the most common ones here. If there is a language you miss here, contact your partnership manager and ask for it. Make sure you only use these translations precisely, without additions or omissions.
This is what it looks like on the default Bright SDK screen:

Mandatory text
“To [Benefit to user], please allow Web Indexing by Bright Data to use your device's free resources and IP address to download public web data from the Internet.
None of your personal information is collected, except your IP address. Bright Data does not track you. Scan the QR Code to learn more about Bright Data policy and ethical usage".

You can use your own branded QR code or hosted version, leading to this URL: https://bright-sdk.com/users#learn-more-about-bright-sdk-web-indexing

See below some examples of a possible custom consent screens (text in screenshot is not 100% compatible, so please use the text provided above):

Integration code

- You should pass `skip_consent: true` in SDK's initialization method to prevent showing the default consent screen.

- When the external consent screen is displayed on the screen, the `brd_api.consent_shown()` method must be called to ensure that the statistics are correctly recorded.
- The opt-in button (e.g. "I Agree”) should call `brd_api.external_opt_in()` method.
- The opt-out button (e.g. "I Disagree”) should call `brd_api.opt_out()` method.
Please contact Bright SDK before implementing in order to get pre-approved.

How to update SDK

Download the latest SDK from our website and follow these 3 simple steps:

• replace brd_api.js with a newer version
• delete the service directory and replace it with a newer version
• update package.json and services.json files as described in Step 3.2: Prepare the files

Updating Hosted Web App

If your app is Hosted Web App, you should pay attention to keep all SDK files from the same SDK version. In a Hosted Web App, the brd_api.js file is usually hosted on your web server. Before submitting a new app version to LG, please make sure you maintain backward compatibility with the old app version.

E.g. if in your IPK file you set a URL like www.mywebsite.com/myapp you should keep the old version of brd_api.js at that URL and use a different URL in the updated app - www.mywebsite.com/myapp/v2

API documentation

API (JavaScript):

• brd_api.init(settings, callbacks) - initialize the API. Should be called at the app init. All other methods will be accessible after successful initialization. Consent screen will be shown on first initialization by default, but can be skipped by setting skip_consent to true
• brd_api.show_consent(callbacks) - shows the consent on the user's action. This can be used when a user tries to close an ad or clicks the checkbox to activate Bright SDK

• brd_api.external_opt_in(callbacks) - if you use your own consent screen, call it after agreeing. For more details see Experimental: custom consent screen

• brd_api.opt_out(callbacks) - disable Bright SDK
• brd_api.get_status() - returns status object
• brd_api.consent_shown() - triggers post actions when a custom consent screen was shown. When you implement a custom consent screen you must call this method when the screen is presented
• status (object) properties:
  • consent (bool) - indicates current SDK status. Possible values:
    • true - SDK enabled and works
    • false - SDK disabled and disconnected
    • null - before the user pass consent screen for the first time
  • ver (string) - current SDK version, e.g. “1.285.476”
• settings (object) properties:
  • app_name (string) - your app name for the consent screen. Required
  • app_logo (string) - path to your app logo for the consent screen. Required
  • skip_consent (boolean) - can be passed to skip showing the consent screen on the initialisation of the API. The consent screen can be shown later with show_consent method.

simple_opt_out (boolean/object) - allow a user to opt-out by pressing [5] (this will reopen the consent screen). If a user opted out, the consent screen will be shown after several app restarts (see. repeat_consent).You can pass the object to this setting to redefine the consent button text. (for more see 3.6.2) Example:
{
agree_btn: 'Keep Ad-Free',

disagree_btn: 'ADS',
}

• repeat_consent (integer >= 3) - shows the consent screen after the specified number of app restarts. Active only if simple_opt_out is set to true.
• agree_btn (string/enum) - consent screen “agree” button text. Default value: “I_AGREE”. Possible values:

You can assign custom text to the button. If you pass a string value that is not present in the value enum, it will be displayed as the text of the button.

• disagree_btn (string/enum) - consent screen “disagree” button text. Default value: “Keep Ads”. Possible values:

You can assign custom text to the button. If you pass a string value that is not present in the value enum, it will be displayed as the text of the button.

• opt_out_instructions (string) - detailed instructions for users on how to disable the Bright SDK in your app's interface.
• benefit (string) - a description of the benefits a user gets if he/she consents to enable Bright SDK.
• iframe (bool) - must be set to true if you render your app in an iFrame. Default value: false
• on_status_change (function) - callback will be called every time the consent status is set.
• on_dialog_shown (function) - callback will be called when consent dialog is shown.
• on_dialog_closed (function) - callback will be called when consent dialog is closed.
• style (object) - describe custom visual styles for consent screen:
  • custom_background_image (false|string) - path to background image for consent screen.
  • agree_btn_focus_styles, disagree_btn_focus_styles, agree_btn_styles, disagree_btn_styles (string) - css styles for buttons. Example: 

background-image: url(accept_button.jpg);

border: 3px solid black;

background-color: #0000;

• custom_font_size, custom_title_font_size, custom_bottom_text_font_size, custom_button_font_size (string) - the values are being used as the css font-size property. Example: '1.2vw'.
• custom_font_family (string) - the values are being used as the css font-family property.
• custom_text_color, custom_text_button_color, custom_focus_text_button_color (string) - font colors. The values are being used as the css color property.
• custom_background_color, custom_background_button_color, custom_focus_background_button_color (string) - background colors. The values are being used as the css background-color property. Can be set to 'none' to get transparent with the background image.
  • custom_qr_code_color, custom_qr_code_bg_color (string) - colors for QR code.
  • shadow (boolean) - shadow for consent popup.
  • custom_icon_color, custom_icon_color (string) - icons background and image colors.
• callbacks (object) properties:
  • on_failure (function) - callback will be called when an error occurs in a called function.
  • on_success (function) - the callback will be called when the called function completes successfully.