Link Management in Alien Mini Apps: Open External URLs

Mini apps run inside a WebView, so clicking external links won’t behave as expected by default. The Alien SDK intercepts external link clicks and routes them through the host app, which opens them in the system browser or handles them natively (e.g. mailto:, solana: URIs).

It Works Out of the Box

AlienProvider enables link interception by default. External links (different origin) are caught and sent to the host via link:open; same-origin links keep working for in-app navigation.

<AlienProvider>
  {/* External links are intercepted automatically */}
  <App />
</AlienProvider>

To turn it off, set interceptLinks={false}:

<AlienProvider interceptLinks={false}>
  <App />
</AlienProvider>

The provider always intercepts in external mode — it exposes no openMode prop. To open intercepted links inside the Alien app instead, use useLinkInterceptor (or enableLinkInterceptor) with openMode: 'internal'.

Per-Component Control with useLinkInterceptor

Use useLinkInterceptor when you disabled interceptLinks on the provider and want it on for specific components, or need a different openMode.

 
function App() {
  useLinkInterceptor({ openMode: 'external' });
 
  return (
    <div>
      <a href="https://example.com">Opens in browser</a>
      <a href="https://alien.app/miniapp/other-app">Opens in browser</a>
    </div>
  );
}

With internal mode:

function App() {
  useLinkInterceptor({ openMode: 'internal' });
 
  return (
    <a href="https://alien.app/miniapp/other-app">
      Opens inside Alien app
    </a>
  );
}

Options

Bridge API

enableLinkInterceptor

For non-React apps, use the bridge function directly. Returns a cleanup function.

 
const disable = enableLinkInterceptor({ openMode: 'external' });
 
// Later, to stop intercepting:
disable();

Interception rules:

• Ignores clicks with modifier keys (Ctrl, Meta, Shift, Alt)
• Ignores right-clicks and non-primary button clicks
• Ignores links with a download attribute
• Ignores javascript: and blob: protocols
• Allows same-origin links through for normal navigation
• Intercepts all other external links

link:open

Open a URL programmatically, without relying on link interception.

 
// Open in system browser
send('link:open', { url: 'https://example.com' });
 
// Open a Solana URI
send('link:open', { url: 'solana:...' });
 
// Send an email
send('link:open', { url: 'mailto:hi@example.com' });
 
// Open another mini app inside Alien
send('link:open', {
  url: 'https://alien.app/miniapp/other-app',
  openMode: 'internal',
});

Payload:

{
  url: string;
  openMode?: 'external' | 'internal';
}

This is a fire-and-forget method — no response event.

Version Requirements

The link:open method is available since contract version 0.1.3. Link interception depends on it internally. To gate on host support, use useCallable:

 
const { callable } = useCallable('link:open');

Next Steps

• Clipboard — read and write the system clipboard
• Haptic Feedback — haptic feedback
• Payments — accept payments
• Bridge Reference — full bridge API reference