User tracking

Kapa's website widget includes user tracking capabilities that help you understand user engagement and improve your implementation. The widget does not perform user tracking by default, but you can enable it to gain additional insights about how users interact with your AI assistant.

Change in tracking behavior

As of June 25th 2025, Kapa's widget will use opt-out tracking by default, rather than the current opt-in approach. This means anonymous user tracking is enabled automatically unless explicitly disabled. This change helps provide better analytics and user journey insights while still maintaining privacy compliance options. Review the configuration options below to ensure your implementation aligns with your privacy requirements.

Benefits of user tracking

User tracking provides valuable insights:

• User engagement: Measure how many unique users interact with the widget
• User retention: Analyze how often users return to ask questions
• User journeys: Understand what individual users ask over time
• User profiles: Identify power users and their common questions

Anonymous user tracking

When enabled, Kapa's website widget assigns an anonymous unique ID to each user who asks questions. This ID is stored in a first-party cookie named kapa_web_id. Since this is a first-party cookie:

• It's restricted to your domain only
• It's automatically included with requests to your own domain but not sent to any external sites
• It enables consistent user identification across different subdomains of your website
• It helps track user journeys without collecting personally identifiable information

The anonymous ID contains no personally identifiable information but allows the Kapa platform to provide meaningful analytics by:

• Providing aggregate metrics about unique users
• Tracking user retention rates
• Enabling conversation analysis by individual users

Privacy compliance

For users in regions governed by privacy regulations like GDPR, you must obtain explicit consent before tracking user interactions. Kapa provides options to manage compliance, including consent prompts and conditional tracking.

Configuration

Disabling user tracking

On June 23rd 2025, Kapa's widget will enable user tracking by default. To disable the automatic user tracking completely, set the data-user-analytics-cookie-enabled parameter to "false".

<script
  async
  src="https://widget.kapa.ai/kapa-widget.bundle.js"
  data-website-id="XXX-XXX-XXX"
  data-user-analytics-cookie-enabled="false"
></script>

Adding a consent prompt

To help with compliance requirements, configure a consent prompt before users submit questions:

<script
  async
  src="https://widget.kapa.ai/kapa-widget.bundle.js"
  data-website-id="XXX-XXX-XXX"
  data-consent-required="true"
  data-user-analytics-cookie-enabled="true"
  data-consent-screen-title="Help us improve our AI assistant"
  data-consent-screen-disclaimer="By clicking 'Allow tracking', you consent to anonymous user tracking which helps us improve our service. We don't collect any personally identifiable information."
  data-consent-screen-accept-button-text="Allow tracking"
  data-consent-screen-reject-button-text="No, thanks"
></script>

Conditional tracking based on user consent

For integration with your existing Consent Management Platform (CMP):

// Function to load Kapa widget with configurable tracking
function loadKapaWidget(enableTracking = false) {
  // Remove existing widget if present
  const existingWidget = document.getElementById("kapa-widget-script");
  if (existingWidget) existingWidget.remove();

  // Create and configure new widget script
  const script = document.createElement("script");
  script.id = "kapa-widget-script";
  script.async = true;
  script.src = "https://widget.kapa.ai/kapa-widget.bundle.js";
  script.setAttribute("data-website-id", "XXX-XXX-XXX");
  script.setAttribute("data-user-analytics-cookie-enabled", enableTracking.toString());

  // Add to document
  document.body.appendChild(script);
}

// Initial load with tracking disabled
loadKapaWidget(false);

// When user grants consent through your consent system
function onUserConsentGranted() {
  loadKapaWidget(true);
}

// Hook this function into your existing consent system
// yourConsentSystem.onAccept(onUserConsentGranted);

Custom user metadata

In addition to anonymous tracking, you can associate specific user information with conversations when available:

window.kapaSettings = {
  user: {
    uniqueClientId: string;
    email: string;
    metadata: {
      company_name: string;
      first_name: string;
      last_name: string;
    }
  }
}

When collecting custom user metadata like emails or unique IDs, ensure you have appropriate consent mechanisms in place, especially in regions with privacy regulations.

Connecting user identities across platforms

After setting up custom user metadata, you can take advantage of Kapa's ability to maintain consistent user profiles across different touchpoints.

Users in Kapa can have multiple identifiers (anonymous IDs, custom IDs, and email addresses), which creates several advantages:

• Track the same user across documentation, help forums, and other platforms
• Start with anonymous tracking and enrich user profiles as they identify themselves
• Access a user's full interaction history regardless of where they started

Example scenario:

1. A new user discovers your documentation and asks a question anonymously (tracked via cookie)
2. The same user later logs into your help forum where you've set the email attribute
3. Kapa recognizes the user through their anonymous ID and associates both interactions with a single user profile
4. All future interactions, whether anonymous or identified, contribute to the same user profile

This identity resolution helps provide continuity in user support and more accurate analytics.

Viewing user analytics

Team members and administrators with access to the project on the Kapa platform can analyze user activity and conversation data:

• Users dashboard: Navigate to Users in the left sidebar to view all tracked users, their activity metrics, and conversation history
• User filtering: Search for specific users by ID or email, or filter to show only users with email addresses
• Conversation analysis: Click "View conversations" for any user to see their complete interaction history
• User context in conversations: When reviewing conversations, user IDs are displayed in the details panel, allowing you to see which user submitted a question

You can also use the Export feature, available on both the Users and Conversations screens, to export conversation or user data as CSV for processing in external systems.

Recommended implementation

For most widget deployments, consider:

1. Enable anonymous tracking for basic analytics
2. Implement a consent mechanism appropriate for your user base
3. Add custom user metadata when available (after obtaining consent)
4. Clearly communicate your tracking practices in your privacy policy

This approach balances valuable insights with privacy compliance requirements.