Handle Domains

Control how links behave in your app: keep them in the main webview (internal) or open them in an in-app browser (external).

How domain handling works

When a user taps a link, the app decides where to open it based on the domain:

• Internal domains load in the main webview — the user stays on your page.
• External domains open in an in-app browser — a browser view that appears on top of your app. The user can close it to return to your page.

By default, only the domain your app starts on is treated as internal. All other domains open in the in-app browser.

Add an internal domain

Internal domains load inside the app's webview:

await startiapp.App.addInternalDomain("partner-site.com");

Add external domains

External domains are specified as RegExp patterns and open in the in-app browser:

await startiapp.App.addExternalDomains(/maps\.google\.com/, /youtube\.com/);

Remove domains

// Remove a specific internal domain
await startiapp.App.removeInternalDomain("partner-site.com");

// Remove external domain patterns
await startiapp.App.removeExternalDomains(/maps\.google\.com/);

List configured domains

const internal = await startiapp.App.getInternalDomains();
const external = await startiapp.App.getExternalDomains();

Handle all domains internally

This is especially useful for flows you don't fully control — for example, payment flows where the user is redirected through several third-party domains before returning to your site. Rather than adding each domain individually, you can treat everything as internal and only exclude specific domains that should open externally.

// Treat all domains as internal
await startiapp.App.handleAllDomainsInternally();

// But force specific ones to open externally
await startiapp.App.addExternalDomains(/maps\.google\.com/);

When you no longer need all domains to be internal, call restoreDefaultDomainHandling() to go back to the default behavior:

await startiapp.App.restoreDefaultDomainHandling();

Open a URL in the device's browser

If you need to open a URL in the device's actual browser (Safari, Chrome) — completely outside the app — use openExternalBrowser(). This is different from external domains, which open in the in-app browser.

await startiapp.App.openExternalBrowser("https://maps.google.com/?q=Copenhagen");

See also