Embed your app with IframeView

Hand it to an agent

This prompt briefs an AI coding agent to implement the entire recipe against the live docs — authentication, every endpoint, and webhooks.

Build the Ewity App UI endpoint for <your app> in iframe mode.

1) Implement GET {app_ui_url}: verify X-Ewity-Signature (t=<ts>,v1=<hex hmac_sha256(secret, "{t}.{raw_body}")>, constant-time compare, reject |now-t| > 300s, raw_body = "" for GETs) and decode the X-Ewity-Context JWT (HS256, same signing secret; trust its company/install/user claims). Respond 200 with exactly: { "version": 1, "components": [{ "type": "IframeView", "url": "<your embed URL with a short-lived session token for this merchant>", "height": 900 }] }.
2) Build the /embed page it points at: authenticate from the session token in the URL (the iframe receives no Ewity headers), fluid width, explicit height, no top-navigation attempts (the sandbox blocks them), no referrer assumptions.
3) Style it to sit naturally inside Ewity POS: neutral background, system-ui type ~13–15px, generous spacing, one accent color for actions, loading + empty states. No nav bars, footers, or marketing chrome — this UI will be reviewed by the Ewity team before the app can list.

…or follow the build, step by step

1. 1

   Choose iframe deliberately

   Iframe = your stack + an Ewity design review. The App UI API = native look with zero frontend work.

   • Pick IframeView when you have a substantial existing web UI (dashboards, charts, flows) that would be costly to re-express as App UI components.
   • Expect a review: before your app is approved for listing, the Ewity team checks that the embedded UI feels at home in the POS — spacing, typography, and no jarring branding takeovers.
   • You can mix modes: serve native components on the main page and open your hosted page in one tab (a tab whose content is a single IframeView).
2. 2

   Serve the IframeView document

   Your App UI endpoint returns one component pointing at your hosted page.

   • GET{app_ui_url}?page=homeReturn the IframeView document

   • Respond with `{ version: 1, components: [{ type: "IframeView", url: "https://yourapp.example.com/embed?store=…", height: 900 }] }` — url must be https (≤1024 chars), height 200–4000px.
   • Verify `X-Ewity-Signature` and read the trusted merchant context from the `X-Ewity-Context` JWT on this request, then mint your own session for the embed URL (e.g. a short-lived token in the query string) — the iframe itself does not receive Ewity headers.
3. 3

   Live inside the sandbox

   The embed runs with a strict sandbox — design for it.

   • The iframe cannot navigate the top window (no redirecting the POS), and the referrer is not sent — deep-link state must ride your embed URL.
   • Your page keeps its own origin: cookies, storage and fetch to your APIs all work normally.
   • Size for the window: fluid width, explicit height via the IframeView `height` key; avoid inner scrollbars where you can.
4. 4

   Match Ewity's conventions (the review checklist)

   The embed should read as part of Ewity, not a foreign site.

   • Neutral ground, generous whitespace, system-ui typography at ~13–15px, restrained color — accent for actions only.
   • No top navigation bars, mega-footers, cookie banners or sign-up upsells inside the embed; the merchant is already authenticated via your signed context.
   • Loading states for anything slower than ~300ms, and empty states with a next step — the same bar Ewity holds its own screens to.