Register now for Android Dev Summit 2019!

CustomTabsSession

class CustomTabsSession
kotlin.Any
   ↳ androidx.browser.customtabs.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

Public methods

static CustomTabsSession
createMockSessionForTesting(@NonNull componentName: ComponentName)

Provides browsers a way to generate a mock CustomTabsSession for testing purposes.

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

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

Int
postMessage(message: String!, extras: Bundle!)

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

Boolean
requestPostMessageChannel(postMessageOrigin: Uri!)

Sends a request to create a two way postMessage channel between the client and the browser.

Boolean
setActionButton(@NonNull icon: Bitmap, @NonNull description: String)

This sets the action button on the toolbar with ID CustomTabsIntent#TOOLBAR_ACTION_BUTTON_ID.

Boolean
setSecondaryToolbarViews(@Nullable remoteViews: RemoteViews?, @Nullable clickableIDs: IntArray?, @Nullable pendingIntent: PendingIntent?)

Updates the RemoteViews of the secondary toolbar in an existing custom tab session.

Boolean
setToolbarItem(id: Int, @NonNull icon: Bitmap, @NonNull description: String)

Updates the visuals for toolbar items.

Boolean
validateRelationship(relation: Int, @NonNull origin: Uri, @Nullable extras: Bundle?)

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

Public methods

createMockSessionForTesting

@NonNull static fun createMockSessionForTesting(@NonNull 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.
Return
CustomTabsSession: A mock session with no functionality.

mayLaunchUrl

fun mayLaunchUrl(url: Uri!, extras: Bundle!, otherLikelyBundles: MutableList<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.
extras Uri!: Reserved for future use.
otherLikelyBundles Uri!: Other likely destinations, sorted in decreasing likelihood order. Inside each Bundle, the client should provide a Uri using CustomTabsService#KEY_URL with Bundle#putParcelable(String, android.os.Parcelable).
Return
Boolean: true for success.

postMessage

fun postMessage(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
message String!: The message that is being sent.
extras String!: Reserved for future use.
Return
Int: An integer constant about the postMessage request result. Will return CustomTabsService#RESULT_SUCCESS if successful.

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

setActionButton

fun setActionButton(@NonNull icon: Bitmap, @NonNull description: String): Boolean

This sets the action button on the toolbar with ID CustomTabsIntent#TOOLBAR_ACTION_BUTTON_ID.

Parameters
icon Bitmap: The new icon of the action button.
description Bitmap: Content description of the action button.

setSecondaryToolbarViews

fun setSecondaryToolbarViews(@Nullable remoteViews: RemoteViews?, @Nullable clickableIDs: IntArray?, @Nullable pendingIntent: PendingIntent?): Boolean

Updates the RemoteViews of the secondary toolbar in an existing custom tab session.

Parameters
remoteViews RemoteViews?: The updated RemoteViews that will be shown in secondary toolbar. If null, the current secondary toolbar will be dismissed.
clickableIDs RemoteViews?: The ids of clickable views. The onClick event of these views will be handled by custom tabs.
pendingIntent RemoteViews?: The PendingIntent that will be sent when the user clicks on one of the Views in clickableIDs.

setToolbarItem

fun setToolbarItem(id: Int, @NonNull icon: Bitmap, @NonNull description: String): Boolean

Deprecated: Use CustomTabsSession#setSecondaryToolbarViews(RemoteViews, int[], PendingIntent)

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 Int: The new icon of the toolbar item.
description Int: Content description of the toolbar item.
Return
Boolean: Whether the update succeeded.

validateRelationship

fun validateRelationship(relation: Int, @NonNull origin: Uri, @Nullable 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 CustomTabsCallback#onRelationshipValidationResult(int, Uri, boolean, Bundle). Otherwise the request didn't succeed. The client must call CustomTabsClient#warmup(long) before this.

Parameters
relation Int: Relation to check, must be one of the CustomTabsService#RELATION_* constants.
origin Int: Origin.
extras Int: Reserved for future use.
Return
Boolean: true if the request has been submitted successfully.