Android Browser Switch

Android Browser Switch makes it easy to open a url in a browser or Chrome Custom Tab and receive a response as the result of user interaction, either cancel or response data from the web page.

Setup

Add the library to your dependencies in your build.gradle:

dependencies {
  implementation 'com.braintreepayments.api:browser-switch:2.6.1'
}

To preview the latest work in progress builds, add the following SNAPSHOT dependency in your build.gradle:

dependencies {
  implementation 'com.braintreepayments.api:browser-switch:2.6.2-SNAPSHOT'
}

You will also need to add the Sonatype snapshots repo to your top-level build.gradle to import SNAPSHOT builds:

allprojects {
    repositories {
        maven {
            url 'https://oss.sonatype.org/content/repositories/snapshots/'
        }
    }
}

AndroidManifest.xml

Declare an activity that you own as a deep link target in your AndroidManifest.xml:

<activity android:name="com.myapp.MyDeepLinkTargetActivity"
    android:launchMode="singleTask"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>
        <data android:scheme="my-custom-url-scheme"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
    </intent-filter>
</activity>

Note: The scheme you define must use all lowercase letters. This is due to scheme matching on the Android framework being case sensitive, expecting lower case. The scheme must also be valid according to RFC 2396.

If these requirements are not met, an error will be returned and no browser switch will occur.

Usage

A browser switch can be initiated by calling BrowserSwitchClient#start(). Use BrowserSwitchOptions to configure options for browser switching:

val browserSwitchOptions = BrowserSwitchOptions()
    .requestCode(MY_REQUEST_CODE)
    .url("https://site-to-load.com?callbackURL=my-custom-url-scheme%3A%2F%2Fsuccess")
    .returnUrlScheme("my-custom-url-scheme")
browserSwitchClient.start(activity, browserSwitchOptions)

In the above example, notice the encoded callbackURL parameter is forwarded to the website that will be loaded. The callback url must have the same custom scheme set in BrowserSwitchOptions. When this URL is loaded by the site, the Android OS will re-direct the user to the deep link destination Activity defined in the AndroidManifest.xml.

To capture a browser switch result, override your deep link target Activity with the following code snippet:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    browserSwitchClient.deliverResult(this)?.let { result ->
        when (result) {
            BrowserSwitchStatus.OK -> {
                // the browser switch returned data in the return uri
                // TODO: handle success
            }
            BrowserSwitchStatus.CANCEL -> {
                // the user canceled and returned to your app return uri is null
                // TODO: handle cancelation
            }
        }
    }
}

Launch Modes

If your deep link target Activity has android:launchMode="singleTop", android:launchMode="singleTask", or android:launchMode="singleInstance", add the following code snippet to your deep link target Activity:

override fun onNewIntent(newIntent: Intent?) {
    super.onNewIntent(intent)
    intent = newIntent
}

Versions

This SDK abides by our Client SDK Deprecation Policy. For more information on the potential statuses of an SDK check our developer docs.

Major version number	Status	Released	Deprecated	Unsupported
2.x.x	Active	February 2021	TBA	TBA
1.x.x	Inactive	June 2020	April 2022	April 2023

Help

• Check out the reference docs
• Find a bug? Open an issue
• Want to contribute? Check out contributing guidelines and submit a pull request.

License

Android Browser Switch is open source and available under the MIT license. See the LICENSE file for more info.