Customization guides

Add your own analytics

Use our callback function to log events from the search and chat widgets to your own analytics tool.

Scenario

To understand how usage of the Inkeep search or chat affects your business, you may want to log events from the search and chat widgets to your own analytics tool. This could be Mixpanel, Posthog, Amplitude, Segment or other analytics or CDP tools.

We expose all the events that we log to our own analytics suite through a callback function called onEvent that can be configured in the baseSettings configuration.

Below is an example of how to use onEvent to log events related to the assistant_message_received event to your analytics tool. You can check out the full reference of events by inspecting the InkeepCallbackEvent type in the npm package.

We recommend you only log the events and properties on the events that you find relevant.

Implementation Examples

Basic Implementation

import { type InkeepCallbackEvent } from "@inkeep/cxkit-types";
 
const baseSettings = {
  onEvent: (event: InkeepCallbackEvent) => {
    // Check if the event type is 'assistant_message_received'
    if (event.eventName === "assistant_message_received") {
      const { message } = event.properties;
 
      // Log to your own analytics tool or CDP.
      console.log("Response: ", message.content);
    }
  },
};

Advanced Implementation with Event Filtering

const baseSettings = {
  onEvent: (event: InkeepCallbackEvent) => {
    const { eventName, properties, userProperties } = event;
 
    // Only track specific events
    const eventsToTrack = [
      "assistant_message_received",
      "user_message_submitted",
      "search_query_submitted",
    ];
 
    if (!eventsToTrack.includes(eventName)) {
      return;
    }
 
    // Add custom properties
    const enrichedProperties = {
      ...properties,
      environment: process.env.NODE_ENV,
      timestamp: new Date().toISOString(),
      // Add user context if available
      ...(userProperties?.id && { userId: userProperties.id }),
      ...(userProperties?.teamId && { teamId: userProperties.teamId }),
    };
 
    // Track with your analytics tool
    analytics.track(eventName, enrichedProperties);
  },
};

Implementation with Multiple Analytics Tools

const baseSettings = {
  onEvent: (event: InkeepCallbackEvent) => {
    const { eventName, properties } = event;
 
    // Track with Segment
    segment.track(eventName, properties);
 
    // Track with Mixpanel
    mixpanel.track(eventName, properties);
  },
};

Common Properties

Every event includes a set of common properties that provide context about the widget and the interaction. These properties are automatically included in the properties object of every event:

PropertyTypeDescription
widgetLibraryVersionstringThe version of the Inkeep widget library being used
componentTypestringThe type of widget interaction. Possible values: 'ChatButton', 'CustomTrigger', 'SearchBar', 'EmbeddedChat', 'EmbeddedSearch', 'EmbeddedSearchAndChat', 'IntelligentForm'
tagsstring[]Custom tags passed in the baseSettings. These can be used to categorize or filter events

Example with Tags

const baseSettings = {
  tags: ["production", "docs-site"], // These tags will be included in all events
  onEvent: (event: InkeepCallbackEvent) => {
    const { eventName, properties } = event;
 
    console.log(properties.tags); // ['production', 'docs-site']
    console.log(properties.widgetLibraryVersion); // e.g., '1.2.3'
    console.log(properties.componentType); // e.g., 'EmbeddedChat'
 
    analytics.track(eventName, properties);
  },
};

User Properties

User properties are exactly what you pass to the userProperties in baseSettings. These properties can be used to associate events with specific users or teams.

const baseSettings = {
  userProperties: {
    id: "user-123",
    teamId: "team-456",
    role: "admin",
    // Any other custom user properties
  },
  onEvent: (event: InkeepCallbackEvent) => {
    const { eventName, properties, userProperties } = event;
    analytics.track(eventName, {
      ...properties,
      user: userProperties,
    });
  },
};

Configuration Options

Privacy Preferences

These settings are used to configure the analytics tracking for the widget; passed in the baseSettings configuration.

OptionTypeDefaultDescription
optOutAnalyticalCookiesbooleanfalseOpt out of analytical cookies
optOutAllAnalyticsbooleanfalseOpt out of all analytics tracking
optOutFunctionalCookiesbooleanfalseOpt out of functional cookies

Events Reference

Chat Events

Event NameDescriptionProperties
assistant_message_receivedAssistant response receivedconversation
user_message_submittedUser message submittedconversation
shared_chat_loadedShared chat loadedconversation
assistant_positive_feedback_submittedPositive feedback givenconversation, reasons
assistant_negative_feedback_submittedNegative feedback givenconversation, reasons
get_help_option_clickedHelp option selectedgetHelpOption, conversation
chat_clear_button_clickedChat clearedconversation
chat_share_button_clickedShare button clickedsharedChatUrl, sharedConversationId, originalConversationId, conversation
assistant_message_copiedMessage copiedconversation
assistant_code_block_copiedCode block copiedconversation, language, code
assistant_source_item_clickedSource item clickedconversation, link
assistant_message_inline_link_openedMessage link openedtitle, url

Search Events

Event NameDescriptionProperties
search_result_clickedResult clickedsearchQuery, title, url
search_query_submittedQuery submittedsearchQuery
search_query_response_receivedSearch results receivedsearchQuery, totalResults

Intelligent Form Events

Event NameDescriptionProperties
intelligent_form_submittedForm submittedconversation, values
intelligent_form_primary_section_submittedPrimary section submittedconversation
intelligent_form_ai_response_providedAI response providedconversation, recordsConsidered