> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/guides/integration/open-external-url.md). # Open External URL ## What is Open External URL? Open External URL lets you control how web links open in your app. You can display them inside a temporary in-app browser window - keeping users within your app - or hand them off to the device's default browser when the external context is needed. * **In-App Browser** - opens the URL in a temporary browser window inside your app. The user can close it and return to your app with a single tap. Best for web pages, articles, or Terms of Service. * **System Browser** - opens the URL in the device's default browser (Safari on iOS, Chrome on Android). Best for file downloads or external services that require the user's saved passwords or browser history. ## Prerequisites {% hint style="success" %} This feature is available in all plans. [See all plans](/getting-started/subscription-plans.md) {% endhint %} ## Implementation Choose your integration method below: **Bubble.io Plugin** (No-Code), **JavaScript SDK** (Code), or **AI Agents** (for AI-powered editors like Lovable, Base44, and Replit). ### Initialization {% tabs %} {% tab title="Bubble.io Plugin" %} **Check Plugin** Before starting, verify if the Natively plugin is already installed in your Bubble project. 1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar. 2. **Check Installed Plugins:** Look through your list of installed plugins for "Natively iOS & Android app builder". * If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

* If it is NOT installed: Click the + Add plugins button, search for "Natively", and click Install.

{% endtab %} {% tab title="JavaScript SDK" %} **Check SDK** Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase. 1. Open your project's main HTML file (or header settings) and look for the Natively script tag inside the `` section. 2. Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., `@2.26.0`). ```javascript ``` {% hint style="info" %} To ensure you are using the most up-to-date version, check the [Natively GitHub releases page](https://github.com/buildnatively/js-sdk/releases) for the latest version number. {% endhint %} {% endtab %} {% tab title="AI Agents" %} **Initialize the SDK** AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Before implementing any feature, the Natively SDK must be initialized in your project. Copy the line below and paste it into your AI agent to check and set up the Natively SDK in your project. ``` Check if the following Natively SDK script is present in the of index.html. If missing or outdated, add it: For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases ``` {% endtab %} {% endtabs %} ### Setup Logic {% tabs %} {% tab title="Bubble.io Plugin" %} #### \[Action] Natively - Open external url * **URL** - the web URL to open. * **Open in external browser** - Yes/No: * **Yes** - opens in the system browser. * **No** - opens in the in-app browser.

{% endtab %} {% tab title="JavaScript SDK" %} ```javascript // ============================================================================ // NATIVELY OPEN EXTERNAL URL - DOCUMENTATION & EXAMPLES // ============================================================================ // No initialization required — openExternalURL is available directly // on the global window.natively object. // ============================================================================ // ALL AVAILABLE METHODS // ============================================================================ // window.natively.openExternalURL(url, external) // - Opens a web URL either in the in-app browser or the system browser. // - url: string — the web URL to open. Must start with https:// // - external: boolean — true = system browser, false = in-app browser // --- Open External URL. In-App Browser Example. Start --- window.natively.openExternalURL("https://example.com/", false); // --- Open External URL. In-App Browser Example. End --- // --- Open External URL. System Browser Example. Start --- window.natively.openExternalURL("https://example.com/", true); // --- Open External URL. System Browser Example. End --- ``` {% endtab %} {% tab title="AI Agents" %} AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Copy the line below and paste it into your AI agent.

[Your feature description] using the Natively Open External URL SDK: // window.natively.openExternalURL(url, external) — opens a web URL. url: string — must start with https://. external: boolean — true opens in system browser, false opens in in-app browser. For reference: https://docs.buildnatively.com/guides/integration/open-external-url

{% hint style="warning" %} Replace the placeholder at the beginning with a description of what you want to build - for example: "Open the Terms of Service page in the in-app browser when the user taps the link". {% endhint %} {% endtab %} {% endtabs %} ### How to use #### Internal URLs - keep specific domains in your app's main view If you want a specific domain to always open directly inside your app's main WebView - without any browser UI or close button - add it to your [**Internal URLs**](/natively-platform/settings.md#internal-urls) whitelist in the Natively Dashboard [Settings](/natively-platform/settings.md). This is useful when your app spans multiple subdomains or when you use a third-party service that must stay within your app context. #### Default behavior for unwhitelisted domains Any link your app navigates to on a domain not in your [Internal URLs](/natively-platform/settings.md#internal-urls) whitelist will automatically open in the in-app browser - even without calling `openExternalURL`. Use `openExternalURL` with `external: true` when you specifically need the system browser for one of those links. #### Use the in-app browser for content Open articles, Terms of Service, Help Center pages, or any web content the user should read and then return from. The in-app browser shows a close button, so users can always get back to your app with a single tap. #### Use the system browser for downloads and external services File downloads and external services that rely on saved passwords or browser history should always use `external: true`. These require the full system browser context to work correctly. ## Troubleshooting

URL opens in the wrong browser

Check the `external` parameter - `true` forces the system browser, `false` forces the in-app browser. Both values override the [Internal URLs](/natively-platform/settings.md#internal-urls) whitelist. If you're not using `openExternalURL` and the URL is opening unexpectedly, check your Internal URLs whitelist in the Natively Dashboard [Settings](/natively-platform/settings.md).

URL opens inside the app instead of the in-app browser

If you're not calling `openExternalURL`, the domain may be whitelisted in [Internal URLs](/natively-platform/settings.md#internal-urls), causing it to open in the app's primary WebView. Either remove it from the whitelist, or explicitly call `openExternalURL(url, false)` to force the in-app browser.

In-app browser not showing close button or navigation bar

The domain is likely whitelisted in [Internal URLs](/natively-platform/settings.md#internal-urls) and opens in the app's primary WebView instead. Either remove it from the whitelist or explicitly call `openExternalURL(url, false)` to force the in-app browser.

Not working in a web browser

This is a native feature and will not work in a standard web browser. Test on a real device using a Natively build or the Preview app.

[^1]: Replace this placeholder