# App proxy, admin page and UI extensions

> App pages on the storefront under /apps/, an embedded app page in the admin (App Bridge and page parts), UI extensions and web pixels.

An app can integrate into four surfaces of a store: on the storefront via an app proxy, inside the admin as an embedded page, inside platform pages via UI extensions, and on the storefront as web pixels listening to visitor events. This page covers each of them.

## Serve storefront pages through the app proxy

Storefront requests under `/apps/<subpath>/…` are proxied to your app's server, allowing the app to serve dynamic pages and data under the store's own domain.

```toml
[app_proxy]
subpath = "downloads"
url = "/proxy"
```

A request to `/apps/downloads/a/b?x=1` is forwarded to `<url>/a/b?x=1` with its HTTP method, path, query string and request body (up to 1 MiB).

### Verify the signed query

The platform appends the following query parameters, overwriting any parameters with the same names sent by the visitor.

| Parameter | Value |
| :--- | :--- |
| `store` | The store's hostname. |
| `store_id` | The store's numeric ID. Use this to look up your store record. |
| `logged_in_customer_id` | The signed-in customer's ID; empty for guest visitors. |
| `path_prefix` | `/apps/<subpath>`. |
| `timestamp` | Unix timestamp in seconds. |
| `signature` | The HMAC signature described below. |

`signature` is the hex-encoded HMAC-SHA256—keyed with your client secret—of the other query parameters: sort them by name, format each as `name=value` (joining repeated parameter values with commas), and concatenate them with no separator. Signing works identically for `GET` and `POST`; the request body is not part of the signature. Reject any `timestamp` older than 5 minutes.

For example, with secret `hush`, the query `extra=1&extra=2&logged_in_customer_id=1000000003042&path_prefix=/apps/loyalty&store=acme.localhost&timestamp=1792317600` is signed over:

```
extra=1,2logged_in_customer_id=1000000003042path_prefix=/apps/loyaltystore=acme.localhosttimestamp=1792317600
```

producing `signature=8c30aea8e44a07efc83114e2d5bab975e9bf9cc23800f848804c7af10eab1cf4`.

