# CustomTabsSession
Artifact: [androidx.browser:browser](https://developer.android.com/jetpack/androidx/releases/browser) [View Source](https://cs.android.com/search?q=file:androidx/browser/customtabs/CustomTabsSession.java+class:androidx.browser.customtabs.CustomTabsSession) Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
*** ** * ** ***
```
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
| ### Nested types |
|---|
| `public class https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession.PendingSession` A class to be used instead of `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession` when a Custom Tab is launched before a Service connection is established. |
| ### Public methods |
|---|---|
| `static @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession` | `@https://developer.android.com/reference/androidx/annotation/VisibleForTesting https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#createMockSessionForTesting(android.content.ComponentName)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/content/ComponentName.html componentName)` Provides browsers a way to generate a mock `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession` for testing purposes. |
| `boolean` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#isEngagementSignalsApiAvailable(android.os.Bundle)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Bundle.html extras)` Returns whether the Engagement Signals API is available. |
| `boolean` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#mayLaunchUrl(android.net.Uri,android.os.Bundle,java.util.List)( @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/net/Uri.html url, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/os/Bundle.html extras, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/util/List.html otherLikelyBundles )` Tells the browser of a likely future navigation to a URL. |
| `int` | `@https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsService.Result https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#postMessage(java.lang.String,android.os.Bundle)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html message, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/os/Bundle.html extras)` Sends a postMessage request using the origin communicated via `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsService#requestPostMessageChannel(androidx.browser.customtabs.CustomTabsSessionToken,android.net.Uri)`. |
| `void` | `@https://developer.android.com/reference/androidx/browser/customtabs/ExperimentalPrefetch https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#prefetch(android.net.Uri,androidx.browser.customtabs.PrefetchOptions)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html url, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/PrefetchOptions options)` Request the browser to start navigational prefetch to the page that will be used for future navigations. |
| `void` | `@https://developer.android.com/reference/androidx/browser/customtabs/ExperimentalPrefetch https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#prefetch(java.util.List,androidx.browser.customtabs.PrefetchOptions)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html urls, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/PrefetchOptions options)` Request the browser to start navigational prefetch to the pages that will be used for future navigations. |
| `boolean` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#receiveFile(android.net.Uri,int,android.os.Bundle)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html uri, int purpose, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/os/Bundle.html 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` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#requestPostMessageChannel(android.net.Uri)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html postMessageOrigin)` Sends a request to create a two way postMessage channel between the client and the browser. |
| `boolean` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#requestPostMessageChannel(android.net.Uri,android.net.Uri,android.os.Bundle)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html postMessageOrigin, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/net/Uri.html postMessageTargetOrigin, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Bundle.html extras )` 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` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setActionButton(android.graphics.Bitmap,java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Bitmap.html icon, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html description)` This sets the action button on the toolbar with ID `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsIntent#TOOLBAR_ACTION_BUTTON_ID()`. |
| `boolean` | `@https://developer.android.com/reference/androidx/annotation/RequiresFeature(name = https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable") https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setEngagementSignalsCallback(androidx.browser.customtabs.EngagementSignalsCallback,android.os.Bundle)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback callback, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Bundle.html extras )` Sets an `https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback` to receive callbacks for events related to the user's engagement with webpage within the tab. |
| `boolean` | `@https://developer.android.com/reference/androidx/annotation/RequiresFeature(name = https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable") https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setEngagementSignalsCallback(java.util.concurrent.Executor,androidx.browser.customtabs.EngagementSignalsCallback,android.os.Bundle)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback callback, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Bundle.html extras )` Sets an `https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback` to receive callbacks for events related to the user's engagement with webpage within the tab. |
| `boolean` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setSecondaryToolbarSwipeUpGesture(android.app.PendingIntent)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/app/PendingIntent.html pendingIntent)` Sets a `https://developer.android.com/reference/android/app/PendingIntent.html` object to be sent when the user swipes up from the secondary (bottom) toolbar. |
| `boolean` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setSecondaryToolbarViews(android.widget.RemoteViews,int[],android.app.PendingIntent)( @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/widget/RemoteViews.html remoteViews, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html int[] clickableIDs, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/app/PendingIntent.html pendingIntent )` Updates the `https://developer.android.com/reference/android/widget/RemoteViews.html` of the secondary toolbar in an existing custom tab session. |
| `boolean` | `[setToolbarItem](https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setToolbarItem(int,android.graphics.Bitmap,java.lang.String))(int id, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Bitmap.html icon, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html description)` **This method is deprecated.** Use CustomTabsSession#setSecondaryToolbarViews(RemoteViews, int\[\], PendingIntent)
|
| `boolean` | `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#validateRelationship(int,android.net.Uri,android.os.Bundle)( @https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsService.Relation int relation, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html origin, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/os/Bundle.html extras )` Requests to validate a relationship between the application and an origin. |
## Public methods
### createMockSessionForTesting
Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
@VisibleForTesting
public static @NonNull CustomTabsSession createMockSessionForTesting(@NonNull ComponentName componentName)
```
Provides browsers a way to generate a mock `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession` for testing purposes.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/content/ComponentName.html componentName` | The component the session should be created for. |
| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession` | A mock session with no functionality. |
### isEngagementSignalsApiAvailable
Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/browser#1.6.0)
```
public boolean isEngagementSignalsApiAvailable(@NonNull Bundle extras)
```
Returns whether the Engagement Signals API is available. The availability of the Engagement Signals API may change at runtime. If an `https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback` has been set, an `https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback#onSessionEnded(boolean,android.os.Bundle)` signal will be sent if the API becomes unavailable later.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Bundle.html extras` | Reserved for future use. |
| Returns |
|---|---|
| `boolean` | Whether the Engagement Signals API is available. A false value means `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setEngagementSignalsCallback(androidx.browser.customtabs.EngagementSignalsCallback,android.os.Bundle)` will return false and not set the callback. |
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | If the Service dies while responding to the request. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html` | If this method isn't supported by the Custom Tabs implementation. |
### mayLaunchUrl
Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
public boolean mayLaunchUrl(
@Nullable Uri url,
@Nullable Bundle extras,
@Nullable List 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 |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/net/Uri.html url` | Most likely URL, may be `null` if `otherLikelyBundles` is provided. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/os/Bundle.html extras` | Reserved for future use. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/util/List.html otherLikelyBundles` | Other likely destinations, sorted in decreasing likelihood order. Inside each Bundle, the client should provide a `https://developer.android.com/reference/android/net/Uri.html` using `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsService#KEY_URL()` with `https://developer.android.com/reference/android/os/Bundle.html#putParcelable(java.lang.String, android.os.Parcelable)`. |
| Returns |
|---|---|
| `boolean` | true for success. |
### postMessage
Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
@CustomTabsService.Result
public int postMessage(@NonNull String message, @Nullable Bundle extras)
```
Sends a postMessage request using the origin communicated via `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsService#requestPostMessageChannel(androidx.browser.customtabs.CustomTabsSessionToken,android.net.Uri)`. Fails when called before `https://developer.android.com/reference/androidx/browser/customtabs/PostMessageServiceConnection#notifyMessageChannelReady(android.os.Bundle)` is received on the client side.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html message` | The message that is being sent. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/os/Bundle.html extras` | Reserved for future use. |
| Returns |
|---|---|
| `int` | An integer constant about the postMessage request result. Will return `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsService#RESULT_SUCCESS()` if successful. |
### prefetch
Added in [1.9.0](https://developer.android.com/jetpack/androidx/releases/browser#1.9.0)
```
@ExperimentalPrefetch
public void prefetch(@NonNull Uri url, @NonNull PrefetchOptions options)
```
Request the browser to start navigational prefetch to the page that will be used for future navigations.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html url` | The url to be prefetched for upcoming navigations. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/PrefetchOptions options` | The option used for prefetch request. Please see `https://developer.android.com/reference/androidx/browser/customtabs/PrefetchOptions`. |
### prefetch
Added in [1.9.0](https://developer.android.com/jetpack/androidx/releases/browser#1.9.0)
```
@ExperimentalPrefetch
public void prefetch(@NonNull List urls, @NonNull PrefetchOptions options)
```
Request the browser to start navigational prefetch to the pages that will be used for future navigations.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html urls` | The urls to be prefetched for upcoming navigations. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/PrefetchOptions options` | The option used for prefetch request. Please see `https://developer.android.com/reference/androidx/browser/customtabs/PrefetchOptions`. |
### receiveFile
Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
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 `https://developer.android.com/reference/android/content/Context.html#grantUriPermission(java.lang.String, android.net.Uri, int)`. The file is read and processed (where applicable) synchronously, therefore it's recommended to call this method on a background thread.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html uri` | `https://developer.android.com/reference/android/net/Uri.html` of the file. |
| `int purpose` | Purpose of transferring this file, one of the constants enumerated in `CustomTabsService#FilePurpose`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/os/Bundle.html extras` | Reserved for future use. |
| Returns |
|---|---|
| `boolean` | `true` if the file was received successfully. |
### requestPostMessageChannel
Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
public boolean requestPostMessageChannel(@NonNull Uri postMessageOrigin)
```
Sends a request to create a two way postMessage channel between the client and the browser.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html 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. |
### requestPostMessageChannel
Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/browser#1.6.0)
```
public boolean requestPostMessageChannel(
@NonNull Uri postMessageOrigin,
@Nullable Uri postMessageTargetOrigin,
@NonNull Bundle extras
)
```
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 |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html postMessageOrigin` | A origin that the client is requesting to be identified as during the postMessage communication. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/net/Uri.html postMessageTargetOrigin` | The target Origin to establish the postMessage communication with. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Bundle.html extras` | 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](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
public boolean setActionButton(@NonNull Bitmap icon, @NonNull String description)
```
This sets the action button on the toolbar with ID `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsIntent#TOOLBAR_ACTION_BUTTON_ID()`.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Bitmap.html icon` | The new icon of the action button. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html description` | Content description of the action button. |
| See also |
|---|---|
| `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setToolbarItem(int,android.graphics.Bitmap,java.lang.String)` | |
### setEngagementSignalsCallback
Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/browser#1.6.0)
```
@RequiresFeature(name = CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable")
public boolean setEngagementSignalsCallback(
@NonNull EngagementSignalsCallback callback,
@NonNull Bundle extras
)
```
Sets an `https://developer.android.com/reference/androidx/browser/customtabs/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 `https://developer.android.com/reference/android/os/Looper.html#getMainLooper()`. To specify the execution thread, use `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setEngagementSignalsCallback(java.util.concurrent.Executor,androidx.browser.customtabs.EngagementSignalsCallback,android.os.Bundle)`.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback callback` | The `https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback` to receive the user engagement signals. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Bundle.html extras` | Reserved for future use. |
| Returns |
|---|---|
| `boolean` | Whether the callback connection is allowed. If false, no callbacks will be called for this session. |
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | If the Service dies while responding to the request. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html` | If this method isn't supported by the Custom Tabs implementation. |
### setEngagementSignalsCallback
Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/browser#1.6.0)
```
@RequiresFeature(name = CustomTabsFeatures.ENGAGEMENT_SIGNALS, enforcement = "androidx.browser.customtabs.CustomTabsSession#isEngagementSignalsApiAvailable")
public boolean setEngagementSignalsCallback(
@NonNull Executor executor,
@NonNull EngagementSignalsCallback callback,
@NonNull Bundle extras
)
```
Sets an `https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback` to receive callbacks for events related to the user's engagement with webpage within the tab.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor` | The `https://developer.android.com/reference/java/util/concurrent/Executor.html` to be used to execute the callbacks. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback callback` | The `https://developer.android.com/reference/androidx/browser/customtabs/EngagementSignalsCallback` to receive the user engagement signals. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Bundle.html extras` | Reserved for future use. |
| Returns |
|---|---|
| `boolean` | Whether the callback connection is allowed. If false, no callbacks will be called for this session. |
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | If the Service dies while responding to the request. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html` | If this method isn't supported by the Custom Tabs implementation. |
### setSecondaryToolbarSwipeUpGesture
Added in [1.7.0](https://developer.android.com/jetpack/androidx/releases/browser#1.7.0)
```
public boolean setSecondaryToolbarSwipeUpGesture(@Nullable PendingIntent pendingIntent)
```
Sets a `https://developer.android.com/reference/android/app/PendingIntent.html` object to be sent when the user swipes up from the secondary (bottom) toolbar.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/app/PendingIntent.html pendingIntent` | `https://developer.android.com/reference/android/app/PendingIntent.html` to send. |
| Returns |
|---|---|
| `boolean` | Whether the update succeeded. |
### setSecondaryToolbarViews
Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
public boolean setSecondaryToolbarViews(
@Nullable RemoteViews remoteViews,
@Nullable int[] clickableIDs,
@Nullable PendingIntent pendingIntent
)
```
Updates the `https://developer.android.com/reference/android/widget/RemoteViews.html` of the secondary toolbar in an existing custom tab session.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/widget/RemoteViews.html remoteViews` | The updated `https://developer.android.com/reference/android/widget/RemoteViews.html` that will be shown in secondary toolbar. If null, the current secondary toolbar will be dismissed. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html int[] clickableIDs` | The ids of clickable views. The onClick event of these views will be handled by custom tabs. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/app/PendingIntent.html pendingIntent` | The `https://developer.android.com/reference/android/app/PendingIntent.html` that will be sent when the user clicks on one of the `https://developer.android.com/reference/android/view/View.html`s in clickableIDs. |
### setToolbarItem
Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0) Deprecated in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
public boolean [setToolbarItem](https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#setToolbarItem(int,android.graphics.Bitmap,java.lang.String))(int id, @NonNull Bitmap icon, @NonNull String description)
```
> [!CAUTION]
> **This method is 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 |
|---|---|
| `int id` | The id for the item to update. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Bitmap.html icon` | The new icon of the toolbar item. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html description` | Content description of the toolbar item. |
| Returns |
|---|---|
| `boolean` | Whether the update succeeded. |
### validateRelationship
Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/browser#1.2.0)
```
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](https://developers.google.com/digital-asset-links/v1/getting-started) 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 `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsCallback#onRelationshipValidationResult(int,android.net.Uri,boolean,android.os.Bundle)`. Otherwise the request didn't succeed. The client must call `https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsClient#warmup(long)` before this.
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsService.Relation int relation` | Relation to check, must be one of the `CustomTabsService#RELATION_* ` constants. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/net/Uri.html origin` | Origin. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/os/Bundle.html extras` | Reserved for future use. |
| Returns |
|---|---|
| `boolean` | `true` if the request has been submitted successfully. |