CustomTabsSession
class CustomTabsSession
A class to be used for Custom Tabs related communication. Clients that want to launch Custom Tabs can use this class exclusively to handle all related communication.
Summary
Nested types |
|---|
|
A class to be used instead of |
Public functions |
|
|---|---|
java-static CustomTabsSession |
@VisibleForTestingProvides browsers a way to generate a mock |
Boolean |
isEngagementSignalsApiAvailable(extras: Bundle)Returns whether the Engagement Signals API is available. |
Boolean |
Tells the browser of a likely future navigation to a URL. |
Int |
@CustomTabsService.ResultSends a postMessage request using the origin communicated via |
Unit |
@ExperimentalPrefetchRequest the browser to start navigational prefetch to the page that will be used for future navigations. |
Unit |
@ExperimentalPrefetchRequest the browser to start navigational prefetch to the pages that will be used for future navigations. |
Boolean |
receiveFile(uri: Uri, purpose: Int, extras: Bundle?)Passes an URI of a file, e.g. in order to pass a large bitmap to be displayed in the Custom Tabs provider. |
Boolean |
requestPostMessageChannel(postMessageOrigin: Uri)Sends a request to create a two way postMessage channel between the client and the browser. |
Boolean |
requestPostMessageChannel(Sends a request to create a two way postMessage channel between the client and the browser with specifying the target origin to communicate with. |
Boolean |
setActionButton(icon: Bitmap, description: String)This sets the action button on the toolbar with ID |
Boolean |
@RequiresFeature(name = CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable")Sets an |
Boolean |
@RequiresFeature(name = CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable")Sets an |
Boolean |
setSecondaryToolbarSwipeUpGesture(pendingIntent: PendingIntent?)Sets a |
Boolean |
setSecondaryToolbarViews(Updates the |
Boolean |
This function is deprecated. Use CustomTabsSession#setSecondaryToolbarViews(RemoteViews, int[], PendingIntent) |
Boolean |
validateRelationship(Requests to validate a relationship between the application and an origin. |
Public functions
createMockSessionForTesting
@VisibleForTesting
java-static fun createMockSessionForTesting(componentName: ComponentName): CustomTabsSession
Provides browsers a way to generate a mock CustomTabsSession for testing purposes.
| Parameters | |
|---|---|
componentName: ComponentName |
The component the session should be created for. |
| Returns | |
|---|---|
CustomTabsSession |
A mock session with no functionality. |
isEngagementSignalsApiAvailable
fun isEngagementSignalsApiAvailable(extras: Bundle): Boolean
Returns whether the Engagement Signals API is available. The availability of the Engagement Signals API may change at runtime. If an EngagementSignalsCallback has been set, an onSessionEnded signal will be sent if the API becomes unavailable later.
| Parameters | |
|---|---|
extras: Bundle |
Reserved for future use. |
| Returns | |
|---|---|
Boolean |
Whether the Engagement Signals API is available. A false value means setEngagementSignalsCallback will return false and not set the callback. |
| Throws | |
|---|---|
android.os.RemoteException |
If the Service dies while responding to the request. |
java.lang.UnsupportedOperationException |
If this method isn't supported by the Custom Tabs implementation. |
mayLaunchUrl
fun mayLaunchUrl(
url: Uri?,
extras: Bundle?,
otherLikelyBundles: (Mutable)List<Bundle!>?
): Boolean
Tells the browser of a likely future navigation to a URL. The most likely URL has to be specified first. 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 | |
|---|---|
url: Uri? |
Most likely URL, may be |
extras: Bundle? |
Reserved for future use. |
otherLikelyBundles: (Mutable)List<Bundle!>? |
Other likely destinations, sorted in decreasing likelihood order. Inside each Bundle, the client should provide a |
| Returns | |
|---|---|
Boolean |
true for success. |
postMessage
@CustomTabsService.Result
fun postMessage(message: String, extras: Bundle?): Int
Sends a postMessage request using the origin communicated via requestPostMessageChannel. Fails when called before notifyMessageChannelReady is received on the client side.
| Returns | |
|---|---|
Int |
An integer constant about the postMessage request result. Will return |
prefetch
@ExperimentalPrefetch
fun prefetch(url: Uri, options: PrefetchOptions): Unit
Request the browser to start navigational prefetch to the page that will be used for future navigations.
| Parameters | |
|---|---|
url: Uri |
The url to be prefetched for upcoming navigations. |
options: PrefetchOptions |
The option used for prefetch request. Please see |
prefetch
@ExperimentalPrefetch
fun prefetch(urls: (Mutable)List<Uri!>, options: PrefetchOptions): Unit
Request the browser to start navigational prefetch to the pages that will be used for future navigations.
| Parameters | |
|---|---|
urls: (Mutable)List<Uri!> |
The urls to be prefetched for upcoming navigations. |
options: PrefetchOptions |
The option used for prefetch request. Please see |
receiveFile
fun receiveFile(uri: Uri, purpose: Int, extras: Bundle?): Boolean
Passes an URI of a file, e.g. in order to pass a large bitmap to be displayed in the Custom Tabs provider. Prior to calling this method, the client needs to grant a read permission to the target Custom Tabs provider via grantUriPermission. The file is read and processed (where applicable) synchronously, therefore it's recommended to call this method on a background thread.
| Parameters | |
|---|---|
uri: Uri |
|
purpose: Int |
Purpose of transferring this file, one of the constants enumerated in |
extras: Bundle? |
Reserved for future use. |
| Returns | |
|---|---|
Boolean |
|
requestPostMessageChannel
fun requestPostMessageChannel(postMessageOrigin: Uri): Boolean
Sends a request to create a two way postMessage channel between the client and the browser.
| Parameters | |
|---|---|
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. |
requestPostMessageChannel
fun requestPostMessageChannel(
postMessageOrigin: Uri,
postMessageTargetOrigin: Uri?,
extras: Bundle
): Boolean
Sends a request to create a two way postMessage channel between the client and the browser with specifying the target origin to communicate with.
| Parameters | |
|---|---|
postMessageOrigin: Uri |
A origin that the client is requesting to be identified as during the postMessage communication. |
postMessageTargetOrigin: Uri? |
The target Origin to establish the postMessage communication with. |
extras: Bundle |
Reserved for future use. |
| 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. |
setActionButton
fun setActionButton(icon: Bitmap, description: String): Boolean
This sets the action button on the toolbar with ID TOOLBAR_ACTION_BUTTON_ID.
| Parameters | |
|---|---|
icon: Bitmap |
The new icon of the action button. |
description: String |
Content description of the action button. |
| See also | |
|---|---|
setToolbarItem |
setEngagementSignalsCallback
@RequiresFeature(name = CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable")
fun setEngagementSignalsCallback(
callback: EngagementSignalsCallback,
extras: Bundle
): Boolean
Sets an EngagementSignalsCallback to receive callbacks for events related to the user's engagement with webpage within the tab. Note that the callback will be executed on the main thread using getMainLooper. To specify the execution thread, use setEngagementSignalsCallback.
| Parameters | |
|---|---|
callback: EngagementSignalsCallback |
The |
extras: Bundle |
Reserved for future use. |
| Returns | |
|---|---|
Boolean |
Whether the callback connection is allowed. If false, no callbacks will be called for this session. |
| Throws | |
|---|---|
android.os.RemoteException |
If the Service dies while responding to the request. |
java.lang.UnsupportedOperationException |
If this method isn't supported by the Custom Tabs implementation. |
setEngagementSignalsCallback
@RequiresFeature(name = CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable")
fun setEngagementSignalsCallback(
executor: Executor,
callback: EngagementSignalsCallback,
extras: Bundle
): Boolean
Sets an EngagementSignalsCallback to receive callbacks for events related to the user's engagement with webpage within the tab.
| Parameters | |
|---|---|
executor: Executor |
The |
callback: EngagementSignalsCallback |
The |
extras: Bundle |
Reserved for future use. |
| Returns | |
|---|---|
Boolean |
Whether the callback connection is allowed. If false, no callbacks will be called for this session. |
| Throws | |
|---|---|
android.os.RemoteException |
If the Service dies while responding to the request. |
java.lang.UnsupportedOperationException |
If this method isn't supported by the Custom Tabs implementation. |
setSecondaryToolbarSwipeUpGesture
fun setSecondaryToolbarSwipeUpGesture(pendingIntent: PendingIntent?): Boolean
Sets a PendingIntent object to be sent when the user swipes up from the secondary (bottom) toolbar.
| Parameters | |
|---|---|
pendingIntent: PendingIntent? |
|
| Returns | |
|---|---|
Boolean |
Whether the update succeeded. |
setSecondaryToolbarViews
fun setSecondaryToolbarViews(
remoteViews: RemoteViews?,
clickableIDs: IntArray?,
pendingIntent: PendingIntent?
): Boolean
Updates the RemoteViews of the secondary toolbar in an existing custom tab session.
| Parameters | |
|---|---|
remoteViews: RemoteViews? |
The updated |
clickableIDs: IntArray? |
The ids of clickable views. The onClick event of these views will be handled by custom tabs. |
pendingIntent: PendingIntent? |
The |
funsetToolbarItem(id: Int, icon: Bitmap, description: String): Boolean
Updates the visuals for toolbar items. Will only succeed if a custom tab created using this session is in the foreground in browser and the given id is valid.
| Parameters | |
|---|---|
id: Int |
The id for the item to update. |
icon: Bitmap |
The new icon of the toolbar item. |
description: String |
Content description of the toolbar item. |
| Returns | |
|---|---|
Boolean |
Whether the update succeeded. |
validateRelationship
fun validateRelationship(
@CustomTabsService.Relation relation: Int,
origin: Uri,
extras: Bundle?
): Boolean
Requests to validate a relationship between the application and an origin.
See here for documentation about Digital Asset Links. This methods requests the browser to verify a relation with the calling application, to grant the associated rights.
If this method returns true, the validation result will be provided through onRelationshipValidationResult. Otherwise the request didn't succeed. The client must call warmup before this.
| Parameters | |
|---|---|
@CustomTabsService.Relation relation: Int |
Relation to check, must be one of the |
origin: Uri |
Origin. |
extras: Bundle? |
Reserved for future use. |
| Returns | |
|---|---|
Boolean |
|