In Go, the [Go template](https://github.com/biticaret/app-template-go) already verifies this signature.

### What passes through

- Only these request headers are forwarded to the app: `Accept`, `Accept-Language`, `Content-Type`, `If-Modified-Since`, `If-None-Match`, `Origin`, `User-Agent`, `X-Requested-With`. The platform also adds `x-biticaret-store-id`, `x-biticaret-store-domain`, `x-biticaret-customer-id` (only when a customer is signed in), `x-biticaret-signature` and `X-Forwarded-For`. These headers are for convenience; always treat the signed query as the proof of origin.
- Only these response headers are returned from the app: `Cache-Control`, `Content-Disposition`, `Content-Language`, `Content-Type`, `ETag`, `Expires`, `Last-Modified`, `Location`, `Vary`.
- `Cookie`, `Set-Cookie` and `Authorization` never pass through in either direction.
- The response preserves the app's HTTP status code. Redirects are not followed by the proxy; they are passed directly to the client. Responses to a signed-in customer always carry `Cache-Control: private, no-store`.
- Limits: 10 seconds total request timeout (`504` on timeout), 5 MB max response size (`502` if `Content-Length` exceeds this), and 1 MiB max request body (`413` if exceeded). Apps serving files can request 120 seconds and 256 MiB for `GET` and `HEAD` via `app_proxy.large_responses`; these limits take effect once approved by the platform ([Configuration](configuration.md#biticaret-app-toml)).

### Render inside the theme

A response with `Content-Type: application/liquid` is rendered as Liquid inside the store theme's layout (up to 1 MiB of Liquid source).

## Show a page in the admin

An app with `[admin_embedded]` renders its own UI inside an iframe in the admin.

```toml
[admin_embedded]
entry_url = "/admin"
navigation = [
  { label = "Reviews", path = "/" },
  { label = "Privacy requests", path = "/privacy-requests" },
]
```

`navigation` accepts up to 10 items. When more than one item is defined, they appear as tabs above the iframe.

### The frame

The platform opens `entry_url` with the same signed query used to [open the app](api.md#install-an-app), plus `embedded=1` and `host` (the admin's origin). The signature is valid for 5 minutes. Your response must allow the admin origin to frame it:

```
Content-Security-Policy: frame-ancestors https://admin.biticaret.com.tr
```

### Talk to the admin with App Bridge

Your embedded page communicates with the admin using the platform's client library, `app-bridge.js`. Serve the script from your own origin (the Go template does this automatically):

```html
<script src="/app-bridge.js?v={{.BridgeVersion}}"></script>
```

`hostOrigin` is required: pass the admin origin your backend is configured with (`appsdk.EmbeddedPage` writes it to `document.body.dataset.host`). Never take it from the frame URL's `host` query, which isn't signed. `createApp` throws without it.

The platform does not host `app-bridge.js` at a public URL. Apps not written in Go must serve the file themselves: copy it from the [Go template](https://github.com/biticaret/app-template-go) into your static assets. The `?v=` parameter is purely for cache busting; update it whenever the file changes.

```js
var app = biticaretAppBridge.createApp({ hostOrigin: document.body.dataset.host })

app
  .fetch('/api/hello')
  .then(function (res) {
    if (!res.ok) throw new Error('HTTP ' + res.status)
    return res.json()
  })
```

| Call | What it does |
| :--- | :--- |
| `app.idToken()` | Returns a fresh session token. |
| `app.fetch(…)` | Works like `fetch`, attaches the session token as `Authorization: Bearer`, and retries once on `401`. The token goes only to your page's own origin; to send it to another backend of yours, list that origin in `createApp({ hostOrigin, tokenOrigins: ['https://api.example.com'] })`. Requests anywhere else go out without it. |
| `app.titleBar.set(…)` | Sets the title bar above the frame, primary button, up to three secondary buttons (`secondaryActions`, each `{label, disabled, onAction}`) and back button (`backAction`). |
| `app.toast.show(…)` | Displays a brief toast notification. |
| `app.modal.open(…)` | Opens a confirmation modal. |
| `app.resourcePicker(…)` | Opens the admin's product or collection picker and resolves with the selected IDs. |
| `app.navigate(…)` | Navigates the admin to one of the store's pages (such as `/orders`). |

### Verify the session token

Your browser code authenticates requests to your own backend using the session token. Your backend verifies the token to identify the store and staff member. The token is an HS256-signed JWT valid for 60 seconds, signed with your app's client secret:

| Claim | Value |
| :--- | :--- |
| `iss` | The admin's origin. |
| `dest` | The store's URL. |
| `store_id` | The store's numeric ID. Key your records by this, not `dest`. |
| `aud` | The app's `client_id`. |
| `sub` | The staff member's numeric ID, as a string. |
| `exp`, `nbf`, `iat`, `jti` | Token lifetime and unique ID. |

Checkout UI extensions get a token with the same secret and `aud`, but `iss` is the store's URL (equal to `dest`) and `sub` is the buyer. So always check `iss` against the admin origin from your own configuration, and require `sub`: otherwise any buyer could call your admin API. In Go, `Verifier.VerifyAdminSessionToken` does both (see [Go SDK](go-sdk.md)).

Only staff members who have the apps permission in the admin receive a session token. In Go, the [Go template](https://github.com/biticaret/app-template-go) verifies it out of the box.

### Build the page

Embedded admin pages use the biticaret Design System (`bt-*` components) so they match the admin interface rather than imposing a separate visual style. The [Go template](https://github.com/biticaret/app-template-go) serves the page shell with the design system stylesheets, `app-bridge.js`, a loading state and the content security policy; your page script populates `<main id="app">`.

`app-page.js` exposes common page building blocks as `biticaretAppPage`: `h` (element builder), `show` (mounts the page), `stack`, `row`, `grid`, `card` (titled card), `table` (table inside a card), `empty` (empty state), `list`, `tabs`, `region`, `loading`, `text`, `muted` and `strong`.

```js
var P = biticaretAppPage
var app = biticaretAppBridge.createApp({ hostOrigin: document.body.dataset.host })
var main = document.getElementById('app')

app.fetch('/admin/api/reviews').then(function (res) { return res.json() }).then(function (data) {
  P.show(main, 'Reviews',
    data.reviews.length
      ? P.card({ title: 'Latest reviews' }, P.list(data.reviews.map(function (r) { return r.title })))
      : P.empty({ heading: 'No reviews yet' }))
})
```

How to show an empty list, a page that failed to load and the loading state (`load`, `showError`, `empty` and the 15-second rule) is on [Empty, error and loading states](page-states.md).

The design system loads from `cdn.biticaret.com.tr` at a pinned version with subresource integrity hashes. The page's content security policy lets in only that version's folder (`appsdk.DesignSystemSource`, such as `https://cdn.biticaret.com.tr/design-system/1.7.2/`), not the whole CDN.

**Light and dark mode.** The admin's active light or dark theme propagates automatically: `app-bridge.js` sets it on `<html data-theme>`. Load `app-bridge.js` without `defer` so the page does not flash in the wrong theme before painting.

## Add a UI extension

A UI extension is a small JavaScript module rendered inside a designated slot on one of the platform's own pages. Available slots: [UI extension targets](../reference/ui-extension-targets.md).

```bash
biticaret app generate extension --type ui_extension --name order-card
```

```toml
type = "ui_extension"
handle = "order_card"
name = "Order card"
target = "admin.order.details.sidebar"
module = "order-card.js"

[capabilities]
network_access = true

[[settings.fields]]
key = "backend_url"
type = "single_line_text_field"
name = "App server"
default = "https://APPBASE"
```

The module registers a callback for its target:

```js
biticaret.extension('admin.order.details.sidebar', function (root, api) {
  var orderId = api.data.selected[0].id
  var badge = root.createComponent('Badge', { tone: 'neutral' }, 'No note')
  root.appendChild(badge)
})
```

Constraints and behaviour:

- Extensions cannot output raw HTML; they use only platform components: `Card`, `Stack`, `Text`, `Badge`, `Banner`, `Button`, `TextField`, `Select`, `Checkbox`, `Divider`.
- Code executes inside an isolated Web Worker with no access to cookies, storage or the host DOM.
- Network requests require `capabilities.network_access = true`. Extensions authenticate requests to your own backend using a token from `api.sessionToken()`.
- Each module is at most 64 KB, an app may define at most 25 UI extensions, and each extension may declare up to 20 setting fields (`single_line_text_field`, `multi_line_text_field`, `boolean`, `number_integer`, `number_decimal`). A `single_line_text_field` with a `choices` list renders as a single-choice select.
- Store owners enable or disable each extension, reorder extensions within the same target, and configure their settings under **Ayarlar > Uzantılar** (Settings > Extensions) in the admin. Extensions read these values via `api.settings.current`; omitted or empty fields fall back to their `default` values. If an extension declares a `targets` list, merchants can move it between those targets, and your module must call `biticaret.extension` for each declared target.
- Extensions only render for apps whose installed version is approved.
- A default value of `"https://APPBASE"` is replaced with the origin of `application_url` when the CLI builds the app ([Configuration](configuration.md#biticaret-extension-toml)).

## Add a web pixel

A web pixel is a lightweight JavaScript module that subscribes to storefront visitor events (`type = "web_pixel"`, up to 10 per app). The storefront runs it inside a hidden, sandboxed iframe with no access to cookies, storage or the host page DOM.

```toml
type = "web_pixel"
handle = "events"
name = "Events"
module = "events.js"
consent = "analytics"

[[settings.fields]]
key = "measurement_id"
type = "string"
required = true
```

```js
analytics.subscribe('product_viewed', function (event) {
  browser.sendBeacon('https://app.example.com/events?id=' + init.data.settings.measurement_id, JSON.stringify(event))
})
```

- Standard events: `page_viewed`, `product_viewed`, `collection_viewed`, `search_submitted`, `product_added_to_cart`, `cart_viewed`, `checkout_started`, `checkout_completed`.
- Theme scripts can publish custom events using `window.biticaret.analytics.publish('name', data)`, and pixels subscribe to them by name. Standard event names are reserved and cannot be published by theme scripts.
- A pixel receives events only when the visitor has consented to its `consent` category (`analytics` or `marketing`).
- `init.data` provides store details, the signed-in customer (if any), and the installation's settings under `settings`. `browser` provides `sendBeacon` and `fetch`.
- **Settings.** A pixel can declare up to 20 setting fields (`string` up to 500 characters, or `string_list`; 4 KB total). Values are written by your app rather than the merchant via `GET` and `PUT /api/v1/pixels/{pixelID}/settings` (`write_pixels`). While any required setting is empty, the pixel does not run and appears under **Ayarlar > Müşteri olayları** (Settings > Customer events) in the admin as **Ayarları yapılmamış** (Not configured).
