From 63977a23e2b639a1a7f478c05cdb2eb5f70cfce6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Berg=C3=A9?= Date: Fri, 3 Jul 2026 14:19:16 +0200 Subject: [PATCH 1/3] Document page and visitor context in webframes Add the site:page:context scope (and the previously undocumented site:visitor:claims) and document that webframes receive state.page ({ id, path, title }) and state.visitor through the postMessage state, in the interactivity guides and the ContentKit component reference. Co-Authored-By: Claude Opus 4.8 --- docs/integrations/configurations.md | 2 ++ docs/integrations/contentkit/interactivity.md | 22 +++++++++++++++++++ .../development/contentkit/reference.md | 2 ++ docs/integrations/guides/interactivity.md | 22 +++++++++++++++++++ 4 files changed, 48 insertions(+) diff --git a/docs/integrations/configurations.md b/docs/integrations/configurations.md index ab07bea72..af1bf30d3 100644 --- a/docs/integrations/configurations.md +++ b/docs/integrations/configurations.md @@ -98,6 +98,8 @@ The scopes your integration has permissions for. - site:script:inject ## Internal scope - see note below - site:script:cookies ## Internal scope - see note below - site:visitor:auth ## Enable workflows related to authenticated access + - site:visitor:claims ## Expose visitor claims to webframes + - site:page:context ## Expose the current page (id, path, title) to webframes - site:adaptive:read ## Read claims available from Adaptive Content - site:adaptive:write ## Write claims avaiable to Adaptive Content # OpenAPI diff --git a/docs/integrations/contentkit/interactivity.md b/docs/integrations/contentkit/interactivity.md index 0dc822b35..578fa319a 100644 --- a/docs/integrations/contentkit/interactivity.md +++ b/docs/integrations/contentkit/interactivity.md @@ -91,6 +91,28 @@ window.addEventListener("message", (event) => { }); ``` +## Page and visitor context + +In addition to the values you bind through the `data` prop, GitBook injects contextual information about the current site into the webframe `state`, as long as your integration requests the matching [scope](../configurations.md#scopes): + +- `state.page` — the current page as `{ id, path, title }`, when the integration has the `site:page:context` scope. +- `state.visitor` — the visitor claims, when the integration has the `site:visitor:claims` scope. + +This context is delivered client-side through the same `message` event as your bound `data`, so requesting it does not change how the integration block is cached: + +```js +window.addEventListener("message", (event) => { + const state = event.data?.state; + if (!state) return; + + // Current page — only present when the integration has the `site:page:context` scope. + if (state.page) { + const { id, path, title } = state.page; + // e.g. build a link to a sibling page from `path` + } +}); +``` + ## Webframes and actions Webframes are powerful elements to integrate in GitBook external applications or complete UI. Passing data to the webframe can be done using the `data` prop. But the webframe also needs to be able to communicate data back to the top component. It can be achieved using the `window.postMessage`: diff --git a/docs/integrations/development/contentkit/reference.md b/docs/integrations/development/contentkit/reference.md index 34fd3f950..3c3fde8dd 100644 --- a/docs/integrations/development/contentkit/reference.md +++ b/docs/integrations/development/contentkit/reference.md @@ -264,6 +264,8 @@ If you need a copy button, only add it when your integration has a supported way | `buttons` | `Array