# Run the sample app

> Start from a working app that installs with OAuth, verifies webhooks, and opens an embedded page and two extension slots.

Source: https://developers-staging.foodpilot.tech/get-started/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](https://github.com/Foodpilot/positive-app-template). Use it as a template for your own app, and copy what you need. It installs [@foodpilot/app-bridge](https://www.npmjs.com/package/@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](https://github.com/Foodpilot/positive-app-template) to start your own repository from it, or clone it:

```bash
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

```bash
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](/build/manifest) 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](/launch/listing).

## 4. Run it

```bash
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](/launch/testing) 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

- [Build your first app](/get-started/first-app): the same flow, step by step, without the sample.
- [Verify signatures](/build/webhooks/verify-signatures): the webhook check the sample implements.
- [App Bridge](/build/app-bridge): what the embedded page calls.
