User tracking

Kapa's Website Widget includes user tracking capabilities that help you understand how users interact with the widget. By default, the widget tracks users anonymously via a first-party cookie.

Change in tracking behavior

As of June 25th 2025, Kapa's widget performs anonymous user tracking by default. Tracking unique users provides better analytics and user journey insights.

Local privacy regulations may require you to collect consent before you anonymously identify users. To comply with regulations, you can configure a consent prompt to allow users to opt-out, or explicitly disable anonymous tracking entirely.

Benefits of user tracking

User tracking provides valuable insights:

• User engagement: Measure how many unique users interact with your integration
• 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 assigns an anonymous unique ID to each user. 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

Fingerprint tracking

As an alternative to cookie-based tracking, you can enable browser fingerprinting via FingerprintJS Pro. Fingerprint tracking uses browser and device characteristics to create a unique identifier. Because it does not rely on cookies, fingerprint tracking works across domains and can track users for longer under the same identifier.

When both cookie and fingerprint tracking are enabled, fingerprint takes precedence.

note

Fingerprint tracking is powered by FingerprintJS Pro, which is managed by Kapa. No additional subscription or platform configuration is required on your end. Simply set the data-user-analytics-fingerprint-enabled attribute to "true" to enable it.

Configuration

Attribute	Description	Default
data-user-analytics-cookie-enabled	Enables anonymous user tracking via the kapa_web_id cookie (399-day expiry).	"true"
data-user-analytics-fingerprint-enabled	Enables browser fingerprinting via FingerprintJS Pro. Takes precedence over cookie tracking when both are enabled.	"false"

When both are disabled (data-user-analytics-cookie-enabled="false" and fingerprint not enabled), no user identifiers are sent.

Disabling user tracking

To disable anonymous tracking, set data-user-analytics-cookie-enabled to "false":

<script
  ...
  data-user-analytics-cookie-enabled="false"
></script>

Custom user metadata

In addition to anonymous tracking, you can associate specific user information with conversations by setting window.kapaSettings:

window.kapaSettings = {
  user: {
    uniqueClientId: "user-123",
    email: "user@example.com",
    metadata: {
      company_name: "Acme Corp",
      first_name: "Jane",
      last_name: "Doe",
    }
  }
};

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.

Privacy compliance

For users in regions governed by privacy regulations like GDPR, you must obtain explicit consent before tracking user interactions. The Website Widget provides a built-in consent prompt to help with compliance.

Consent prompt

The Website Widget includes a built-in consent prompt that can be shown before users submit questions. This helps comply with privacy regulations like GDPR.

<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>

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.