Web Content Provider Development Guide

Starting from 4.2, Samsung Internet for Android lets 3rd party apps recommend valuable contents to desiring users. You can show users contents that might interest them while they browse the web.

Overview

Samsung Internet for Android will provide information on the current web page that the user is viewing, so your extension app can recommend contents based on that information. The information will be available if the current web page that the user is viewing is belongs to a white-listed (provided by your app) URL host, and if the user granted permission to your app.

Web content provider apps pre-registered to Samsung Internet for Android will be listed in our Extensions menu, and can be installed, enabled, and disabled from there. Details for registering your app to Samsung Internet for Android are described in the Basic Guideline section.

While or after installing your extension app, users need to accept your EULA to enable it. Your EULA should include a statement that notifies users that their browsing data will be used. Samsung Internet for Android will ask users to accept your EULA if they try to enable it without agreeing to it.

After the user enables your web content provider extension app, Samsung Internet for Android will request user permission info, configurations and URL host white-list from your app, and start checking the white-list when user visits web pages.

When the user visits a white-listed web page, Samsung Internet for Android will send the URL and meta-elements of the current page to your app so that your app can recommend proper contents to the user. Your app should use the URL and meta-elements to show your contents to users on top of Samsung Internet for Android with your own UI. Samsung Internet for Android does not provide the UI for showing your contents.

Basic Guidelines

App Registration

To register your app to Samsung Internet for Android, the following preconditions need to be met.

  1. Add the following uses-permission in your AndroidManifest.xml file.

    <uses-permission
    android:name="com.sec.android.app.sbrowser.permission.WEBCONTENTSPROVIDER" />
    
  2. Include the version info for our Web Content Provider interface in your AndroidManifest.xml file.

    <meta-data
    android:name="com.sec.android.app.sbrowser.webcontentsprovider.VERSION"
    android:value="1.0" />
    <meta-data
    android:name="com.sec.android.app.sbrowser.webcontentsprovider.INTERFACE_VERSION"
    android:value="1.4" />
    
  3. Include intent service class name for handling Web Content Provider interface in your AndroidManifest.xml file.

    <meta-data
    android:name="com.sec.android.app.sbrowser.webcontentsprovider.SERVICE_CLASS_NAME"
    android:value="com.example.sampleApp.sampleIntentService" />
    
Validation Process

The validation process from Samsung is designed to make sure that the extension interface between the extensions app and Samsung Internet is properly used, and the extension app can be properly enabled and disabled from Samsung Internet. The intent of the validation process is to make sure that the app is not misleading the user. You need to send the final apk of your app to browser@samsung.com and follow the validation process before uploading your apps to public app markets. Detailed guidelines will be provided via e-mail, and the validation process takes around 1 week. Once validated, the package name and signature will be registered, and your app will be listed in our Extensions settings.

* Samsung reserves the rights to change the validation process without prior notice.

Enabling the Extension App

Samsung Internet for Android provides an “Extensions” menu, where users can view the list of available extension apps and enable/disable them. For your extension app to be properly enabled, Samsung Internet for Android needs to check that the user has agreed to your EULA. The following intents are essential to successfully enable your extension app for Samsung Internet for Android.

  1. Update User Permission action

    Whenever the user accepts or declines the EULA of your app, you need to broadcast an Intent with the following action, extra, and data.

    Intent intent = new Intent();
    intent.setAction("com.sec.android.app.sbrowser.webcontentsprovider.ACTION_UPDATE_USER_PERMISSION");
    intent.putExtra(“permission”, accepted_status); // accepted_status is true if user accepted your EULA, otherwise false.
    intent.setData(Uri.parse("package:<your_package_name>"));
    sendBroadcast(intent);
    
  2. Show Disclosure action

    If a user tries to enable your extension app from Samsung Internet for Android’s “Extensions” menu, but hasn’t accepted your EULA, Samsung Internet for Android will try to show your disclosure, using the following Intent.

    Intent intent = new Intent();
    intent.setAction("<your_package_name>.SHOW_DISCLOSURE");
    intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK);
    startActivity(intent);
    

    Your extension app will need to listen for the SHOW_DISCLOSURE intent, and on receiving it should 1) show your EULA to the user so they can accept it, and 2) send the UPDATE_USER_PERMISSION intent back to Samsung Internet for Android.

    If you receive a SHOW_DISCLOSURE intent after the user already accepted your EULA, you can skip the first part and just send the UPDATE_USER_PERMISSION intent and finish your activity.

