In-Product Contextual Help API

Why contextual help matters

Users lose flow when they leave an application to search documentation. Context-switching between a product screen and a docs portal creates friction, increases time-to-resolution, and reduces feature adoption. Embedding relevant help content directly inside Optimizely products keeps users in their workflow while providing the guidance they need.

The In-Product Contextual Help system provides three integration methods — iframe embedding, a JavaScript SDK, and a REST content API — so product teams and partners can surface portal content wherever users need it.

Cross-Product Integration

CMSOpti ID

Integration methods overview

Method	Best for	Complexity	Customization
Iframe embed	Quick integration, sidebar panels	Low	Theming via query params
JavaScript SDK	Rich interactions, tooltips, overlays	Medium	Full DOM control
Content API	Custom UIs, mobile apps, chatbots	High	Complete flexibility

---

Iframe embed

The simplest integration. Embed a portal page in an iframe with optional theme and layout parameters.

Base URL format

https://certification.optimizely.com/embed/{content-path}

Query parameters

Parameter	Type	Default	Description
theme	light | dark | auto	auto	Color scheme. auto reads prefers-color-scheme.
chrome	full | minimal | none	minimal	Controls header/nav visibility. none shows content only.
toc	boolean	true	Show or hide the table of contents sidebar.
search	boolean	true	Enable the embedded search bar.
product	string	none	Pre-filter content to a specific product context.
locale	string	en	Content locale (ISO 639-1).
callback_url	string	none	URL the “Open in docs” link navigates to.

Example: sidebar help panel

<iframe
  src="https://certification.optimizely.com/embed/guides/content-management/create-a-content-type?theme=dark&chrome=none&toc=false"
  width="400"
  height="100%"
  frameborder="0"
  title="Contextual help: Create a content type"
  allow="clipboard-write"
></iframe>

Security headers

The embed endpoint sets these headers:

Content-Security-Policy: frame-ancestors 'self' *.optimizely.com
X-Frame-Options: ALLOW-FROM https://*.optimizely.com

To allow embedding on custom domains, configure allowed origins in the portal admin under Settings > Embed Origins.

---

JavaScript SDK

The SDK provides programmatic control over help content rendering, including tooltips, slide-out panels, and modal overlays.

Installation

npm install @optimizely/docs-contextual-help

Or load from CDN:

<script src="https://certification.optimizely.com/sdk/contextual-help.min.js"></script>

Initialization

import { OptiDocsHelp } from '@optimizely/docs-contextual-help';

const help = new OptiDocsHelp({
  // Required
  apiKey: 'your-portal-api-key',

  // Optional
  theme: 'auto',            // 'light' | 'dark' | 'auto'
  position: 'right',        // 'left' | 'right' | 'bottom'
  width: '400px',           // Panel width
  zIndex: 10000,            // Stacking order
  locale: 'en',             // Content locale
  product: 'cms-saas',      // Product context filter
  onReady: () => {},         // Fires when SDK is loaded
  onError: (err) => {},      // Error handler
  onNavigate: (path) => {},  // Fires when user navigates within help
});

API methods

help.open(contentPath, options?)

Opens the help panel with the specified content.

help.open('/guides/content-management/create-a-content-type', {
  anchor: '#property-configuration',  // Scroll to a section
  highlight: true,                     // Highlight the target section
});

help.close()

Closes the help panel.

help.close();

help.toggle(contentPath)

Toggles the help panel open or closed.

document.getElementById('help-btn').addEventListener('click', () => {
  help.toggle('/concepts/content-management/content-modeling');
});

help.search(query, options?)

Opens the help panel with search results.

help.search('content type properties', {
  product: 'cms-saas',
  limit: 10,
});

help.tooltip(element, contentPath, options?)

Attaches a help tooltip to a DOM element. The tooltip appears on hover or focus.

help.tooltip(
  document.getElementById('content-type-label'),
  '/reference/apis/content-type-attributes',
  {
    trigger: 'hover',    // 'hover' | 'click' | 'focus'
    placement: 'bottom', // 'top' | 'bottom' | 'left' | 'right'
    maxWidth: '300px',
    excerpt: true,       // Show only the first paragraph
  }
);

