It's happening now, watch the livestream.

CustomTabsService

public abstract class CustomTabsService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ androidx.browser.customtabs.CustomTabsService


Abstract service class for implementing Custom Tabs related functionality. The service should be responding to the action ACTION_CUSTOM_TABS_CONNECTION. This class should be used by implementers that want to provide Custom Tabs functionality, not by clients that want to launch Custom Tabs.

Summary

Nested classes

@interface CustomTabsService.Relation

 

@interface CustomTabsService.Result

 

Constants

String ACTION_CUSTOM_TABS_CONNECTION

The Intent action that a CustomTabsService must respond to.

String CATEGORY_COLOR_SCHEME_CUSTOMIZATION

An Intent filter category to signify that the Custom Tabs provider supports selecting and customizing color schemes via CustomTabsIntent.Builder.setColorScheme(int) and CustomTabsIntent.Builder.setColorSchemeParams(int, CustomTabColorSchemeParams).

String CATEGORY_NAVBAR_COLOR_CUSTOMIZATION

An Intent filter category to signify that the Custom Tabs provider supports customizing the color of the navigation bar (CustomTabsIntent.Builder.setNavigationBarColor(int)).

String CATEGORY_TRUSTED_WEB_ACTIVITY_IMMERSIVE_MODE

An Intent filter category to signify that the Trusted Web Activity provider supports immersive mode.

String CATEGORY_WEB_SHARE_TARGET_V2

An Intent filter category to signify that the Trusted Web Activity provider supports sending shared data according to the Web Share Target v2 protocol defined in https://wicg.github.io/web-share-target/level-2/.

int FILE_PURPOSE_TRUSTED_WEB_ACTIVITY_SPLASH_IMAGE

A constant to be used with CustomTabsSession.receiveFile(Uri, int, Bundle) indicating that the file is a splash image to be shown on top of a Trusted Web Activity while the web contents are loading.

String KEY_URL

For mayLaunchUrl(CustomTabsSessionToken, Uri, Bundle, List) calls that wants to specify more than one url, this key can be used with Bundle.putParcelable(String, android.os.Parcelable) to insert a new url to each bundle inside list of bundles.

int RELATION_HANDLE_ALL_URLS

Used for CustomTabsSession.validateRelationship(int, Uri, Bundle).

int RELATION_USE_AS_ORIGIN

Used for CustomTabsSession.validateRelationship(int, Uri, Bundle).

int RESULT_FAILURE_DISALLOWED

Indicates that the postMessage request was not allowed due to a bad argument or requesting at a disallowed time like when in background.

int RESULT_FAILURE_MESSAGING_ERROR

Indicates that the postMessage request has failed due to an internal error on the browser message channel.

int RESULT_FAILURE_REMOTE_ERROR

Indicates that the postMessage request has failed due to a RemoteException .

int RESULT_SUCCESS

Indicates that the postMessage request was accepted.

String TRUSTED_WEB_ACTIVITY_CATEGORY

An Intent filter category to signify that the Custom Tabs provider supports Trusted Web Activities (see TrustedWebUtils for more details).

Inherited constants

Public constructors

CustomTabsService()

Public methods

IBinder onBind(Intent intent)

Protected methods

boolean cleanUpSession(CustomTabsSessionToken sessionToken)

Called when the client side IBinder for this CustomTabsSessionToken is dead.

abstract Bundle extraCommand(String commandName, Bundle args)

Unsupported commands that may be provided by the implementation.

abstract boolean mayLaunchUrl(CustomTabsSessionToken sessionToken, Uri url, Bundle extras, List<Bundle> otherLikelyBundles)

Tells the browser of a likely future navigation to a URL.

abstract boolean newSession(CustomTabsSessionToken sessionToken)

Creates a new session through an ICustomTabsService with the optional callback.

abstract int postMessage(CustomTabsSessionToken sessionToken, String message, Bundle extras)

Sends a postMessage request using the origin communicated via requestPostMessageChannel(CustomTabsSessionToken, Uri).

abstract boolean receiveFile(CustomTabsSessionToken sessionToken, Uri uri, int purpose, Bundle extras)

Receive a file from client by given Uri, e.g.

abstract boolean requestPostMessageChannel(CustomTabsSessionToken sessionToken, Uri postMessageOrigin)

Sends a request to create a two way postMessage channel between the client and the browser linked with the given CustomTabsSession.

abstract boolean updateVisuals(CustomTabsSessionToken sessionToken, Bundle bundle)

Updates the visuals of custom tabs for the given session.

abstract boolean validateRelationship(CustomTabsSessionToken sessionToken, int relation, Uri origin, Bundle extras)

Request to validate a relationship between the application and an origin.

abstract boolean warmup(long flags)

Warms up the browser process asynchronously.

Inherited methods

Constants

ACTION_CUSTOM_TABS_CONNECTION

public static final String ACTION_CUSTOM_TABS_CONNECTION

The Intent action that a CustomTabsService must respond to.

Constant Value: "android.support.customtabs.action.CustomTabsService"

