Bridge API

Reference for the MicroAppBridge — the communication channel between your Agent App and the host.

Overview

The Bridge API (MicroAppBridge) is the interface that the host app exposes to every Agent App. It provides navigation, UI feedback, permissions, storage, and system capabilities.

Access it via props (bridge), the useMicroApp() hook, or the useBridge() shortcut hook. See SDK Reference for all available hooks.

Note: The SDK uses the internal name MicroApp for Agent Apps. In code, you'll see types like MicroAppBridge, MicroAppProps, etc. These refer to Agent App concepts.

Methods

`navigateBack()`

Navigate back to the previous screen in the host app.

bridge.navigateBack();

`navigateToApp(slug: string)`

Navigate to another Agent App by its slug.

bridge.navigateToApp("note"); // Opens AssistMe Note

`showToast(message: string, type?: "success" | "error" | "info")`

Show a native toast notification.

bridge.showToast("Saved successfully!", "success");
bridge.showToast("Something went wrong", "error");
bridge.showToast("Tip: swipe to delete", "info");

Platform behavior:

Android: Uses ToastAndroid.SHORT
iOS: Shows an Alert dialog with an OK button

`requestPermission(permission: MicroAppPermission): Promise<boolean>`

Request a device permission from the user. Returns true if granted, false if denied.

const granted = await bridge.requestPermission("camera");
if (granted) {
  // Access camera
}

The host shows a native alert dialog: "{appSlug}" wants to access: {permission}.

Permissions granted in the current session are cached — subsequent requests return true immediately
If the user doesn't respond within 60 seconds, the request is automatically denied
Available permissions: camera, location, notifications, contacts, storage, microphone, haptics, biometrics

`getHostContext(): MicroAppHostContext`

Get the current host context (user info, auth tokens, Supabase config).

const ctx = bridge.getHostContext();
console.log(ctx.userId);
console.log(ctx.colorScheme); // "light" or "dark"

Returns:

{
  userId: string;
  accessToken: string;
  refreshToken: string;
  expiresAt: number;        // Unix timestamp (seconds)
  supabaseUrl: string;
  supabaseAnonKey: string;
  hostVersion: string;
  colorScheme: "light" | "dark";
}

`setTitle(title: string)`

Set the title displayed in the host's navigation bar.

bridge.setTitle("Settings");

`haptics(type?: "light" | "medium" | "heavy")`

Trigger haptic feedback on the device.

bridge.haptics();          // Light (default)
bridge.haptics("medium");
bridge.haptics("heavy");

`openUrl(url: string): Promise<void>`

Open a URL in the system browser.

await bridge.openUrl("https://example.com");

Uses Linking.canOpenURL() to verify the URL is valid before opening.

`setStorageItem(key: string, value: string): Promise<void>`

Store a key-value pair in the app's sandboxed storage.

await bridge.setStorageItem("theme", "dark");
await bridge.setStorageItem("last-query", "weather in Tokyo");

Storage keys are automatically namespaced as agentapp_{slug}_{key} to prevent conflicts between apps. Data is stored securely via expo-secure-store.

`getStorageItem(key: string): Promise<string | null>`

Retrieve a value from sandboxed storage. Returns null if the key doesn't exist.

const theme = await bridge.getStorageItem("theme");
if (theme === "dark") {
  // Apply dark theme
}

`log(message: string): void`

Log a message to the host console (useful for debugging).

bridge.log("User tapped the submit button");