Mini App Lifecycle: Handle app:ready and Lifecycle Events

Mini apps run inside the Alien app’s WebView. The host coordinates with your mini app to know when it’s ready to be shown, when to close it, and how the native back button behaves. The app:ready signal is at the center of this.

Understanding the Mini App Lifecycle

When a user opens your mini app, the host shows a loading screen while your app boots. The host will not display your mini app until it receives app:ready — so 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. No extra code needed.

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

Deferred

If your app must load initial data first (API calls, asset preloading), set autoReady={false} and call ready() yourself 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 reveals your mini app
    });
  }, []);
 
  if (!data) return <LoadingSpinner />;
  return <MainContent data={data} />;
}

ready() is idempotent — only the first call sends the signal; later calls are no-ops.

Back Button

The host provides a native back button you can show, hide, and respond to.

useBackButton Hook

useBackButton manages visibility, listens for clicks, and handles cleanup — the button is hidden on unmount.

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

Closing the Mini App

useClose Hook

useClose returns a close function that asks the host to dismiss your mini app, plus a callable flag.

 
function ExitButton() {
  const { close, callable } = useClose();
 
  if (!callable) return null;
 
  return <button onClick={close}>Close</button>;
}

Bridge API

For non-React apps, drive the lifecycle directly through the bridge.

 
// Signal ready (after your app is painted)
send('app:ready', {});
 
// Close the mini app
send('app:close', {});
 
// Show the back button
send('host.back.button:toggle', { visible: true });
 
// Handle back button clicks
on('host.back.button:clicked', () => {
  navigateBack();
});

These are all fire-and-forget — no response events.

Lifecycle Summary

Next Steps

• Safe Area Insets — handle notches and home indicators
• Clipboard — system clipboard access
• Haptic Feedback — haptic feedback
• Bridge Reference — full bridge API reference