CATEGORY_COLOR_SCHEME_CUSTOMIZATION

public static final String CATEGORY_COLOR_SCHEME_CUSTOMIZATION

An Intent filter category to signify that the Custom Tabs provider supports selecting and customizing color schemes via CustomTabsIntent.Builder.setColorScheme(int) and CustomTabsIntent.Builder.setColorSchemeParams(int, CustomTabColorSchemeParams).

Constant Value: "androidx.browser.customtabs.category.ColorSchemeCustomization"

CATEGORY_NAVBAR_COLOR_CUSTOMIZATION

public static final String CATEGORY_NAVBAR_COLOR_CUSTOMIZATION

An Intent filter category to signify that the Custom Tabs provider supports customizing the color of the navigation bar (CustomTabsIntent.Builder.setNavigationBarColor(int)).

Constant Value: "androidx.browser.customtabs.category.NavBarColorCustomization"

CATEGORY_TRUSTED_WEB_ACTIVITY_IMMERSIVE_MODE

public static final String CATEGORY_TRUSTED_WEB_ACTIVITY_IMMERSIVE_MODE

An Intent filter category to signify that the Trusted Web Activity provider supports immersive mode.

Constant Value: "androidx.browser.trusted.category.ImmersiveMode"

CATEGORY_WEB_SHARE_TARGET_V2

public static final String CATEGORY_WEB_SHARE_TARGET_V2

An Intent filter category to signify that the Trusted Web Activity provider supports sending shared data according to the Web Share Target v2 protocol defined in https://wicg.github.io/web-share-target/level-2/.

Constant Value: "androidx.browser.trusted.category.WebShareTargetV2"

FILE_PURPOSE_TRUSTED_WEB_ACTIVITY_SPLASH_IMAGE

public static final int FILE_PURPOSE_TRUSTED_WEB_ACTIVITY_SPLASH_IMAGE

A constant to be used with CustomTabsSession.receiveFile(Uri, int, Bundle) indicating that the file is a splash image to be shown on top of a Trusted Web Activity while the web contents are loading.

Constant Value: 1 (0x00000001)

KEY_URL

public static final String KEY_URL

For mayLaunchUrl(CustomTabsSessionToken, Uri, Bundle, List) calls that wants to specify more than one url, this key can be used with Bundle.putParcelable(String, android.os.Parcelable) to insert a new url to each bundle inside list of bundles.

Constant Value: "android.support.customtabs.otherurls.URL"

RELATION_HANDLE_ALL_URLS

public static final int RELATION_HANDLE_ALL_URLS

Used for CustomTabsSession.validateRelationship(int, Uri, Bundle). Requests the ability to handle all URLs from a given origin.

Constant Value: 2 (0x00000002)

RELATION_USE_AS_ORIGIN

public static final int RELATION_USE_AS_ORIGIN

Used for CustomTabsSession.validateRelationship(int, Uri, Bundle). For App -> Web transitions, requests the app to use the declared origin to be used as origin for the client app in the web APIs context.

Constant Value: 1 (0x00000001)

RESULT_FAILURE_DISALLOWED

public static final int RESULT_FAILURE_DISALLOWED

Indicates that the postMessage request was not allowed due to a bad argument or requesting at a disallowed time like when in background.

Constant Value: -1 (0xffffffff)

RESULT_FAILURE_MESSAGING_ERROR

public static final int RESULT_FAILURE_MESSAGING_ERROR

Indicates that the postMessage request has failed due to an internal error on the browser message channel.

Constant Value: -3 (0xfffffffd)

RESULT_FAILURE_REMOTE_ERROR

public static final int RESULT_FAILURE_REMOTE_ERROR

Indicates that the postMessage request has failed due to a RemoteException .

Constant Value: -2 (0xfffffffe)

RESULT_SUCCESS

public static final int RESULT_SUCCESS

Indicates that the postMessage request was accepted.

Constant Value: 0 (0x00000000)

TRUSTED_WEB_ACTIVITY_CATEGORY

public static final String TRUSTED_WEB_ACTIVITY_CATEGORY

An Intent filter category to signify that the Custom Tabs provider supports Trusted Web Activities (see TrustedWebUtils for more details).

Constant Value: "androidx.browser.trusted.category.TrustedWebActivities"

Public constructors

CustomTabsService

public CustomTabsService ()

Public methods

onBind

public IBinder onBind (Intent intent)

Parameters
intent Intent

Returns
IBinder

Protected methods

cleanUpSession

protected boolean cleanUpSession (CustomTabsSessionToken sessionToken)

Called when the client side IBinder for this CustomTabsSessionToken is dead. Can also be used to clean up IBinder.DeathRecipient instances allocated for the given token.

Parameters
sessionToken CustomTabsSessionToken: The session token for which the IBinder.DeathRecipient call has been received.

Returns
boolean Whether the clean up was successful. Multiple calls with two tokens holdings the same binder will return false.

extraCommand

protected abstract Bundle extraCommand (String commandName, 
                Bundle args)

Unsupported commands that may be provided by the implementation.

