Skip to main content

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​

FeatureWhere it is in the app
Install with the OAuth authorization code flow and PKCEGET /install, GET /oauth/callback
Webhooks: signature v2, a 5-minute replay window, deduplication by event idPOST /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 localhost or *.test are 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
VariableWhat it holds
CLIENT_ID, CLIENT_SECRETYour app's OAuth client, from the partner space (step 3)
APP_ORIGINThe public origin the app is served from, without a path, for example https://app.example.com
PLATFORMSThe 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_SECRET32 characters or more, to sign the OAuth state cookie: openssl rand -base64 32
PORTDefault 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​

  1. Create your publisher, accept the partner agreement, then create the app with a handle. The handle cannot change later.
  2. Create a client secret on the app page. It is shown once: put it in CLIENT_SECRET, and the app's client id in CLIENT_ID.
  3. Create a version, for example 1.0.0, and paste the manifest.
  4. 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/uninstalled and forgets the installation.

Next​