help.destroy()

Removes all SDK elements and event listeners. Call this on unmount in single-page applications.

// React useEffect cleanup
useEffect(() => {
  const help = new OptiDocsHelp({ apiKey: 'key' });
  return () => help.destroy();
}, []);

Events

help.on('open', ({ path }) => {
  analytics.track('help_opened', { path });
});

help.on('close', () => {
  analytics.track('help_closed');
});

help.on('navigate', ({ from, to }) => {
  analytics.track('help_navigate', { from, to });
});

help.on('search', ({ query, resultCount }) => {
  analytics.track('help_search', { query, resultCount });
});

---

Content API

The REST API returns structured content for custom rendering.

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer {api-key}

Obtain API keys from the portal admin under Settings > API Keys.

Endpoints

GET /api/v1/content/{path}

Returns a single content page.

Response:

{
  "path": "/guides/content-management/create-a-content-type",
  "title": "Create a Content Type",
  "description": "Step-by-step guide to creating content types in Optimizely CMS.",
  "type": "guide",
  "domain": "content-management",
  "products": ["cms-paas", "cms-saas"],
  "difficulty": "beginner",
  "body_html": "<h2>Why content types matter</h2><p>...</p>",
  "body_markdown": "## Why content types matter\n\n...",
  "headings": [
    { "depth": 2, "text": "Why content types matter", "slug": "why-content-types-matter" }
  ],
  "last_reviewed": "2026-03-24",
  "estimated_time": "15 minutes"
}

Query parameters:

Parameter	Type	Description
format	html | markdown | plaintext	Body format (default: html)
excerpt	boolean	Return only the first section (default: false)
headings_only	boolean	Return metadata and headings, no body (default: false)

GET /api/v1/search

Searches content across the portal.

Query parameters:

Parameter	Type	Description
q	string	Search query (required)
product	string	Filter by product slug
type	string	Filter by content type
domain	string	Filter by domain
limit	number	Results per page (default: 10, max: 50)
offset	number	Pagination offset

Response:

{
  "query": "content type",
  "total": 23,
  "results": [
    {
      "path": "/guides/content-management/create-a-content-type",
      "title": "Create a Content Type",
      "excerpt": "Learn how to define page types and block types...",
      "score": 0.95,
      "type": "guide",
      "products": ["cms-paas", "cms-saas"]
    }
  ]
}

GET /api/v1/related/{path}

Returns content related to the specified page.

Query parameters:

Parameter	Type	Description
limit	number	Maximum results (default: 5)
types	string	Comma-separated content types to include

---

Configuration options

Theming

Custom themes override default portal styles in the embed context.

const help = new OptiDocsHelp({
  apiKey: 'key',
  theme: {
    mode: 'dark',
    colors: {
      primary: '#5332f5',
      background: '#1a1a2e',
      surface: '#222244',
      text: '#e0e0e0',
      link: '#7c6ef5',
      border: '#333366',
    },
    fonts: {
      body: 'Inter, system-ui, sans-serif',
      code: 'JetBrains Mono, monospace',
    },
    borderRadius: '8px',
  },
});

Deep-linking

Deep-link to specific sections within content using the anchor parameter:

https://certification.optimizely.com/embed/guides/content-management/create-a-content-type#property-configuration

Programmatically via the SDK:

help.open('/guides/content-management/create-a-content-type', {
  anchor: '#property-configuration',
});

Product context

Set a product context to filter navigation and related content to the active product:

const help = new OptiDocsHelp({
  apiKey: 'key',
  product: 'cms-saas',  // Only show CMS SaaS-relevant content
});

Valid product slugs: cms-saas, cms-paas, experimentation-web, experimentation-feature, odp, cmp, personalization, graph, opal, opti-id, analytics, commerce-connect, commerce-classic.

---

Rate limits

Plan	Requests per minute	Concurrent connections
Free	60	5
Standard	600	50
Enterprise	6,000	500

Rate-limited responses return HTTP 429 with a Retry-After header.

---

Related resources

• Opti ID and Optimizely One — Identity layer that powers authenticated help content
• Opti ID Integration Spec — SSO and SCIM configuration for the help system
• Content Standards — How portal content is structured