Mini App Lifecycle: Handle app:ready and Lifecycle Events

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.

Understanding the Mini App Lifecycle

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.

How to Send app:ready Signal

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