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 |
An Intent filter category to signify that the Custom Tabs provider supports selecting and customizing color schemes via |
static String |
An Intent filter category to signify that the Custom Tabs provider supports customizing the color of the navigation bar ( |
static String |
An Intent filter category to signify that the Trusted Web Activity provider supports immersive mode. |
static String |
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. |
static Int |
A constant to be used with |
static String |
For |
static Int |
Used for |
static Int |
Used for |
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 |
static Int |
Indicates that the postMessage request was accepted. |
static String |
An Intent filter category to signify that the Custom Tabs provider supports Trusted Web Activities (see |
Public constructors |
|
---|---|
<init>() Abstract service class for implementing Custom Tabs related functionality. |
Public methods |
|
---|---|
open IBinder |
Protected methods |
|
---|---|
open Boolean |
cleanUpSession(@NonNull sessionToken: CustomTabsSessionToken) Called when the client side |
abstract Bundle? |
extraCommand(@NonNull commandName: String, @Nullable args: Bundle?) Unsupported commands that may be provided by the implementation. |
abstract Boolean |
mayLaunchUrl(@NonNull sessionToken: CustomTabsSessionToken, @NonNull url: Uri, @Nullable extras: Bundle?, @Nullable otherLikelyBundles: MutableList<Bundle!>?) Tells the browser of a likely future navigation to a URL. |
abstract Boolean |
newSession(@NonNull sessionToken: CustomTabsSessionToken) Creates a new session through an ICustomTabsService with the optional callback. |
abstract Int |
postMessage(@NonNull sessionToken: CustomTabsSessionToken, @NonNull message: String, @Nullable extras: Bundle?) Sends a postMessage request using the origin communicated via |
abstract Boolean |
receiveFile(@NonNull sessionToken: CustomTabsSessionToken, @NonNull uri: Uri, purpose: Int, @Nullable extras: Bundle?) Receive a file from client by given Uri, e. |
abstract Boolean |
requestPostMessageChannel(@NonNull sessionToken: CustomTabsSessionToken, @NonNull postMessageOrigin: Uri) Sends a request to create a two way postMessage channel between the client and the browser linked with the given |
abstract Boolean |
updateVisuals(@NonNull sessionToken: CustomTabsSessionToken, @Nullable bundle: Bundle?) Updates the visuals of custom tabs for the given session. |
abstract Boolean |
validateRelationship(@NonNull sessionToken: CustomTabsSessionToken, relation: Int, @NonNull origin: Uri, @Nullable extras: Bundle?) Request to validate a relationship between the application and an origin. |
abstract Boolean |
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"
CATEGORY_COLOR_SCHEME_CUSTOMIZATION
static val CATEGORY_COLOR_SCHEME_CUSTOMIZATION: String
An Intent filter category to signify that the Custom Tabs provider supports selecting and customizing color schemes via CustomTabsIntent.Builder#setColorScheme
and CustomTabsIntent.Builder#setColorSchemeParams
.
Value: "androidx.browser.customtabs.category.ColorSchemeCustomization"
CATEGORY_NAVBAR_COLOR_CUSTOMIZATION
static val CATEGORY_NAVBAR_COLOR_CUSTOMIZATION: String
An Intent filter category to signify that the Custom Tabs provider supports customizing the color of the navigation bar (CustomTabsIntent.Builder#setNavigationBarColor
).
Value: "androidx.browser.customtabs.category.NavBarColorCustomization"
CATEGORY_TRUSTED_WEB_ACTIVITY_IMMERSIVE_MODE
static val CATEGORY_TRUSTED_WEB_ACTIVITY_IMMERSIVE_MODE: String
An Intent filter category to signify that the Trusted Web Activity provider supports immersive mode.
Value: "androidx.browser.trusted.category.ImmersiveMode"
CATEGORY_WEB_SHARE_TARGET_V2
static val CATEGORY_WEB_SHARE_TARGET_V2: String
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/.
Value: "androidx.browser.trusted.category.WebShareTargetV2"
FILE_PURPOSE_TRUSTED_WEB_ACTIVITY_SPLASH_IMAGE
static val FILE_PURPOSE_TRUSTED_WEB_ACTIVITY_SPLASH_IMAGE: Int
A constant to be used with CustomTabsSession#receiveFile
indicating that the file is a splash image to be shown on top of a Trusted Web Activity while the web contents are loading.
Value: 1
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
TRUSTED_WEB_ACTIVITY_CATEGORY
static val TRUSTED_WEB_ACTIVITY_CATEGORY: String
An Intent filter category to signify that the Custom Tabs provider supports Trusted Web Activities (see TrustedWebUtils
for more details).
Value: "androidx.browser.trusted.category.TrustedWebActivities"
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
Protected methods
cleanUpSession
protected open fun cleanUpSession(@NonNull 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
@Nullable protected abstract fun extraCommand(@NonNull commandName: String, @Nullable 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(@NonNull sessionToken: CustomTabsSessionToken, @NonNull url: Uri, @Nullable extras: Bundle?, @Nullable 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(@NonNull 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(@NonNull sessionToken: CustomTabsSessionToken, @NonNull message: String, @Nullable 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. |
receiveFile
protected abstract fun receiveFile(@NonNull sessionToken: CustomTabsSessionToken, @NonNull uri: Uri, purpose: Int, @Nullable extras: Bundle?): Boolean
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 android.content.Context#grantUriPermission
. The file is read and processed (where applicable) synchronously.
Parameters | |
---|---|
sessionToken |
CustomTabsSessionToken: The unique identifier for the session. |
uri |
CustomTabsSessionToken: Uri of the file. |
purpose |
CustomTabsSessionToken: Purpose of transferring this file, one of the constants enumerated in CustomTabsService#FilePurpose . |
extras |
CustomTabsSessionToken: Reserved for future use. |
Return | |
---|---|
Boolean: true if the file was received successfully. |
requestPostMessageChannel
protected abstract fun requestPostMessageChannel(@NonNull sessionToken: CustomTabsSessionToken, @NonNull 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(@NonNull sessionToken: CustomTabsSessionToken, @Nullable 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(@NonNull sessionToken: CustomTabsSessionToken, relation: Int, @NonNull origin: Uri, @Nullable 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. |