App Lifecycle

Mini apps run inside the Alien app’s WebView. The host app needs to coordinate with your mini app to know when it’s ready to be shown. The app:ready signal is at the center of this.

Why app:ready Matters

When a user opens your mini app, the host app shows a loading screen while your app boots up. The host app will not display your mini app until it receives the app:ready signal. This ensures users never see a blank screen, a half-rendered UI, or a flash of unstyled content.

User taps miniapp → Host shows loading screen → Your app loads →
  → app:ready sent → Host reveals your app

If you never send app:ready, the loading screen stays up indefinitely and the user’s only option is to close your app.

Sending app:ready

Automatic (Default)

AlienProvider sends app:ready automatically after mounting and reading launch parameters. This is the default behavior — no extra code needed.

 
function App() {
  return (
    <AlienProvider>
      {/* app:ready fires automatically after mount */}
      <YourApp />
    </AlienProvider>
  );
}

Deferred

If your app needs to load initial data before it’s ready (API calls, asset preloading, etc.), set autoReady={false} and call ready() manually when you’re done.

 
function App() {
  return (
    <AlienProvider autoReady={false}>
      <YourApp />
    </AlienProvider>
  );
}
 
function YourApp() {
  const { ready } = useAlien();
  const [data, setData] = useState(null);
 
  useEffect(() => {
    fetchInitialData().then((result) => {
      setData(result);
      ready(); // Now the host app reveals your mini app
    });
  }, []);
 
  if (!data) return <LoadingSpinner />;
  return <MainContent data={data} />;
}

The ready() function is idempotent — safe to call multiple times. Only the first call sends the signal; subsequent calls are no-ops.

Bridge API

For non-React apps, send app:ready directly via the bridge:

 
// After your app is ready to be displayed
send('app:ready', {});

This is fire-and-forget — no response event. Available since contract version 0.0.9.

Closing the Mini App

Close the mini app programmatically using app:close.

 
send('app:close', {});

This is fire-and-forget — no response event. Available since contract version 1.0.0.

Back Button

The host app provides a native back button. You can show/hide it and respond to clicks.

useBackButton Hook

The useBackButton hook manages visibility, listens for clicks, and handles cleanup automatically. The back button is hidden on unmount.

 
function DetailScreen() {
  const { show, hide, isVisible, supported } = useBackButton(() => {
    navigate(-1);
  });
 
  useEffect(() => {
    show();
    return () => hide();
  }, [show, hide]);
 
  return <div>Detail content</div>;
}

Back Button via Bridge

 
// Show the back button
send('host.back.button:toggle', { visible: true });
 
// Handle clicks
useEvent('host.back.button:clicked', () => {
  navigateBack();
});

Lifecycle Summary

Next Steps

• Clipboard — System clipboard access
• Haptic Feedback — Haptic feedback
• Link Management — Open URLs through the host app
• Payments — Accept payments
• Bridge Reference — Full bridge API reference