> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/publish/adaptive-content/faq-and-troubleshooting.md).

# FAQ and troubleshooting

### Which authentication method should I use for adaptive content?

It depends on how you want to control access:

* Public and private content on one site — use [signed cookies](/docs/publish/adaptive-content/enabling-adaptive-content/cookies.md)
* Simple personalization without authentication — use [URL parameters](/docs/publish/adaptive-content/enabling-adaptive-content/url.md)
* An entirely private site — use an [authenticated access integration](/docs/publish/adaptive-content/enabling-adaptive-content/authenticated-access.md)
* Already using feature flags — use a [feature flag provider](/docs/publish/adaptive-content/enabling-adaptive-content/feature-flags.md)

### Can I publish a partially public site with some authenticated content?

Yes. You can keep a public site with some authenticated sections, without requiring login for the entire site:

1. Keep your site audience as Public, Unlisted, or Share link.
2. Enable adaptive content in your site’s settings.
3. Use [signed cookies](/docs/publish/adaptive-content/enabling-adaptive-content/cookies.md#signed-cookie) to pass visitor claims after they log in to your main application.
4. Set conditions on the specific pages or sections that should only show for authenticated visitors.

### How do I set up adaptive content with a custom OIDC provider?

Adaptive content works with any identity provider:

1. Set up the generic OIDC integration in GitBook.
2. Configure your OIDC provider to include custom claims in tokens.
3. Map those claims in your GitBook visitor schema.

Common issues: make sure your provider includes the custom claims in the token (not just standard OIDC claims), check whether claims are nested under provider-specific properties, and verify the token format. Different providers structure custom claims differently — check your provider’s documentation.

### Why aren’t my segments working or showing in preview?

* Confirm your visitor schema is correctly defined.
* Verify that your segment JSON matches the schema structure.
* Ensure the condition applies to the section, page, or block you’re testing.
* Use the preview feature from the correct page, and refresh the preview after schema changes.

See [Testing with segments](/docs/publish/adaptive-content/testing-with-segments.md) for the full testing flow.

### Does restricted content appear in search results?

No. Search results only reflect the content a visitor has access to. Any section, page, or block behind adaptive content is only indexed and visible in search for visitors who meet the conditions to view it.

### Do JWT claim schemas support free-form strings?

Not yet. Claim schemas currently only support enums for string values, so define all required string values within an enum.

### Can adaptive content work with arrays in JWT claims?

No. A claim provides a single value — a string (enum) or a boolean. If you need multiple values, transform them on the claims-provider side (for example, in Azure or Okta).

### How do I debug adaptive content conditions?

* Property names are case-sensitive (`role` ≠ `Role`).
* Check data types — boolean `true` is not the string `"true"`.
* Check the property path in nested conditions.
* Inspect the claims attached to a token at [jwt.io](https://www.jwt.io/) to confirm your expected claims are being passed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/publish/adaptive-content/faq-and-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.