Skip to main content

Extension slots

In this page you will learn which slots an app can fill, how to declare them in the manifest, and what an extension frame can and cannot do.

The slots of version 1​

SlotWhereContextHeightScope
product.details.tabA tab of a product page, after the built-in tabsproductId200 to 2000 px, 600 by defaultread_products
organization.overview.cardA card on the organization overview pagenone: the token's org80 to 600 px, 200 by defaultnone

product.details.tab is refused at submission when read_products is not among your scopes, and hidden at runtime if the installation was not granted it.

Declare an extension​

{
"embedded": true,
"app_url": "https://app.example.com/app",
"extensions": [
{ "slot": "product.details.tab", "path": "/app/extensions/product", "label": { "en": "Carbon offsets", "fr": "Compensation" } },
{ "slot": "organization.overview.card", "path": "/app/extensions/overview", "label": { "en": "Offsets this year" } }
]
}

At most 10 extensions, at most 2 per slot, each (slot, path) once. The path follows the rule of navigation paths: under your app_url. Extensions require embedded: true and an app_url.

How a slot is shown​

  • Each extension is its own iframe, with the same sandbox and query parameters as a full page, plus a slot parameter. A small "From <app name>" caption tells the user the content is third party.
  • Cards load when they scroll into view, at most 4 per slot, the rest behind "Show more apps".
  • Each frame talks only to its own app: it has its own session token and its own answers.
  • A change of organization remounts every frame.

What an extension can ask​

A slot frame gets a reduced App Bridge: ready, session-token, context, resize, toast, loading and navigate. There is no confirm and no title.

const app = createApp({ allowedHosts: ['https://acme.example.com'] });
await app.ready();
const { slot, extensionId, productId } = await app.context(); // to render before verifying a token
app.autoResize(); // follows the page height, at most 10 times a second

context is a convenience: the only context you can trust is the slot and ctx claims of the session token, verified on your server. For a product tab, ctx is { "productId": 345 }, and the platform has checked that the product belongs to the token's organization and that the user may see it.

Extension ids​

An extension has a stable id, <handle>.<first 10 hex of sha256(slot + "\n" + path)>. It stays the same across versions while the slot and path do, so a bookmarked product tab keeps working after an update.