Register now for Android Dev Summit 2019!

CustomTabsService

abstract class CustomTabsService : Service
kotlin.Any
   ↳ 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

Constants

static String

The Intent action that a CustomTabsService must respond to.

static String

For CustomTabsService#mayLaunchUrl 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.

static Int

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

static Int

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

static Int

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

static Int

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

static Int

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

static Int

Indicates that the postMessage request was accepted.

Public constructors

Abstract service class for implementing Custom Tabs related functionality.

Public methods

open IBinder!
onBind(intent: Intent!)

Protected methods

open Boolean

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

abstract Bundle!
extraCommand(commandName: String!, args: Bundle!)

Unsupported commands that may be provided by the implementation.

abstract Boolean
mayLaunchUrl(sessionToken: CustomTabsSessionToken!, url: Uri!, extras: Bundle!, otherLikelyBundles: MutableList<Bundle!>!)

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

abstract Boolean

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

abstract Int
postMessage(sessionToken: CustomTabsSessionToken!, message: String!, extras: Bundle!)

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

abstract Boolean
requestPostMessageChannel(sessionToken: CustomTabsSessionToken!, postMessageOrigin: Uri!)

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

abstract Boolean
updateVisuals(sessionToken: CustomTabsSessionToken!, bundle: Bundle!)

Updates the visuals of custom tabs for the given session.

abstract Boolean
validateRelationship(sessionToken: CustomTabsSessionToken!, relation: Int, origin: Uri!, extras: Bundle!)

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

abstract Boolean
warmup(flags: Long)

Warms up the browser process asynchronously.

Constants

ACTION_CUSTOM_TABS_CONNECTION

static val ACTION_CUSTOM_TABS_CONNECTION: String

The Intent action that a CustomTabsService must respond to.

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

KEY_URL

static val KEY_URL: String

For CustomTabsService#mayLaunchUrl 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.

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

RELATION_HANDLE_ALL_URLS

static val RELATION_HANDLE_ALL_URLS: Int

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

Value: 2

RELATION_USE_AS_ORIGIN

static val RELATION_USE_AS_ORIGIN: Int

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.

Value: 1

RESULT_FAILURE_DISALLOWED

static val RESULT_FAILURE_DISALLOWED: Int

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

Value: -1

RESULT_FAILURE_MESSAGING_ERROR

static val RESULT_FAILURE_MESSAGING_ERROR: Int

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

Value: -3

RESULT_FAILURE_REMOTE_ERROR

static val RESULT_FAILURE_REMOTE_ERROR: Int

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

Value: -2

RESULT_SUCCESS

static val RESULT_SUCCESS: Int

Indicates that the postMessage request was accepted.

Value: 0

Public constructors

<init>

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.

Public methods

onBind

open fun onBind(intent: Intent!): IBinder!

Protected methods

cleanUpSession

protected open fun cleanUpSession(sessionToken: CustomTabsSessionToken!): Boolean

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

Parameters
sessionToken CustomTabsSessionToken!: The session token for which the DeathRecipient call has been received.
Return
Boolean: Whether the clean up was successful. Multiple calls with two tokens holdings the same binder will return false.

extraCommand

protected abstract fun extraCommand(commandName: String!, args: Bundle!): Bundle!

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 String!: Arguments for the command
Return
Bundle!: The result Bundle, or null.

mayLaunchUrl

protected abstract fun mayLaunchUrl(sessionToken: CustomTabsSessionToken!, url: Uri!, extras: Bundle!, otherLikelyBundles: MutableList<Bundle!>!): Boolean

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

The method CustomTabsService#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 CustomTabsSessionToken!: Most likely URL.
extras CustomTabsSessionToken!: Reserved for future use.
otherLikelyBundles CustomTabsSessionToken!: Other likely destinations, sorted in decreasing likelihood order. Each Bundle has to provide a url.
Return
Boolean: Whether the call was successful.

newSession

protected abstract fun newSession(sessionToken: CustomTabsSessionToken!): Boolean

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().
Return
Boolean: Whether a new session was successfully created.

postMessage

protected abstract fun postMessage(sessionToken: CustomTabsSessionToken!, message: String!, extras: Bundle!): Int

Sends a postMessage request using the origin communicated via CustomTabsService#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 CustomTabsSessionToken!: The message that is being sent.
extras CustomTabsSessionToken!: Reserved for future use.
Return
Int: An integer constant about the postMessage request result. Will return CustomTabsService#RESULT_SUCCESS if successful.

requestPostMessageChannel

protected abstract fun requestPostMessageChannel(sessionToken: CustomTabsSessionToken!, postMessageOrigin: Uri!): Boolean

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 CustomTabsSessionToken!: A origin that the client is requesting to be identified as during the postMessage communication.
Return
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 fun updateVisuals(sessionToken: CustomTabsSessionToken!, bundle: Bundle!): Boolean

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 CustomTabsSessionToken!: The action button configuration bundle. This bundle should be constructed with the same structure in CustomTabsIntent.Builder.
Return
Boolean: Whether the operation was successful.

validateRelationship

protected abstract fun validateRelationship(sessionToken: CustomTabsSessionToken!, relation: Int, origin: Uri!, extras: Bundle!): Boolean

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 CustomTabsSessionToken!: Relation to check, must be one of the CustomTabsService#RELATION_* constants.
origin CustomTabsSessionToken!: Origin for the relation query.
extras CustomTabsSessionToken!: Reserved for future use.
Return
Boolean: true if the request has been submitted successfully.

warmup

protected abstract fun warmup(flags: Long): Boolean

Warms up the browser process asynchronously.

Parameters
flags Long: Reserved for future use.
Return
Boolean: Whether warmup was/had been completed successfully. Multiple successful calls will return true.