Run the sample app
In this page you will run the sample app, register it, and follow it through install, use and uninstall. Its code is the reference implementation of everything the guides describe: copy what you need.
What it shows
| Feature | Where it is in the app |
|---|---|
| Install with the OAuth authorization code flow and PKCE | GET /install, GET /oauth/callback |
| Webhooks: signature v2, a 5-minute replay window, deduplication by event id | POST /webhooks |
| An embedded page that learns who is there from a session token, and uses toasts, confirm, navigation, title and loading through App Bridge | /app/* |
| A product tab and an organization overview card | /app/extensions/product, /app/extensions/overview |
| Billing: plans, a subscription, its cancellation | /api/billing/* |
It is a Node.js and TypeScript server (Express), with the pages built by Vite. It keeps its state in a JSON file.
It is public, under the MIT license: Foodpilot/positive-app-template. Use it as a template for your own app, and copy what you need. It installs @foodpilot/app-bridge from npm.
Before you start
- Node.js 22.22 or later.
- A host name with HTTPS that the platform can reach. The manifest's URLs must be public HTTPS addresses: local names such as
localhostor*.testare refused when you submit a version. - An account in the partner space, linked at the top of every page of this site.
1. Get it and configure it
On GitHub, click Use this template on positive-app-template to start your own repository from it, or clone it:
git clone https://github.com/Foodpilot/positive-app-template.git my-app
cd my-app
npm install
cp .env.example .env
| Variable | What it holds |
|---|---|
CLIENT_ID, CLIENT_SECRET | Your app's OAuth client, from the partner space (step 3) |
APP_ORIGIN | The public origin the app is served from, without a path, for example https://app.example.com |
PLATFORMS | The platforms the app trusts, as JSON: {"<platform>": {"apiOrigin": "https://{tenant}-api.example.com", "appOrigin": "https://{tenant}.example.com"}}. apiOrigin is where tokens and the session-token keys come from; appOrigin is the web app that frames your pages. At least one |
COOKIE_SECRET | 32 characters or more, to sign the OAuth state cookie: openssl rand -base64 32 |
PORT | Default 3000 |
The embedded pages answer with Content-Security-Policy: frame-ancestors set to the appOrigin of every platform in PLATFORMS: only those may frame them.
2. Generate the manifest
npm run manifest > manifest.json
The manifest asks for read_products and read_organizations, declares two navigation entries, both extension slots, and three webhooks: app/uninstalled, app_subscription/updated and app_charge/updated. The manifest guide explains each field.
3. Register it in the partner space
- Create your publisher, accept the partner agreement, then create the app with a handle. The handle cannot change later.
- Create a client secret on the app page. It is shown once: put it in
CLIENT_SECRET, and the app's client id inCLIENT_ID. - Create a version, for example
1.0.0, and paste the manifest. - Complete the listing in French and in English and upload a logo: a version cannot be submitted without them. See Your listing.
4. Run it
npm run dev
Serve it behind your HTTPS host on APP_ORIGIN. GET /healthz answers when it is up.
5. Install it on your test platform
An app can be installed only once a version is approved, including a private one. Set the visibility to private, name your test platform, and submit the version: Test your app explains why and what to expect.
Once the version is released, an administrator of the test platform installs the app from the platform's marketplace, chooses the organizations, and consents. The app receives the code, exchanges it, and stores the installation.
6. Use it, then uninstall it
- Open it from the platform's Apps menu: the page shows the user and the organization from the session token.
- Open a product: the Sample facts tab is the product slot.
- Uninstall it from Installed apps: the app receives
app/uninstalledand forgets the installation.
Next
- Build your first app: the same flow, step by step, without the sample.
- Verify signatures: the webhook check the sample implements.
- App Bridge: what the embedded page calls.