Chrome Custom Tabs let apps open web content in a browser tab that looks like part of the app. They're faster than opening Chrome, more capable than a WebView, and used by millions of apps for in-app browsing. But when App Links are involved, Custom Tabs create a set of behaviors that confuse developers and users alike.<\/p>\n\n\n\n
The core issue: when a user taps a link inside a Custom Tab, should Android open the linked app (via App Links) or keep the user in the Custom Tab? The answer depends on the Chrome version, the link verification status, and how the Custom Tab was launched. This guide covers all of it.<\/p>\n\n\n\n
For the foundational App Links setup, see the Android App Links complete guide<\/a>. For the difference between verified and unverified links, see verified vs. unverified App Links<\/a>.<\/p>\n\n\n\n Chrome Custom Tabs<\/a> are a feature of Chrome (and other Chromium-based browsers) that lets apps open URLs in a lightweight browser tab. The hosting app can customize the toolbar color, add action buttons, and define animations.<\/p>\n\n\n\n From the user's perspective, it looks like an in-app browser. From the system's perspective, it's Chrome running in a separate process with a custom UI overlay.<\/p>\n\n\n\n This means your App Links need to work correctly when clicked inside a Custom Tab, because that's how many users will encounter them.<\/p>\n\n\n\n When a user taps a verified App Link inside a Chrome Custom Tab:<\/p>\n\n\n\n This means: if your app opens a Custom Tab pointing to Chrome specifically prevents a Custom Tab from triggering an App Link back to the app that launched it. This stops the circular navigation pattern:<\/p>\n\n\n\n This protection is sensible but causes confusion when:<\/p>\n\n\n\n App Links to other<\/strong> apps work normally from Custom Tabs. If a user is reading a page in your Custom Tab and taps a link that's a verified App Link for a different app, that app will open.<\/p>\n\n\n\n Pre-connecting to the Custom Tabs service improves performance and ensures the browser is ready to handle navigation correctly.<\/p>\n\n\n\n When you use a Custom Tab for a flow that should return to your app (like OAuth), use an intent flag to handle the return:<\/p>\n\n\n\n For the return redirect, use a custom scheme or an App Link with an intent filter that catches the redirect URL:<\/p>\n\n\n\n Symptom<\/strong>: A user taps a verified App Link inside a Custom Tab, but the app doesn't open. The link loads in the browser instead.<\/p>\n\n\n\n Cause<\/strong>: Chrome's same-app protection is active, OR the App Link is not verified.<\/p>\n\n\n\n Fix<\/strong>:<\/p>\n\n\n\n Symptom<\/strong>: Instead of opening the app directly, Chrome shows a "Open with" dialog.<\/p>\n\n\n\n Cause<\/strong>: The App Link is not verified (unverified links show a disambiguation dialog) or another app has registered the same domain.<\/p>\n\n\n\n Fix<\/strong>: Ensure your Digital Asset Links file<\/a> is correctly hosted at Symptom<\/strong>: The app opens correctly, but the Custom Tab remains in the recent apps list or back stack.<\/p>\n\n\n\n Fix<\/strong>: Use Symptom<\/strong>: Custom Tabs work fine in Chrome but fail in Samsung Internet, Firefox, or other browsers.<\/p>\n\n\n\n Cause<\/strong>: Custom Tabs behavior varies by browser. Samsung Internet has its own Custom Tabs implementation with different App Link handling.<\/p>\n\n\n\n Fix<\/strong>: Test on the top 3-4 browsers used by your audience. For critical flows, consider using a standard Don't use Custom Tabs for your own App Links.<\/strong> If you need to open a URL that should resolve back to your own app, use Use Custom Tabs for third-party web content.<\/strong> They're perfect for opening external links, documentation pages, or web content that doesn't need to redirect back to your app.<\/p>\n\n\n\n Test with multiple browsers.<\/strong> Custom Tab behavior varies across Chrome, Samsung Internet, and other Chromium-based browsers. Test on the browsers your users actually use.<\/p>\n\n\n\n Handle the back button correctly.<\/strong> When a user presses back in a Custom Tab, they should return to your app, not to a blank screen. Set up the activity launch mode correctly.<\/p>\n\n\n\n Pre-warm the connection.<\/strong> Call For Tolinku deep links<\/a>, the platform handles browser detection and routing automatically. When a Tolinku link is opened in a Custom Tab, the redirect chain resolves the App Link correctly without triggering the same-app protection issue. See the App Links documentation<\/a> for setup.<\/p>\n\n\n\nHow Chrome Custom Tabs Work<\/h2>\n\n\n\n
\/\/ Launch a Chrome Custom Tab\nval customTabsIntent = CustomTabsIntent.Builder()\n .setToolbarColor(ContextCompat.getColor(this, R.color.primary))\n .setShowTitle(true)\n .build()\n\ncustomTabsIntent.launchUrl(this, Uri.parse("https:\/\/example.com\/page"))\n<\/code><\/pre>\n\n\n\nWho Uses Custom Tabs<\/h3>\n\n\n\n
\n
The App Links Behavior in Custom Tabs<\/h2>\n\n\n\n
Default Behavior (Chrome 90+)<\/h3>\n\n\n\n
\n
https:\/\/links.yourapp.com\/promo<\/code>, the system will NOT redirect back to your own app, even if that URL is a verified App Link. This is by design; it prevents a redirect loop.<\/p>\n\n\n\nThe Same-App Protection<\/h3>\n\n\n\n
Your App \u2192 Custom Tab \u2192 App Link \u2192 Your App \u2192 Custom Tab \u2192 ...\n<\/code><\/pre>\n\n\n\n\n
Cross-App Navigation<\/h3>\n\n\n\n
Configuring Custom Tabs for App Links<\/h2>\n\n\n\n
Warm-Up the Custom Tabs Service<\/h3>\n\n\n\n
class MainActivity : AppCompatActivity() {\n private var customTabsClient: CustomTabsClient? = null\n private var customTabsSession: CustomTabsSession? = null\n\n override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n\n \/\/ Warm up Chrome Custom Tabs\n CustomTabsClient.bindCustomTabsService(\n this,\n "com.android.chrome",\n object : CustomTabsServiceConnection() {\n override fun onCustomTabsServiceConnected(\n name: ComponentName,\n client: CustomTabsClient\n ) {\n customTabsClient = client\n client.warmup(0)\n customTabsSession = client.newSession(null)\n }\n\n override fun onServiceDisconnected(name: ComponentName) {\n customTabsClient = null\n customTabsSession = null\n }\n }\n )\n }\n}\n<\/code><\/pre>\n\n\n\nHandling Return Navigation<\/h3>\n\n\n\n
\/\/ For OAuth or payment flows that redirect back to your app\nfun launchAuthFlow(authUrl: String) {\n val customTabsIntent = CustomTabsIntent.Builder()\n .setSession(customTabsSession!!)\n .build()\n\n \/\/ Add FLAG_ACTIVITY_NO_HISTORY so the Custom Tab doesn't stay in the back stack\n customTabsIntent.intent.addFlags(Intent.FLAG_ACTIVITY_NO_HISTORY)\n customTabsIntent.launchUrl(this, Uri.parse(authUrl))\n}\n<\/code><\/pre>\n\n\n\n<!-- In AndroidManifest.xml -->\n<activity\n android:name=".AuthCallbackActivity"\n android:exported="true"\n android:launchMode="singleTask">\n <intent-filter android:autoVerify="true">\n <action android:name="android.intent.action.VIEW" \/>\n <category android:name="android.intent.category.DEFAULT" \/>\n <category android:name="android.intent.category.BROWSABLE" \/>\n <data\n android:scheme="https"\n android:host="yourapp.com"\n android:pathPrefix="\/auth\/callback" \/>\n <\/intent-filter>\n<\/activity>\n<\/code><\/pre>\n\n\n\nCommon Issues and Fixes<\/h2>\n\n\n\n
Issue 1: App Link Doesn't Trigger from Custom Tab<\/h3>\n\n\n\n
\n
adb shell pm get-app-links --user cur <package><\/code><\/li>\n# Check verification status\nadb shell pm get-app-links --user cur com.example.app\n<\/code><\/pre>\n\n\n\nIssue 2: Disambiguation Dialog Appears<\/h3>\n\n\n\n
https:\/\/yourdomain.com\/.well-known\/assetlinks.json<\/code> and your app's SHA-256 fingerprint matches.<\/p>\n\n\n\n[{\n "relation": ["delegate_permission\/common.handle_all_urls"],\n "target": {\n "namespace": "android_app",\n "package_name": "com.example.app",\n "sha256_cert_fingerprints": [\n "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"\n ]\n }\n}]\n<\/code><\/pre>\n\n\n\nIssue 3: Custom Tab Stays Open After App Launch<\/h3>\n\n\n\n
FLAG_ACTIVITY_NO_HISTORY<\/code> when launching the Custom Tab, or call finishAffinity()<\/code> in the Activity that handles the App Link.<\/p>\n\n\n\nIssue 4: Links Don't Work on Non-Chrome Browsers<\/h3>\n\n\n\n
Intent.ACTION_VIEW<\/code> instead of Custom Tabs:<\/p>\n\n\n\n\/\/ Fallback: open in the default browser (supports App Links reliably)\nval intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))\nstartActivity(intent)\n<\/code><\/pre>\n\n\n\nBest Practices<\/h2>\n\n\n\n
\n
Intent.ACTION_VIEW<\/code> instead.<\/p>\n\n\n\nCustomTabsClient.warmup()<\/code> before the user taps a link. This reduces the perceived load time by several hundred milliseconds.<\/p>\n\n\n\n