Skip to content
biticaretdevelopers

Apps

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 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).

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, 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 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).

Only staff members who have the apps permission in the admin receive a session token. In Go, the Go template 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 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.

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.

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).

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).