Apps

An app renders on the page surface (a full route under Apps in the merchant sidebar) or the overlay surface (a floating panel above the current screen).

Page appsCopy Anchor Link

"ui": { "framework": "vite", "runtime": "iframe", "surfaces": ["page"], "entry": "./dist/index.html", "uses_times_tokens": true }

The host passes section in the init payload when the merchant deep links to a sub view. Listen with client.onNavigate().

Overlay appsCopy Anchor Link

Add ui:overlay to your scopes and overlay to surfaces. Keep overlays narrow (at most 420px wide) and close them with client.close().

Good appsCopy Anchor Link

• Load in under two seconds on a 3G connection.
• Call client.ready() as soon as the first view renders.
• Use client.toast() for feedback instead of your own banners.
• Never ask the merchant to sign in again. The bridge already carries their session.