Enabling adaptive content
Choose an authentication method to pass user data to GitBook.
To start customizing your documentation experience for your readers, you'll need to enable adaptive content and decide how your visitor data is passed to GitBook. This lets your site's content dynamically adapt based on who's viewing it.
Enable adaptive content
Before you’re able to pass user data to GitBook, you’ll need to configure your site to use adaptive content.
Head to your site’s settings, and enable Adaptive content from your site’s audience settings. Once enabled, you’ll get a generated ‘Visitor token signing key’, which you’ll need in order to continue the adaptive content setup.

Set your visitor schema
After enabling adaptive content, you’ll need to define a schema for the types of claims you expect GitBook to receive when a user visits your site.
The visitor schema should reflect how these claims are structured when sent to GitBook.
For example, if you expect a visitor to potentially be a beta user in your product, you would set a visitor schema similar to:
This will also help you use autocomplete when configuring your claims in the condition editor. Visitor schemas only support the following types:
Read claims being passed in as strings.
GitBook accepts dynamic strings, meaning you can dynamically pass string data — such as a user’s name, developer tokens, and more.
Strings can also contain an optional enum key, which allows you to restrict the data that is received by GitBook to one of its set values.
Read claims being passed in as booleans.
Nest claims in an object to group similar values.
Set an unsigned claim
Unsigned claims are a specific type of claim that identifies claims coming through that might not be signed by a client application. It is required to set claims in your visitor schema as unsigned if you are passing claims through URL parameters, unsigned cookies, and feature flags.
If you intend to work with unsigned claims, you will need to declare the claims you are expecting in the schema under an “unsigned” prop alongside your signed claims.
Use visitor claims with the Content API
Use the Content API when your server needs published content evaluated for a specific visitor.
Define visitor claims in your schema, then sign the visitor JSON Web Token (JWT) with the Visitor token signing key in audience settings. Only claims declared in the schema can drive your adaptive content conditions.
Your trusted server exchanges the signed visitor JWT and target published URL for a short-lived content API token. Use the returned Bearer token to search content, list pages, and retrieve pages in that visitor's context.
Before implementing the flow, understand how retrieval behaves:
A single-page request with
evaluated=trueresolves conditional blocks and inline expressions for the visitor. Without it, the API returns raw authored content.Search results and page lists omit content the visitor cannot view. A direct request for an ineligible page returns
404.If the visitor JWT signature is invalid, GitBook evaluates content as an anonymous visitor. GitBook doesn't trust the supplied claims.
Pass visitor data to GitBook
GitBook provides different ways to pass visitor data to adapt your site's content. After defining your schema, you’ll need to decide how you want to pass your visitor data to GitBook.
Last updated
Was this helpful?