URL Handling API
Decide which links open inside your Android app, in Chrome Custom Tabs, or in the external browser.
To improve user experience, it's often beneficial to customize how your app handles different types of web links. For example, social media buttons can be configured to open in the system browser or respective app, rather than within your app. WebViewGold provides flexible settings to customize URL handling for your WebView-based Android app:
Types of Links:
- External Links: Links that lead to a different domain from your app's primary domain.
- Example: If your app's domain is mydomain.com, an external link would be google.com.
- Internal Links: Links that stay within the same domain as your app.
- Example: If your app's domain is mydomain.com, an internal link would be mydomain.com/purchase.
- Special Links: Links that include special attributes, such as target="_blank" or links ending with #.
Link Handling Options:
You can configure link behavior by modifying settings in the Config.java file as shown below.
External Link Handling:
- Default Option (0): To open external links in the main WebView (the same as internal links), set
EXTERNAL_LINK_HANDLING_OPTIONSto0. - Option 1: To open external links in a new in-app tab, set
EXTERNAL_LINK_HANDLING_OPTIONSto1. - Option 2: To open external links in the device's default system browser (e.g. Chrome, Safari), set
EXTERNAL_LINK_HANDLING_OPTIONSto2.
Special Link Handling:
- Option 0: To open special links in the app's main WebView, set
SPECIAL_LINK_HANDLING_OPTIONSto0. - Option 1: To open special links in a new in-app tab, set
SPECIAL_LINK_HANDLING_OPTIONSto1. - Option 2: To open special links in the device's default system browser (e.g. Chrome, Safari), set
SPECIAL_LINK_HANDLING_OPTIONSto2.
Note: This setting with override EXTERNAL_LINK_HANDLING_OPTIONS for links that are both external and special.
Customizing Link Access: Whitelist and Blacklist
To create exceptions for specific sites or pages, open Config.java and add the domain to one of the following arrays:
- BROWSER_WHITELIST: Lists specific domains to open within the app's WebView.
- BROWSER_BLACKLIST: Lists specific domains to open in the external browser.
For detailed guidance on link configuration for your Android app, watch the video tutorial provided below:
URL Handling – Using the In-App Browser for Specific Links
Some links, like a Terms and Conditions page, may not be significant enough to open in an external system browser yet too specific for your app's primary WebView. WebViewGold provides a creative solution for handling these links: an in-app browser tab that opens over the main WebView, providing a hybrid app and browser experience. Here's what it will look like:
Key Features of the In-App Browser Tab:
- The in-app browser tab includes an address bar and navigation buttons, offering a more browser-like experience than the primary WebView.
- Ideal for content that requires easy navigation, such as tutorials, knowledge bases, or pages with specific information.
How to Use the In-App Browser Tab in Your WebView-Based Android App:
To open a link in the in-app browser tab, format the URL in your HTML as follows:
<a href='#' onClick="top.location.href='https://www.example.com';">Open Example Page</a>
Example: To open Google, use:
<a href='#' onClick="top.location.href='https://www.google.com';">Open Google</a>
Testing Link Behavior:
To see how your app will handle different types of links, use the following URL as the WebView URL during testing:
Test Link: https://www.webviewgold.com/demo/testlinks.php
Note: You can also open the same domain in your desktop browser to view the source code and copy the format for your links.
SDK-style implementation notes
Treat this feature as a native capability exposed to your web layer: keep your production website or PWA as the source of truth, then use the documented WebViewGold configuration flags, URL commands, and JavaScript bridge calls to opt in to native Android behavior only where it adds value. This approach keeps your codebase maintainable because the same web application can serve browsers, WebViewGold for Android, and the other WebViewGold platforms with minimal conditional logic.
For reliable results, prefer HTTPS endpoints, stable route names, explicit success/error states in your UI, and small JavaScript helper functions that wrap native calls. For example, a web app built with jQuery Mobile, Lovable, Base44, Bolt, WordPress, Bubble, a custom React/Vue/Angular stack, or static HTML can expose a single button or event handler that triggers the native WebViewGold API while still showing a graceful browser fallback.
- Recommended integration pattern: detect the app context, call the WebViewGold API, then update your web UI after the native callback or route change.
- Testing checklist: validate the feature on a real device or packaged build, verify permissions and store review text, and confirm that browser-only users still receive a useful fallback.
- SEO benefit: keep feature pages, route titles, and structured content indexable on your website while WebViewGold delivers the native app shell for Android users.