Data Format

Samsung Internet for Android requests data from your extension app in order to check user permission status, what type of data you would like to receive, and the URL hosts that you would like to receive data for. The white-listed URL hosts should follow the W3C Spec to be properly handled by Samsung Internet for Android.

When a user opens a web page that belongs to a URL host in your white-list, Samsung Internet for Android will send you the URL and meta data of the web page. JSON format is used when sending the meta data, each meta element being represented as a JSONObject, and these elements are bundled and sent to your extension app as a JSONArray

[{“name”:”keywords”, “content”:”window treatments”},
 {“http-equiv”:”content-language”, “content”: “en”}]
Responding to Samsung Internet for Android’s Requests

Before sending web content data to your extension app, Samsung Internet for Android will request user permission info, configurations and the URL host white-list from your app. To get web contents information from Samsung Internet for Android, the following intents need to be handled.

  1. User Permission request

    Samsung Internet for android will ask your app to provide whether the user agreed to your EULA before starting communication with your app. Your IntentService should handle the ACTION_USER_PERMISSION intent in onHandleIntent(), and send a Bundle containing the query id and user permission status. The result code should be 1 when sending the Bundle to the ResultReceiver.

    @Override
    protected void onHandleIntent(Intent intent) {
        if(intent.equals(“com.sec.android.app.sbrowser.webcontentsprovider.ACTION_USER_PERMISSION”)) {
            Bundle resultData = new Bundle();
            resultData.putInt(“query_id”, intent.getIntExtra(“query_id”, -1));
            resultData.putBoolean(“permission”, true); // true if EULA is accepted, otherwise false
            ResultReceiver receiver = intent.getParcelableExtra(Intent.EXTRA_RESULT_RECEIVER);
            receiver.send(1, resultData); // resultCode should be 1
        }
    }
    
  2. Select Options request

    Samsung Internet for Android lets your app configure a few settings, such as what kind of web content data you want to receive, and what methods you would like to use when giving us your URL host white-list. Here are the options that you can select for each configuration:

    Select Options request
    Configuration Name Description Options Default Value
    “contents_info_type”
    • The type of data you want to receive for the web contents.
    • “url”
    • (“url”, meta”)
    • “meta”
    “domain_method”
    • The method you want to use when providing your URL host white-list. Either by sending Intents, or as a ContentProvider.
    • “intent”
    • “intent”
    • “cp”

    More configurations can be added if necessary. Please contact browser@samsung.com for further guidelines.

    @Override
    protected void onHandleIntent(Intent intent) {
            if(intent.equals(“com.sec.android.app.sbrowser.webcontentsprovider.ACTION_SELECT_OPTIONS”)) {
            Bundle resultData = new Bundle();
            resultData.putInt(“query_id”, intent.getIntExtra(“query_id”, -1));
            resultData.putString(“mode”, “default”);
            ResultReceiver receiver = intent.getParcelableExtra(Intent.EXTRA_REULST_RECEIVER);
            receiver.send(2, resultData); // resultCode for ACTION_SELECT_OPTIONS is 2
        }
    }
    
  3. Domain List request

    Samsung Internet for Android provides web contents information to you only for the white-listed hosts. If you select to use Intents for sending your white-list, Samsung Internet for Android will request the list with a ACTION_DOMAIN_LIST intent. On receiving this intent, you should send back the result data containing the white-list of URL hosts, with the result code 0.

    @Override
       protected void onHandleIntent(Intent intent) {
           if(intent.equals(“com.sec.android.app.sbrowser.webcontentsprovider.ACTION_DOMAIN_LIST”)) {
               Bundle resultData = new Bundle();
               resultData.putInt(“query_id”, intent.getIntExtra(“query_id”, -1));
               ArrayList<String> hostList = new ArrayList<>();
               hostList.add(“www.a.com”);
               hostList.add(“m.a.com”);
               hostList.add(“a.co.kr”);
               resultData.putStringArrayList(“domain”, hostList);
               ResultReceiver receiver = intent.getParcelableExtra(Intent.EXTRA_REULST_RECEIVER);
               receiver.send(0, resultData); // resultCode for ACTION_SELECT_OPTIONS is 0
           }
       }
    
