CustomTabsSession

Kotlin |Java

public final 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 methods
`boolean`	`mayLaunchUrl( @Nullable Uri url, @Nullable Bundle extras, @Nullable List<Bundle> otherLikelyBundles )` Tells the browser of a likely future navigation to a URL.
`int`	`@CustomTabsService.Result postMessage(@NonNull String message, @Nullable Bundle extras)` Sends a postMessage request using the origin communicated via `requestPostMessageChannel`.
`boolean`	`receiveFile(@NonNull Uri uri, int purpose, @Nullable Bundle extras)` 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(@NonNull Uri postMessageOrigin)` Sends a request to create a two way postMessage channel between the client and the browser.
`boolean`	`setActionButton(@NonNull Bitmap icon, @NonNull String description)` This sets the action button on the toolbar with ID `TOOLBAR_ACTION_BUTTON_ID`.
`boolean`	`setSecondaryToolbarViews( @Nullable RemoteViews remoteViews, @Nullable int[] clickableIDs, @Nullable PendingIntent pendingIntent )` Updates the `RemoteViews` of the secondary toolbar in an existing custom tab session.
`boolean`	`setToolbarItem(int id, @NonNull Bitmap icon, @NonNull String description)` This method is deprecated. Use CustomTabsSession#setSecondaryToolbarViews(RemoteViews, int[], PendingIntent)
`boolean`	`validateRelationship( @CustomTabsService.Relation int relation, @NonNull Uri origin, @Nullable Bundle extras )` Requests to validate a relationship between the application and an origin.

Public methods

mayLaunchUrl

public boolean mayLaunchUrl(
    @Nullable Uri url,
    @Nullable Bundle extras,
    @Nullable List<Bundle> otherLikelyBundles
)

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
`@Nullable Uri url`	Most likely URL, may be `null` if `otherLikelyBundles` is provided.
`@Nullable Bundle extras`	Reserved for future use.
`@Nullable List<Bundle> otherLikelyBundles`	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

@CustomTabsService.Result
public int postMessage(@NonNull String message, @Nullable Bundle extras)

Sends a postMessage request using the origin communicated via requestPostMessageChannel. Fails when called before notifyMessageChannelReady is received on the client side.

Parameters
`@NonNull String message`	The message that is being sent.
`@Nullable Bundle extras`	Reserved for future use.

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

receiveFile

public boolean receiveFile(@NonNull Uri uri, int purpose, @Nullable Bundle extras)

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
`@NonNull Uri uri`	`Uri` of the file.
`int purpose`	Purpose of transferring this file, one of the constants enumerated in `CustomTabsService#FilePurpose`.
`@Nullable Bundle extras`	Reserved for future use.

Returns
`boolean`	`true` if the file was received successfully.

requestPostMessageChannel

public boolean requestPostMessageChannel(@NonNull Uri postMessageOrigin)

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

Parameters
`@NonNull Uri postMessageOrigin`	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.

setActionButton

public boolean setActionButton(@NonNull Bitmap icon, @NonNull String description)

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

Parameters
`@NonNull Bitmap icon`	The new icon of the action button.
`@NonNull String description`	Content description of the action button.

See also
`setToolbarItem`

public boolean setSecondaryToolbarViews(
    @Nullable RemoteViews remoteViews,
    @Nullable int[] clickableIDs,
    @Nullable PendingIntent pendingIntent
)

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

Parameters
`@Nullable RemoteViews remoteViews`	The updated `RemoteViews` that will be shown in secondary toolbar. If null, the current secondary toolbar will be dismissed.
`@Nullable int[] clickableIDs`	The ids of clickable views. The onClick event of these views will be handled by custom tabs.
`@Nullable PendingIntent pendingIntent`	The `PendingIntent` that will be sent when the user clicks on one of the `View`s in clickableIDs.

setToolbarItem

public boolean setToolbarItem(int id, @NonNull Bitmap icon, @NonNull String description)

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
`int id`	The id for the item to update.
`@NonNull Bitmap icon`	The new icon of the toolbar item.
`@NonNull String description`	Content description of the toolbar item.

Returns
`boolean`	Whether the update succeeded.

validateRelationship

public boolean validateRelationship(
    @CustomTabsService.Relation int relation,
    @NonNull Uri origin,
    @Nullable Bundle extras
)

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 int relation`	Relation to check, must be one of the `CustomTabsService#RELATION_*` constants.
`@NonNull Uri origin`	Origin.
`@Nullable Bundle extras`	Reserved for future use.

Returns
`boolean`	`true` if the request has been submitted successfully.