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

Public functions
java-static CustomTabsSession

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

Returns whether the Engagement Signals API is available.
Boolean
mayLaunchUrl(
    url: Uri?,
    extras: Bundle?,
    otherLikelyBundles: (Mutable)List<Bundle!>?
)

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

Sends a postMessage request using the origin communicated via requestPostMessageChannel.
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(
    postMessageOrigin: Uri,
    postMessageTargetOrigin: Uri?,
    extras: Bundle
)

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 TOOLBAR_ACTION_BUTTON_ID.
Boolean
@RequiresFeature(name = CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable")
setEngagementSignalsCallback(
    callback: EngagementSignalsCallback,
    extras: Bundle
)

Sets an EngagementSignalsCallback to receive callbacks for events related to the user's engagement with webpage within the tab.
Boolean
@RequiresFeature(name = CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable")
setEngagementSignalsCallback(
    executor: Executor,
    callback: EngagementSignalsCallback,
    extras: Bundle
)

Sets an EngagementSignalsCallback to receive callbacks for events related to the user's engagement with webpage within the tab.
Boolean

Sets a PendingIntent object to be sent when the user swipes up from the secondary (bottom) toolbar.
Boolean
setSecondaryToolbarViews(
    remoteViews: RemoteViews?,
    clickableIDs: IntArray?,
    pendingIntent: PendingIntent?
)

Updates the RemoteViews of the secondary toolbar in an existing custom tab session.
Boolean
setToolbarItem(id: Int, icon: Bitmap, description: String)

This function is deprecated.

Use CustomTabsSession#setSecondaryToolbarViews(RemoteViews, int[], PendingIntent)
Boolean
validateRelationship(
    @CustomTabsService.Relation relation: Int,
    origin: Uri,
    extras: Bundle?
)

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

Public functions

createMockSessionForTesting

Added in 1.2.0
@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

Added in 1.6.0
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

Added in 1.2.0
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 null if otherLikelyBundles is provided.
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 Uri using KEY_URL with putParcelable.
Returns
Boolean

true for success.

postMessage

Added in 1.2.0
@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.

Parameters
message: String

The message that is being sent.
extras: Bundle?

Reserved for future use.
Returns
Int

An integer constant about the postMessage request result. Will return RESULT_SUCCESS if successful.

receiveFile

Added in 1.2.0
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

Uri of the file.
purpose: Int

Purpose of transferring this file, one of the constants enumerated in CustomTabsService#FilePurpose.
extras: Bundle?

Reserved for future use.
Returns
Boolean

true if the file was received successfully.

requestPostMessageChannel

Added in 1.2.0
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

Added in 1.6.0
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

Added in 1.2.0
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

Added in 1.6.0
@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 EngagementSignalsCallback to receive the user engagement signals.
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

Added in 1.6.0
@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 Executor to be used to execute the callbacks.
callback: EngagementSignalsCallback

The EngagementSignalsCallback to receive the user engagement signals.
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

Added in 1.7.0
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?

PendingIntent to send.
Returns
Boolean

Whether the update succeeded.

setSecondaryToolbarViews

Added in 1.2.0
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 RemoteViews that will be shown in secondary toolbar. If null, the current secondary toolbar will be dismissed.
clickableIDs: IntArray?

The ids of clickable views. The onClick event of these views will be handled by custom tabs.
pendingIntent: PendingIntent?

The PendingIntent that will be sent when the user clicks on one of the Views in clickableIDs.

setToolbarItem

Added in 1.2.0
Deprecated in 1.2.0
fun setToolbarItem(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

Added in 1.2.0
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 CustomTabsService#RELATION_* constants.
origin: Uri

Origin.
extras: Bundle?

Reserved for future use.
Returns
Boolean

true if the request has been submitted successfully.