Apps
App Bridge reference
Everything the bridge does, and the messages under it.
App Bridge connects your iframe and the desktop with postMessage. Both sides check the other's origin and window before reading a message, so another page can't talk to your app or impersonate the desktop.
createAppBridge(shellOrigin: string, on?: {
theme?: (theme: Theme) => void; // appearance, accent, locale…
navigate?: (path: string) => void; // the desktop asks your app to show a page
}): AppBridgeshellOrigin is always https://ostorya.com.
Methods#
| Method | What it does |
|---|---|
graphql(query, variables?) | Admin GraphQL call with the app's token; resolves to data, throws on errors. |
adminFetch(path, init?) | fetch() to another Admin route on the desktop origin, with the token header. |
shop() | { name, handle } of the current shop, once the first token arrived (else null). |
setTitle(title) | Title shown in the menu bar: "WhatsApp — Conversations". |
setLocation(path) | Your current path + query; the desktop reopens it after a refresh. |
notify(message, badge?) | Success toast; badge sets the number on your dock icon. |
notifyError(message) | Error toast. |
openApp(handle, path?) | Opens another app from the dock, for example openApp("store"). The path argument is reserved: today the app opens on its last page. |
embedded | true inside the desktop. Outside it, token requests fail. |
destroy() | Removes the listeners (single-page apps that unmount the bridge). |
Theme#
type Theme = {
appearance: "light" | "dark";
reduceGlass: boolean; // the merchant turned off transparency: use solid cards
accent: string; // hex color from the merchant's wallpaper or choice
locale?: string; // interface language, e.g. "fr", "ar" (right to left)
};The theme arrives when your app starts and again whenever the merchant changes wallpaper, accent, dark mode or language.
Shortcuts#
While your app has focus, ⌘K / Ctrl+K opens the desktop's search. The bridge forwards it; don't bind it yourself.
Messages (protocol)#
The bridge is a thin layer over these messages. If you can't use the script, send and receive them yourself, always withhttps://ostorya.com as target origin and checking event.origin and event.source === window.parent.
| Direction | Message |
|---|---|
| app → desktop | { type: "omni:ready" } |
| app → desktop | { type: "omni:token:request" } |
| app → desktop | { type: "omni:title", title } |
| app → desktop | { type: "omni:location", path } |
| app → desktop | { type: "omni:notify", message, badge?, tone?: "success" | "error" } |
| app → desktop | { type: "omni:open-app", app, path? } |
| app → desktop | { type: "omni:spotlight" } |
| desktop → app | { type: "omni:token", token, expiresIn, apiUrl, shop: { name, handle } } |
| desktop → app | { type: "omni:token:error", error } |
| desktop → app | { type: "omni:theme", theme } |
| desktop → app | { type: "omni:navigate", path } |
The script is built from the same source as the Store's own bridge: v1.mjs · v1.js. v1 only gets backward-compatible changes.