Note:Clients should never rely on this method to have a defined behavior, as it is entirely implementation-defined and not supported.

This call can be used by implementations to add extra commands, for testing or experimental purposes.

Parameters
commandName String: Name of the extra command to execute.

args Bundle: Arguments for the command

Returns
Bundle The result Bundle, or null.

mayLaunchUrl

protected abstract boolean mayLaunchUrl (CustomTabsSessionToken sessionToken, 
                Uri url, 
                Bundle extras, 
                List<Bundle> otherLikelyBundles)

Tells the browser of a likely future navigation to a URL.

The method warmup(long) has to be called beforehand. The most likely URL has to be specified explicitly. Optionally, a list of other likely URLs can be provided. They are treated as less likely than the first one, and have to be sorted in decreasing priority order. These additional URLs may be ignored. All previous calls to this method will be deprioritized.

Parameters
sessionToken CustomTabsSessionToken: The unique identifier for the session. Can not be null.

url Uri: Most likely URL.

extras Bundle: Reserved for future use.

otherLikelyBundles List: Other likely destinations, sorted in decreasing likelihood order. Each Bundle has to provide a url.

Returns
boolean Whether the call was successful.

newSession

protected abstract boolean newSession (CustomTabsSessionToken sessionToken)

Creates a new session through an ICustomTabsService with the optional callback. This session can be used to associate any related communication through the service with an intent and then later with a Custom Tab. The client can then send later service calls or intents to through same session-intent-Custom Tab association.

Parameters
sessionToken CustomTabsSessionToken: Session token to be used as a unique identifier. This also has access to the CustomTabsCallback passed from the client side through CustomTabsSessionToken.getCallback().

Returns
boolean Whether a new session was successfully created.

postMessage

protected abstract int postMessage (CustomTabsSessionToken sessionToken, 
                String message, 
                Bundle extras)

Sends a postMessage request using the origin communicated via requestPostMessageChannel(CustomTabsSessionToken, Uri). Fails when called before PostMessageServiceConnection.notifyMessageChannelReady(Bundle) is received on the client side.

Parameters
sessionToken CustomTabsSessionToken: The unique identifier for the session. Can not be null.

message String: The message that is being sent.

extras Bundle: Reserved for future use.

Returns
int An integer constant about the postMessage request result. Will return RESULT_SUCCESS if successful.

receiveFile

protected abstract boolean receiveFile (CustomTabsSessionToken sessionToken, 
                Uri uri, 
                int purpose, 
                Bundle extras)

Receive a file from client by given Uri, e.g. in order to display a large bitmap in a Custom Tab. Prior to calling this method, the client grants a read permission to the target Custom Tabs provider via Context.grantUriPermission(String, Uri, int). The file is read and processed (where applicable) synchronously.

Parameters
sessionToken CustomTabsSessionToken: The unique identifier for the session.

uri Uri: Uri of the file.

purpose int: Purpose of transferring this file, one of the constants enumerated in CustomTabsService#FilePurpose.

extras Bundle: Reserved for future use.

Returns
boolean true if the file was received successfully.

requestPostMessageChannel

protected abstract boolean requestPostMessageChannel (CustomTabsSessionToken sessionToken, 
                Uri postMessageOrigin)

Sends a request to create a two way postMessage channel between the client and the browser linked with the given CustomTabsSession.

Parameters
sessionToken CustomTabsSessionToken: The unique identifier for the session. Can not be null.

postMessageOrigin Uri: A origin that the client is requesting to be identified as during the postMessage communication.

Returns
boolean Whether the implementation accepted the request. Note that returning true here doesn't mean an origin has already been assigned as the validation is asynchronous.

updateVisuals

protected abstract boolean updateVisuals (CustomTabsSessionToken sessionToken, 
                Bundle bundle)

Updates the visuals of custom tabs for the given session. Will only succeed if the given session matches the currently active one.

Parameters
sessionToken CustomTabsSessionToken: The currently active session that the custom tab belongs to.

bundle Bundle: The action button configuration bundle. This bundle should be constructed with the same structure in CustomTabsIntent.Builder.

Returns
boolean Whether the operation was successful.

validateRelationship

protected abstract boolean validateRelationship (CustomTabsSessionToken sessionToken, 
                int relation, 
                Uri origin, 
                Bundle extras)

Request to validate a relationship between the application and an origin. If this method returns true, the validation result will be provided through CustomTabsCallback.onRelationshipValidationResult(int, Uri, boolean, Bundle). Otherwise the request didn't succeed. The client must call CustomTabsClient.warmup(long) before this.

Parameters
sessionToken CustomTabsSessionToken: The unique identifier for the session. Can not be null.

relation int: Relation to check, must be one of the CustomTabsService#RELATION_* constants.

origin Uri: Origin for the relation query.

extras Bundle: Reserved for future use.

Returns
boolean true if the request has been submitted successfully.

warmup

protected abstract boolean warmup (long flags)

Warms up the browser process asynchronously.

Parameters
flags long: Reserved for future use.

Returns
boolean Whether warmup was/had been completed successfully. Multiple successful calls will return true.