Receiving Web Contents data

Samsung Internet provides web contents data based on the white-list of URL hosts provided by your app. You will get the following events when the user visits or leaves a web site that is in your white-list.

  1. CONTENT_CHANGED event

    Whenever a user visits a web page that is in your white-list, Samsung Internet for Android will send an intent with the event extra set as CONTENT_CHANGED. Your IntentService should handle this intent properly to recommend contents to users based on the data provided by us. Your recommendations should be based on the data received, and should not interfere with the users browsing experience.

    @Override
    protected void onHandleIntent(Intent intent) {
        if (intent.equals(“com.sec.android.app.sbrowser.webcontentsprovider.ACTION_SEND”)) {
            String eventName = intent.getStringExtra(“event”);
            if (eventName.equals(“CONTENT_CHANGED”)) {
                Bundle contents = intent.getBundleExtra(“contents”);
                String url = contents.getString(“url”);
                // CONTENT_CHANGED intent is sent as soon as the url is ready, so “meta” might be null
                // In this case, another intent with the same “url” and proper “meta” will be sent
                // when “meta” becomes ready.
                String meta = contents.getString(“meta”);
            }
        }
    }
    
  2. CONTENT_HIDDEN event

    Whenever the web content that you are showing recommendations over is hidden for some reason(user navigating to another page, user exiting Samsung Internet for Android, etc), your UI should also be hidden. Samsung Internet for Android will send you an CONTENT_HIDDEN event when this happens, and your extension app should handle it in your IntentService.

    @Override
    protected void onHandleIntent(Intent intent) {
        if(intent.equals(“com.sec.android.app.sbrowser.webcontentsprovider.ACTION_SEND”)) {
            String eventName = intent.getStringExtra(“event”);
            if (eventName.equals(“CONTENT_HIDDEN”)) {
                // Hide your UI
            }
        }
    }
    
Launching Extensions Settings

You can launch Samsung Internet for Android’s Extensions setting menu from your app with the following Intent.

Intent intent = new Intent();
intent.setAction("com.sec.android.app.sbrowser.webcontentsprovider.ACTION_SETTING");
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_NEW_DOCUMENT |
            Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
List<ResolveInfo> list = getPackageManager().queryIntentActivities(
        intent, PackageManager.MATCH_DEFAULT_ONLY);
if (list.size() > 0) {
    startActivity(intent);
}
Opening URLs in a new tab

Samsung Internet for Android lets you open URLs in a new tab, so users can visit the page you are recommending, close the new tab, and seamlessly resume browsing the contents they were looking at before. Call startActivity() with the following intent to open URLs in a new tab.

try {
Intent intent = new Intent();
    Bundle metaData = getPackageManager().getApplicationInfo(
            “com.sec.android.app.sbrowser”, PackageManager.GET_META_DATA)
                    .metaData;
    float interfaceVersion = metaData.getFloat(
            “com.sec.android.app.sbrowser.webcontentsprovider.INTERFACE_VERSION”,
            1.0f);
    if (interfaceVersion >= 1.4f) {
        intent.setAction(“com.samsung.intent.action.SBROWSER_VIEW_FOR_EXTERNAL_APP”);
    } else {
        intent.setAction(“android.intent.action.SBROWSER_VIEW_FOR_EXTERNAL_APP”);
    }
    intent.setData(Uri.parse(“<url_to_load_e.g.http://example.com >”));
    intent.setPackage(“com.sec.android.app.sbrowser”);
    if (list.size() > 0) {
        startActivity(intent);
    }
} catch (PackageManager.NameNotFoundException e){
}
Developer Mode

Samsung Internet for Android provides a development mode for web content provider, so you can test your app during the development phase. If you launch the settings menu in development mode, you will be able to add and test your web content provider extension app even if it is not validated.

Type "internet://webextensiontest" in the URL bar of Samsung Internet for Android. (It shows a page with the "this site can't be reached" message.) Visit “Settings” > “Web Extension Test” > ”Add Extension Package” from the menu, and add your package. You will see your app in Extensions menu.

Restrictions

Supported devices: Web content provider extension is supported on Samsung Galaxy devices with Samsung Internet for Android 4.2 and above.