Testing Your Mini App in the Alien Developer Environment

This guide covers how to test your mini app during development, from local browser testing to full integration testing in the Alien app.

Local Development Setup

During development, you can run your mini app in a regular browser. The SDK operates in development mode when the bridge is unavailable — i.e. window.__miniAppsBridge__ is not injected. (Launch params are a separate signal, marked by the host’s auth token, and can be present or absent independently.)

bun run dev
# or: npm run dev

What works in the browser:

• UI rendering and styling
• Application logic and state management
• API calls to your backend
• Navigation and routing

What doesn’t work:

• Bridge communication with the host app
• Native features (payments, clipboard, link opening, haptic feedback)

The React hooks degrade gracefully in the browser — they never throw, report callable: false, and route failures to their error state. The raw strict bridge calls (send/request) are stricter: they throw BridgeUnavailableError when no bridge is present. Guard them with isBridgeAvailable()/callability(), or use the .ifAvailable variants.

 
// Check if running in Alien app
if (isBridgeAvailable()) {
  send('app:ready', {}); // safe — bridge is present
} else {
  // Dev mode — strict send/request would throw here;
  // use send.ifAvailable() or rely on the React hooks
}

Mock Bridge

For testing bridge interactions without the Alien app, use createMockBridge. It injects a simulated bridge and launch params into window globals, allowing all bridge methods to work.

import { createMockBridge } from '@alien-id/miniapps-bridge/mock';
 
const mock = createMockBridge({
  launchParams: {
    authToken: 'test-token',
    contractVersion: '1.5.0', // omit to default to LATEST_VERSION
    platform: 'ios',
  },
  handlers: {
    'payment:request': (payload) => ({
      status: 'paid',
      txHash: 'mock-tx-123',
      reqId: payload.reqId,
    }),
  },
  delay: 100,
});
 
// Later: clean up
mock.cleanup();

The mock bridge provides default responses for all request-response methods (payment:request, clipboard:read, wallet methods). Set a handler to false to suppress the response entirely.

See Bridge Reference — Mock Bridge for full documentation.

Testing Your Mini App in the Alien App

To test the full integration with native features, launch your mini app inside the Alien app.

Steps

1. Deploy your app to a publicly accessible URL
2. Go to your mini app dashboard in the Developer Portal 
3. Copy the deeplink for your mini app
4. Open the deeplink on your device — your mini app launches in the Alien app

Launch Parameters

When the Alien app loads your mini app, it provides launch parameters. Use the useLaunchParams hook to access them:

 
function App() {
  const launchParams = useLaunchParams();
 
  if (!launchParams) {
    return <div>Running outside Alien App</div>;
  }
 
  return <div>Platform: {launchParams.platform}</div>;
}

Available parameters:

Deeplink Testing

Share deeplinks to launch your mini app directly:

https://alien.app/miniapp/{slug}

With a custom start parameter:

https://alien.app/miniapp/{slug}?startParam={value}

This link opens the mini app inside the installed Alien App; it does not resolve to a mini-app page in a desktop browser.

The startParam value is available via useLaunchParams(). Use this for:

• Referral tracking
• Deep navigation to specific content
• Campaign attribution
• Pre-filling form data

Example:

https://alien.app/miniapp/my-game?startParam=level-5

 
function Game() {
  const launchParams = useLaunchParams();
 
  useEffect(() => {
    if (launchParams?.startParam === 'level-5') {
      navigateToLevel(5);
    }
  }, [launchParams?.startParam]);
 
  // ...
}

Debugging Common Integration Issues

Check Bridge Availability

 
function DebugInfo() {
  const { isBridgeAvailable } = useAlien();
 
  if (isBridgeAvailable) {
    console.log('Running in Alien app');
  } else {
    console.log('Running in browser (dev mode)');
  }
 
  // ...
}

Log Launch Parameters

 
function DebugInfo() {
  const launchParams = useLaunchParams();
 
  console.log('Launch params:', {
    authToken: launchParams?.authToken ? 'present' : 'missing',
    contractVersion: launchParams?.contractVersion,
    hostVersion: launchParams?.hostAppVersion,
    platform: launchParams?.platform,
    startParam: launchParams?.startParam,
    displayMode: launchParams?.displayMode,
  });
 
  // ...
}

Remote Debugging

iOS: Use Safari Web Inspector to debug the WebView.

1. Enable “Web Inspector” in Safari settings on your device
2. Connect your device to your Mac
3. Open Safari > Develop > [Your Device] > [Your App]

Android: Use Chrome DevTools.

1. Enable USB debugging on your device
2. Connect your device to your computer
3. Open chrome://inspect in Chrome
4. Select your WebView under “Remote Target”

Common Issues

Next Steps

• Authentication — Implement user authentication
• Payments — Accept payments with webhook verification
• React SDK — Full hooks reference