User Tracking

By default, the kapa widget does not track or store any data besides the questions asked by users and answers provided by the AI model. However, platform admins are often very interested in understanding the following:

• User Engagement: How many unique users interact with the widget?
• User Retention: How often do users come back?
• User Journeys: What do individual users ask over time?
• User Profiles: Who are my power users?

The website widget offers two ways of tracking users that can be used together:

1. Anonymous user tracking with Fingerprint
2. Tracking users yourself

Anonymous user tracking with Fingerprint

The kapa website widget allows you to track users anonymously based on browser fingerprinting. This feature is powered by the commercial version of Fingerprint, which provides a robust method for generating a consistent identifier for users based on their browser and device characteristics. See here for their privacy policy. The kapa platform stores only the hash (the visitor ID) generated by Fingerprint and nothing else.

This feature is enabled by setting data-user-analytics-fingerprint-enabled to "true" in the widget configuration:

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

Once enabled the website widget will submit the unique id generated by Fingerprint alongside the questions to the kapa system. The user profiles immediately become visible under the users tab in the kapa platform. Here are some ways to analyze them

1. Sort them by Question Count count to find your power users.
2. Sort them by First Activity to find users that have used the website widget for the first time.
3. Click on View Conversations to see all conversations of a single user.

Tracking users yourself

In addition using Fingerprint the kapa website widget allows you to provide it with user identifiers yourself. If you have information available on your users on the domains or platforms where the website widget is installed you can give this information to the widget.

To do this you need to assign the information to the global window object on your website, specifically by assigning a user object to the global window.kapaSettings property. The widget will then attach this information to the queries it sends to the kapa system which uses it to build user profiles. It supports the following optional attributes:

window.kapaSettings = {
  user: {
    uniqueClientId: string;
    email: string;
  }
}

• You can set uniqueClientId with a meaningful identifier from your system like a user id. This identifier will not mean anything to the kapa platform it will simply be used to track users anonymously.

• Setting the email attribute has the same effects but it comes with the added benefit of seeing your users emails in the kapa platform. Now you exactly know who is asking which questions.

When should I use this?

1. You are not allowed to use Fingerprint: In this scenario you simply set uniqueClientId yourself to track users anomously in the kapa platform.
2. You want to collect user data in the kapa platform and then later pull it into your own system to analyze it. In this case it makes sense to provide your own uniqueClientId becuase you can then later identify the individual users in your own system.
3. You want to understand who your users are in the kapa platform. In this case it makes sense to set the email.

Why should I also use Fingerprint?

User objects in the kapa system can have multiple identifiers. Setting a uniqueClientId and email while having Fingerprint enabled is perfectly valid. To illustrate the benefit of doing this, think of the following scenario:

1. A first time user discovers the widget on your documentation where you have fingerprinting enabled and asks a question. This creates a new user object in the kapa system and associates it with the question.
2. The same user returns to your help forum and logs in. On your help forum you also have a kapa widget installed and here you are setting the email attribute for logged in users while also fingerprinting them.
3. Once the user asks a question on your help forum kapa can understand that this is an existing user via the fingerprint and instead of creating a new record will simply add the email to the existing user profile.

Docusaurus setup example

This is a minimal example of how you can assign data to the global kapaSettings object within Docusaurus by obtaining the user data from a cookie containing user information on the client.

All you need to do is create a custom JS script in the static folder in your Docusaurus project, e.g. /static/kapa-user-info.js. This script is loaded once when the user visits your docs website.

/* Helper function to extract the cookie value */
function getCookie(name) {
  const nameEquals = name + "=";
  const ca = (document.cookie ?? "").split(";");
  for (let i = 0; i < ca.length; i++) {
    let c = ca[i];
    while (c.charAt(0) === " ") c = c.substring(1, c.length);
    if (c.indexOf(nameEquals) === 0)
      return c.substring(nameEquals.length, c.length);
  }
  return null;
}

// make sure the cookie is available when the script first loads, i.e. when the user first visits the website
const userEmail = getCookie("userEmail"); // assuming the name of your cookie is ”userEmail”
window.kapaSettings = { user: { email: userEmail } };

Finally, add the kapa-user-info.js script to the scripts array in your docusaurus.config.js file:

// docusaurus.config.js
module.exports = {
	...,
	scripts: [
		{
			src: "/kapa-user-info.js",
		},
		...
	]
}

If you use another platform or framework like React.js, the implementation will be similar:

// my-component.tsx in React
import { useEffect } from "react"

const MyComponent = () => {

	useEffect(() => {
		const userEmail = getCookie("userEmail")  // assuming the name of your cookie is ”userEmail”
		window.kapaSettings = {user: {email: userEmail}}
	}, [])

	...
}