Extension Development GuideSep 8, 2016

Samsung Internet for Android provides support for 3rd party extensions that let users customize their web browsing experience. We are constantly seeking for more services that can be integrated to further improve user experience.

Note

All 3rd party extension apps are validated and approved by Samsung. So that the plug-in apps installed from public app markets do not interfere with Samsung Internet for Android in any unauthorized manner.

Web Content Provider

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" />
    
  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.

Intent intent = new Intent();
intent.setAction("com.samsung.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”);
List<ResolveInfo> list = getPackageManager().queryIntentActivities(
intent, PackageManager.MATCH_DEFAULT_ONLY);
if (list.size() > 0) {
    startActivity(intent);
}
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.

Note

Development mode is only intended for web content provider extension app developers. You must not guide app users to enable development mode in order to use your app.

Restrictions

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

Content Blocker

Starting from 4.0, Samsung Internet for Android allows 3rd party apps to provide filters for Content Blocking. You can let users browse the web without unnecessary content cluttering their screens.

Block Content Off Block Content On

Overview

Samsung Internet for Android uses the filter data provided by your apps to tidy up web pages shown to users.

Block Content Block Content

In Samsung Internet for Android, Content Blocker feature is disabled by default. When users install Content Blocking apps -pre-registered to Samsung Internet for Android - from app stores, the Block Content menu will become visible. For Samsung Internet for Android 4.0, in our Settings – Advanced page, and for Samsung Internet for Android 4.2, in our Extensions page. This setting menu becomes visible only after at least one pre-registered Content Blocking app is installed.

Samsung Internet for Android scans for pre-registered Content Blocking apps, details for registering your app to Samsung Internet for Android is described in the Basic Guidelines section.

After the user enables a Content Blocker extension, Samsung Internet for Android will request the filter data to your app and start using that filter data when rendering web pages. Although several content blocking apps can be installed and registered to Samsung Internet for Android, only one app selected by the user will be used for content blocking.

Basic Guidelines

Filter Format

Samsung Internet works with filters following the widely known Adblock Plus filter (adblockplus.org/filters) format packaged into android apk packages.

App Registration

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

  1. The ContentProvider’s authority string should follow this format

    <provider>
    android:name="com.example.sampleApp.sampleContentProvider"
    android:authorities="< your_package_name >.contentBlocker.contentProvider"
    android:exported="true">
    </provider>
    
  2. Add the following uses-permission in your AndroidManifest.xml file.

    <uses-permission android:name="com.samsung.android.sbrowser.permission.CONTENTBLOCKER" />
    
  3. Include the version info for our Content Blocker interface in your AndroidManifest.xml file.

    <meta-data android:name="com.samsung.android.sbrowser.contentBlocker.interfaceVersion" android:value="API_1.0" />
    
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 used by Samsung Internet for Android for Content Blocking.

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

Data Encryption

Samsung Internet for Android provides an optional filter data encryption SW on request. The key value generated by the encryption SW should be included in the Bundle returned by the call() method in ContentProvider.
If not using data encryption, you can return null in call().
Contact browser@samsung.com to request the encryption SW and detailed guides.

@Override
public Bundle call(String method, String arg, Bundle extras) {
if((method.equals(“getKeyInfo”))) {
Bundle returnData = new Bundle();
returnData.putString(“keyInfo”, “key_value_generated_by_encryption_sw”);

return returnData;
}
return null;

Samsung Internet for Android requests the filter data in read-only mode, but to be sure, it is recommended that you explicitly open your filter file in read-only mode.

@Override
public ParcelFileDescriptor openFile(Uri uri, String mode)
throws FileNotFoundException {
ParcelFileDescriptor parcel =
ParcelFileDescriptor.open(file,
ParcelFileDescriptor.MODE_READ_ONLY);
return parcel;
}
Updating Filter Data

Whenever your app is updated through public app markets, Samsung Internet for Android will request the up-to-date filter data from your app. Another option is for you to send a broadcast message with the intent action and data set following this format.

Intent intent = new Intent();
intent.setAction("com.samsung.android.sbrowser.contentBlocker.ACTION_UPDATE");
intent.setData(Uri.parse("package:<your_package_name>"));
sendBroadcast(intent);</your_package_name>
Launching Content Blocking Settings

You can launch the Content Blocking setting menu for Samsung Internet for Android from your app with startActivity(Intent).

Intent intent = new Intent();
intent.setAction("com.samsung.android.sbrowser.contentBlocker.ACTION_SETTING");
List<ResolveInfo> list = getPackageManager().queryIntentActivities(
intent, PackageManager.MATCH_DEFAULT_ONLY);
If (list.size() > 0) {
startActivity(intent);
}
Development Mode

Samsung Internet for Android provides a development mode for Content Blocker, so you can test your app before carrying out the validation process.

Type "about:contentblock" in the URL bar of Samsung Internet for Android, and you will enter Content Blocker development mode. If you launch the setting menu in development mode, you will be able to select and test your Content Blocking app even if it is not validated.

Note

Development mode is only intended for Content Blocker app developers. You must not guide app users to enable development mode in order to use your app.

Restrictions

Supported devices: Content blocking feature is supported on Samsung Galaxy devices with Samsung Internet for Android 4.0 and above.

Developer Feedback

For more details or inquiries, please contact browser@samsung.com.