Tizen SDK Integration Guide

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

API documentation 

Overview

This guide is for developers who want to monetize TizenOS 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 our Control Panel in 24 hours.

Note! Bright SDK for TizenOS requires Tizen 6.5 or newer. 

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://brightdata.com/legal/sdk-privacy for further information.

Step 2: Extract SDK framework from the distribution

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

• sample_app
• sdk
  • consent
    • brd_api.js
  • service
    • peer_node
    • util
    • sdk_service.js
    • service.js
    • ver_conf.js

Step 2.1: SDK overview

• Sample_app demonstrates possible integration options. sample_app represents the general architecture of Tizen TV applications and can also be used for Tizen Web Application.
• The main engine for the Tizen 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.

Step 3.1: Prerequisites

Make sure you have the following:

• The latest Bright SDK version for Tizen (supported versions of Tizen 2.4 and above)
• The latest Tizen Studio

Step 3.2: Prepare the files

• copy sdk/service folder to your project
• add service to config.xml 

...   

    <tizen:privilege name='http://tizen.org/privilege/alarm'/> 

    <tizen:service id="brdsample0.Service">

        <tizen:content src="service/service.js"/>

        <tizen:name>WebUIService</tizen:name>

        <tizen:description>WebUIService</tizen:description>

        <tizen:metadata key="meta-key" value="meta-value"/>

        <tizen:category name="http://tizen.org/category/service"/>

    </tizen:service>

...

• replace here brdsample0 to your package id

Tip:

after creating a Tizen app, if it has not been published previously, we recommend changing the package ID to something more readable. Use your partner ID from our CP. For example, "blUqHYQcnKEE.actionGames" will change to "brightdata.actionGames".  

Follow Tizen requirements for generating the package and application ID. If your Partner ID contains illegal characters, you can remove them. For example "super_games" -> "SuperGames".

The 'tizen_' 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 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.

<!DOCTYPE html>

<html>

  <head>

...

    <script src=brd_api.js></script>

  </head>

  <body>

...

  </body>

</html>

Step 3.4: 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 Tizen 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://brightdata.com/sdk/information?is_tv=1 . 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 this QR in SVG, or use the hosted version on https://media.bright-sdk.com/2023/09/qr-bright-sdk-faq.svg
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://brightdata.com/sdk/information. 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 typing “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 typing [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.

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.

Step 3.9: Build your app

In order to build your app you must use Tizen CLI command.

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.
• Submit the app for review by uploading the package (wgt 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.
• 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 Samsung, 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:

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
• Check actual way to run service: see Prepare the files

API documentation