Skip to main content

App Bridge

In this page you will learn how an embedded app is opened, how it learns who is using it, and what it can ask of the platform page around it. The @foodpilot/app-bridge package implements everything below.

An embedded app​

An app whose manifest has embedded: true and an app_url appears in the platform's menu, under Apps. A user of a granted organization opens it, and the platform shows your page in an iframe under its own header. Your navigation entries are the tabs of that page.

The platform loads your app_url (or a navigation path under it) with four query parameters:

ParameterValue
embedded1
platformThe platform name
localefr or en
hostThe origin of the platform's web app, in base64url (UTF-8, no padding)

They are hints only: trust what a verified session token says, never these.

The frame is sandboxed: scripts, forms, popups and same-origin are allowed; top navigation and downloads are not. No token is ever put in the URL.

Secure your pages​

  • Send Content-Security-Policy: frame-ancestors <the platform web app origins> so nobody else can embed your app.
  • Do not rely on third-party cookies, which a browser may block inside an iframe: authenticate each request to your server with a session token.
  • Serve the app from an origin only you control, not a shared hosting domain.

The client​

npm install @foodpilot/app-bridge jose
import { createApp } from '@foodpilot/app-bridge';

const app = createApp({ allowedHosts: ['https://acme.example.com'] }); // exact origins

await app.ready(); // hides the platform's loading skeleton

const token = await app.getSessionToken(); // 60 seconds
await fetch('/api/me', { headers: { Authorization: `Bearer ${token}` } });

app.toast({ message: 'Saved', kind: 'success' });
const ok = await app.confirm({ message: 'Delete the report?', confirmLabel: 'Delete' });
app.navigate.app('/app/reports/2');
app.navigate.foodpilot('/products');
app.title('Reports');
app.loading(true);

createApp refuses to start unless the page is framed and the host parameter names one of the origins you listed. Requests go to that origin only, and replies are accepted only from the parent window.

What the host does​

RequestEffect
readyEnds the loading state. If it does not come within 15 seconds, the user sees "The app did not respond" with a retry
session-tokenReturns a session token for the user, organization and installation. Cached by the host until 10 seconds before it expires
toastA message of at most 200 characters, info, success or error, shown with the app's name
confirmA dialog, titled with the app's name, with a message of at most 500 characters and a label of at most 30. Answers whether the user confirmed
navigateapp: a path under your app_url. foodpilot: only a few areas of the platform, such as /products
titleSets the page title, at most 100 characters
loadingShows or hides a progress bar under the header
resizeIn an extension slot: sets the frame height
contextIn an extension slot: tells the app its slot and context

A request the host would refuse never leaves your page: it rejects at once. Messages are { "fpab": 1, "id", "type", "payload" }, at most 8 KB, and the host answers at most 50 messages per second per app. Another request type gets the error unsupported.

On your server​

Verify the session token with verifySessionToken from @foodpilot/app-bridge/server, against what you recorded at install: the API origin, the web app origin, your client id, the platform, the installation and its organizations. See session tokens.

import { verifySessionToken } from '@foodpilot/app-bridge/server';

const claims = await verifySessionToken(bearer, {
apiOrigin: 'https://api.acme.example.com',
appOrigin: 'https://app.acme.example.com',
clientId: process.env.CLIENT_ID,
platform: 'acme',
installationId: '0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b',
organizationIds: [7, 9, 12], // coveredOrganizationIds of GET /api/app/v1/installation
});

A token lives 60 seconds and may be replayed within it. When one authorizes a change, remember its jti and refuse a second use.