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
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	`validateRelationship(relation: Int, @NonNull origin: Uri, @Nullable extras: Bundle?)` Requests to validate a relationship between the application and an origin.
Boolean	`requestPostMessageChannel(postMessageOrigin: Uri!)` Sends a request to create a two way postMessage channel between the client and the browser.
Int	`postMessage(message: String!, extras: Bundle!)` Sends a postMessage request using the origin communicated via `CustomTabsService#requestPostMessageChannel( * CustomTabsSessionToken, Uri)`.
Boolean	`setToolbarItem(id: Int, @NonNull icon: Bitmap, @NonNull description: String)` Updates the visuals for toolbar items.
Boolean	`mayLaunchUrl(url: Uri!, extras: Bundle!, otherLikelyBundles: MutableList<Bundle!>!)` Tells the browser of a likely future navigation to a URL.
static CustomTabsSession	`createMockSessionForTesting(@NonNull componentName: ComponentName)` Provides browsers a way to generate a mock `CustomTabsSession` for testing purposes.

Public methods

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.

See Also

CustomTabsSession#setToolbarItem(int, Bitmap, String)

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 `View`s in clickableIDs.

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.

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.

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.

setToolbarItem

fun setToolbarItem(id: Int, @NonNull icon: Bitmap, @NonNull 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`	Int: The new icon of the toolbar item.
`description`	Int: Content description of the toolbar item.

Return
Boolean: Whether the update succeeded.

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.

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.