BrowserSwitchClient

constructor()

Construct a client that manages browser switching with Chrome Custom Tabs fallback only. This constructor does not initialize Auth Tab support. For Auth Tab functionality, use BrowserSwitchClient instead.


constructor(@NonNull caller: ActivityResultCaller)

Construct a client that manages the logic for browser switching and automatically initializes the Auth Tab launcher.

IMPORTANT: This constructor enables the AuthTab functionality, which has several caveats:

  • This constructor must be called in the activity/fragment's onCreate() method to properly register the activity result launcher before the activity/fragment is started.
  • The caller must be an ActivityResultCaller to register for activity results.
  • ACTIVITY_NEW_TASK is not supported when using AuthTab and will be ignored. Only ACTIVITY_CLEAR_TOP is supported with AuthTab.
  • When using SingleTop activities, you must check for launcher results in onResume() as well as in onNewIntent(), since the AuthTab activity result might be delivered during the resuming phase.
  • Care must be taken to avoid calling completeRequest multiple times for the same result. Merchants should properly track their pending request state to ensure the completeRequest method is only called once per browser switch session.
  • AuthTab support is browser version dependent. It requires Chrome version 137 or higher on the user's device. On devices with older browser versions, the library will automatically fall back to Custom Tabs. This means that enabling AuthTab is not guaranteed to use the AuthTab flow if the user's browser version is too old.

Consider using the default constructor BrowserSwitchClient if these limitations are incompatible with your implementation.

Parameters

caller

The ActivityResultCaller used to initialize the Auth Tab launcher.


constructor(@NonNull registry: ActivityResultRegistry)

Construct a client that manages the logic for browser switching and automatically initializes the Auth Tab launcher. Use this constructor for flows where ActivityResultCaller is not available.

IMPORTANT: This constructor enables the AuthTab functionality, which has several caveats:

  • ACTIVITY_NEW_TASK is not supported when using AuthTab and will be ignored. Only ACTIVITY_CLEAR_TOP is supported with AuthTab.
  • When using SingleTop activities, you must check for launcher results in onResume() as well as in onNewIntent(), since the AuthTab activity result might be delivered during the resuming phase.
  • Care must be taken to avoid calling completeRequest multiple times for the same result. Merchants should properly track their pending request state to ensure the completeRequest method is only called once per browser switch session.
  • AuthTab support is browser version dependent. It requires Chrome version 137 or higher on the user's device. On devices with older browser versions, the library will automatically fall back to Custom Tabs. This means that enabling AuthTab is not guaranteed to use the AuthTab flow if the user's browser version is too old.

Consider using the default constructor BrowserSwitchClient if these limitations are incompatible with your implementation.

The launcher is registered under a random key, so an Auth Tab result that arrives while the host activity is being recreated cannot be delivered to the new client. Use BrowserSwitchClient when the result must survive recreation.

Parameters

registry

The ActivityResultRegistry used to initialize the Auth Tab launcher


constructor(@NonNull registry: ActivityResultRegistry, @NonNull registryKey: String)

Construct a client that manages the logic for browser switching and initializes the Auth Tab launcher on the given ActivityResultRegistry under a caller-provided key.

Use this constructor, instead of BrowserSwitchClient, when the client is created outside of an activity's onCreate(), for example in Jetpack Compose. If the activity is destroyed while the browser is open, the registry stores the Auth Tab result under the key the launcher was registered with. Registering the new client's launcher under the same key lets the registry deliver that result.

The key must:

  • be the same value each time the client is recreated for the same flow, for example a value saved with rememberSaveable.
  • be unique for each BrowserSwitchClient that uses the same registry, otherwise results for one client could be delivered to another.

After the activity is recreated, call restorePendingRequest before calling completeRequest, because the pending request is only kept in memory.

The same Auth Tab caveats as BrowserSwitchClient apply.

Parameters

registry

The ActivityResultRegistry used to initialize the Auth Tab launcher

registryKey

The key the Auth Tab launcher is registered under