Base
Review the basic configuration settings for our widgets.
The base configuration provides core settings for all Inkeep widgets. These settings control authentication, branding, theming, and general behavior.
Basic Configuration
Configuration Options
Core Settings
Essential configuration options for authentication, branding, and basic widget setup. These settings form the foundation of your Inkeep integration.
Each setting serves a specific purpose in customizing the widget behavior:
Option | Type | Required | Description |
---|---|---|---|
env | 'production' | 'development' | No | Environment setting (defaults to 'production') |
apiKey | string | Yes | Your Inkeep API key |
organizationDisplayName | string | No | Display name for your organization |
primaryBrandColor | string | Yes | Primary brand color (hex code) |
aiApiBaseUrl | string | No | Custom base URL for API endpoints |
analyticsApiBaseUrl | string | No | Custom base URL for analytics endpoints |
shadowHost | HTMLElement | null | No | Reference to shadow DOM host element |
rootElement | HTMLElement | null | No | Reference to root mounting element |
shouldBypassCaptcha | boolean | No | Bypass captcha challenge (server-side API only) |
tags | string[] | No | Custom tags for widget identification |
prism | Prism | No | Instance of Prism for syntax highlighting. You can add support for additional languages by importing them from prismjs and passing in the Prism instance |
User Properties
Configure user-specific information for personalization, tracking, and authentication. This allows you to identify users and provide personalized experiences.
Property | Type | Required | Description |
---|---|---|---|
userProperties | UserProperties | No | User identification and metadata |
userAuthToken | string | No | Authentication token for the user |
Privacy Preferences
Control analytics and cookie preferences for tracking user interactions with the widget.
Property | Type | Required | Description |
---|---|---|---|
privacyPreferences | PrivacyPreferences | No | Privacy preferences configuration |
Event Handling
Configure callbacks for tracking and processing widget events. This allows you to integrate with your own analytics or monitoring systems.
Property | Type | Required | Description |
---|---|---|---|
onEvent | (event: InkeepCallbackEvent) => void | No | Event processing callback function |
You can see the Analytics guide for more information.
Color Mode
Synchronize the widget's appearance with your application's theme. This enables seamless dark/light mode integration.
Property | Type | Required | Description |
---|---|---|---|
colorMode | ColorMode | No | Theme synchronization configuration |
Theme Customization
Configure advanced styling and branding options for the widget. This includes colors, styles, and custom CSS.
Property | Type | Required | Description |
---|---|---|---|
theme | UserTheme | No | Theme customization settings |
You can see the Theme Customization guide for more information.
Custom Icons
Configure custom icons for various widget elements. You can use built-in icons from popular icon libraries or provide custom SVG URLs.
Property | Type | Required | Description |
---|---|---|---|
customIcons | CustomIconMap | No | Custom icon configurations |
You can see the Custom Icons guide for more information.
URL Parameters
Configure URL parameters that will be automatically appended to all links within the widget. This is useful for tracking and maintaining context across page navigations.
Property | Type | Required | Description |
---|---|---|---|
urlQueryParamsToAppend | object | No | URL parameters to append to links |
Source Transformation
Configure how source information is displayed in the widget by transforming the raw source data before it's rendered. This allows you to customize titles, URLs, descriptions, and other metadata for search results and chat references.
Type Signature
Examples
The transformSource
function allows you to modify how source information appears in different contexts:
Parameter | Type | Description |
---|---|---|
source | SourceItem | The original source data containing title, URL, description, etc. |
type | 'chatSourceItem' | 'searchResultItem' | 'intelligentFormSource' | Context where the source is being displayed |
opts | { organizationDisplayName?: string; tabs?: (string | SearchTab)[] } | Additional options including organization name and configured tabs |
The function should return a TransformedSource
object that defines how the source should be displayed. This gives you control over:
- Title and description formatting
- URL modifications and parameters
- Breadcrumb trails
- Tab categorization
- Icons and visual elements
- Link behavior (new tab vs same window)
- Additional metadata and tags
Common use cases include:
- Adding organization branding to titles
- Truncating long descriptions
- Categorizing content into tabs
- Adding tracking parameters to URLs
- Customizing navigation behavior
- Setting context-specific icons
Custom Filters
Configure how we filter the search and chat
Supported Operators
Comparison Operators: $eq
, $ne
, $gt
, $gte
, $lt
, $lte
Array Operators: $in
, $nin
Boolean Operators: $exists
Logical Operators: $and
, $or
Filter by custom tags and attributes
A common filter scenario is you have docs that covers many products, versions, and SDKs.
The first part to setting up filters is to add <meta>
tags prefixed with inkeep:
to each page. For example:
Then to filter the search and chat with your custom tags version
and sdk
:
Filters can be dynamically generated based on the page the user is on, giving full control over the search and chat experience.