Skip to content

Open a url in a browser or Chrome Custom Tab and receive a response as the result of user interaction.

License

Notifications You must be signed in to change notification settings

braintree/browser-switch-android

Folders and files

NameName
Last commit message
Last commit date

Latest commit

fd7c8aa · Aug 28, 2024
Jul 10, 2024
Jun 23, 2020
Aug 28, 2024
Aug 28, 2024
Jul 10, 2024
Aug 28, 2024
Jun 22, 2020
May 17, 2023
Jun 23, 2020
Nov 22, 2016
Aug 28, 2024
Feb 24, 2017
Jul 10, 2024
Aug 28, 2024
Sep 29, 2023
Jan 25, 2024
Nov 18, 2016
Nov 18, 2016
Jul 3, 2017
Jun 3, 2024
May 29, 2024

Repository files navigation

Android Browser Switch

GitHub Actions Tests

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:3.0.0-beta1'
}

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

dependencies {
  implementation 'com.braintreepayments.api:browser-switch:3.0.0-beta1-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: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().apply {
    requestCode = MY_REQUEST_CODE
    url = "https://site-to-load.com?callbackURL=my-custom-url-scheme%3A%2F%2Fsuccess"
    returnUrlScheme = "my-custom-url-scheme"
}

when (val pendingRequest = browserSwitchClient.start(this, browserSwitchOptions)) {
    is BrowserSwitchPendingRequest.Started -> {
        // store pending request
    }
    is BrowserSwitchPendingRequest.Failure -> {
        // browser was unable to be launched, handle failure
    }
}

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 onResume() {
    handleReturnToAppFromBrowser(intent) 
}

fun handleReturnToAppFromBrowser(intent: Intent) {
    // fetch stored pending request
    fetchPendingRequestFromPersistentStorage()?.let { startedRequest ->
        when (val browserSwitchResult = browserSwitchClient.parseResult(startedRequest, intent)) {
            is BrowserSwitchResult.Success -> {
                // handle successful browser switch result
                // clear stored pending request
            }
            is BrowserSwitchResult.NoResult -> {
                // user did not complete browser switch
                // allow user to complete browser switch, or clear stored pending request
            }
        }
    }
}

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 in the onNewIntent method instead of onResume:

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

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
3.x.x Beta TBA TBA TBA
2.x.x Active February 2021 TBA TBA
1.x.x Inactive June 2020 April 2022 April 2023

Help

License

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