Warm-up and pre-fetch: using the Custom Tabs Service

Sebastian Benz

The third part of this guide focuses on the Custom Tabs Service and why using it in your application creates a better user experience:

• Instantly open external content: using warmup() causes the browser process to start in the background even before the user clicks on a link and can save up to 700ms when opening a link. mayLaunchUrl() pre-fetches pages. Using both APIs together allow pages to load instantly, greatly improving the user experience of a Custom Tabs integration.
• Better handling of minimized Custom tabs: by connecting to the Custom Tabs service and using the same CustomTabSession when launching the Custom Tab, Chrome will be able to remove a previously minimized Custom Tabs before launching a new tab, delivering a more consistent user experience.

The required steps are:

1. Check if the default browser supports Custom Tabs using CustomTabsClient.getPackageName(...). If yes, bind to the CustomTabsService using CustomTabsClient.bindCustomTabsService().

2. Once connected to the CustomTabsService, in the CustomTabsServiceConnection.onCustomTabsServiceConnected() callback, do:

   a. Warmup the browser process using CustomTabsClient.warmup(). b. Create a new CustomTabsSession using CustomTabsClient.newSession().

3. Optionally, prefetch web pages the user is likely to visit using CustomTabsSession.mayLaunchUrl().

4. When launching a new Custom Tab, pass the CustomTabsSession to the CustomTabsIntent.Builder using the constructor new CustomTabsIntent.Builder(session).

If your app targets Android API level 30, CustomTabsClient.getPackageName(...) requires you to add a queries section to your Android Manifest, declaring an intent-filter that matches browsers with Custom Tabs support.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
  …
   <queries>
        <intent>
            <action android:name="android.support.customtabs.action.CustomTabsService" />
        </intent>
    </queries>
</manifest>

Here is a full example for how to connect to a Custom Tabs service:

private CustomTabsClient mClient;
private CustomTabsSession mSession;

private CustomTabsServiceConnection mConnection = new CustomTabsServiceConnection() {
    @Override
    public void onCustomTabsServiceConnected(
            @NonNull ComponentName name,
            @NonNull CustomTabsClient client
    ) {
        mClient = client;
        // Warm up the browser process
        mClient.warmup(0 /* placeholder for future use */);
        // Create a new browser session
        mSession = mClient.newSession(new CustomTabsCallback());
        // Pre-render pages the user is likely to visit
        // you can do this any time while the service is connected
        mSession.mayLaunchUrl(Uri.parse("https://developers.android.com"), null, null);
    }

    @Override
    public void onServiceDisconnected(ComponentName name) {
        mClient = null;
        mSession = null;
    }
};

private void bindCustomTabService(Context context) {
    // Check for an existing connection
    if (mClient != null) {
        // Do nothing if there is an existing service connection
        return;
    }

    // Get the default browser package name, this will be null if
    // the default browser does not provide a CustomTabsService
    String packageName = CustomTabsClient.getPackageName(context, null);
    if (packageName == null) {
        // Do nothing as service connection is not supported
        return;
    }
    CustomTabsClient.bindCustomTabsService(context, packageName, mConnection);
}

@Override
protected void onCreate(Bundle savedInstanceState) {
…
    bindCustomTabService(this);
    findViewById(R.id.button).setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View view) {
            String url = "https://developers.android.com";
            CustomTabsIntent intent = new CustomTabsIntent.Builder(mSession)
                    .build();
            intent.launchUrl(MainActivity.this, Uri.parse(url));
        }
    });
}

Caution: A Custom Tabs service connection might fail while your activity is running. If your app requires an active service connection, there are two strategies to ensure a working service connection:

1. When eagerly connecting to the CustomTabsService during onCreate(), reconnect to the service if your activity gets disconnected and the onServiceDisconnected() callback gets invoked.
2. Wait until the user triggers a Custom Tab, then establish the service connection and launch the Custom Tab.

Open links in Android apps

On Android, URLs can be handled by Android applications. For example, if the user has the Facebook app installed and clicks on a link to a Facebook post, they usually prefer the link opening in the Facebook app instead of in the browser.

By default, Custom Tabs opens links in the respective Android application if installed. However, once a CustomTabsServiceConnection has been established, this behavior stops working and all URLs open in Custom Tabs instead. For an improved user experience, we recommend re-enabling this behavior using the following code:

CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder()
    .setSendToExternalDefaultHandlerEnabled(true)
    .build();

Next up: Learn how to resize the Custom Tabs experience.