Runtime & the bridge

The Phone SDK is the same object everywhere, but how it talks to the phone depends on who's running it. Understanding this makes the whole SDK click.

Two execution modes

When you call createHelixPhoneSdk({ appId }), the SDK picks one of two transports automatically:

// No token — the SDK detects it's framed and uses the bridge.
const phone = createHelixPhoneSdk({ appId: "studio.example" });

const phone = createHelixPhoneSdk({ appId: "wallet", accessToken });

The SDK decides with one rule: if it's running inside another window (window.parent !== window) and has no access token, it uses the bridge. Otherwise it calls the API directly. Your app code is identical in both modes — you never branch on it.

The bridge protocol

The bridge is a request/response protocol over postMessage, secured by a per-session helixBridgeNonce (passed to the iframe as a query param). The shape:

// app → shell
window.parent.postMessage({
  source: "helix-phone-app",
  appId, bridgeNonce, requestId,
  method: "notifications.push",   // namespaced SDK method
  params: { title, body },
}, "*");

// shell → app
{
  source: "helix-phone",
  bridgeNonce, requestId,
  ok: true,
  result: { /* … */ },   // or: ok:false, error: "scope_not_granted"
}

Requests time out after 8 seconds. The nonce ensures one app can't impersonate another or read another app's responses. You normally never write this by hand — the SDK does it — but it's why every SDK method maps to a stable method string like media.pickFromAlbum or storage.set.

Bootstrap — one snapshot of everything

On launch, an app reads a bootstrap snapshot that contains the account, installed apps, effective permissions, the launch context, and runtime config:

const runtime = await phone.runtime.bootstrap();
// runtime.account       → the signed-in PhoneAccount
// runtime.apps          → installed app manifests
// runtime.permissions   → { [appId]: PhonePermissionScope[] }
// runtime.launchContext → how this launch happened

Convenience accessors wrap it:

const me = await phone.account.getCurrentUser();          // runtime.account
const ctx = await phone.runtime.launchContext();          // see below
const manifest = await phone.runtime.manifest();          // this app's manifest

Runtime config

The bootstrap's runtime block tells you the environment you're in:

Launch context

How did the app open? Deep link from a notification, the home screen, or a web URL?

type PhoneAppLaunchContext = {
  appId: string;
  url: string;
  path: string;
  source: "web" | "notification" | "shell";
  receivedAt: string;
};

Use it to route — e.g. a notification with a deepLink lands the user on the right screen.

Lifecycle events

The phone is foreground-only: only the active app runs. Subscribe to transitions so you can pause timers, save drafts, or refresh on resume:

const off = phone.lifecycle.on("suspend", () => saveDraft());
phone.lifecycle.on("resume", () => refresh());
phone.lifecycle.on("close", () => flush());

// later
off(); // unsubscribe