About user stitching

This is for:

Developer System Administrator

Coveo User Stitching is a service that keeps track of user identities across their visits. The service can retrieve user identities and stitch their visits in multiple scenarios, such as when the user:

  • Switches from a web browser to another.

  • Switches from a device to another (for example, from a desktop to a smart phone).

  • Performs actions as an anonymous user, and then logs in.

  • In a single browser, uses multiple accounts across different interfaces that are linked to the same Coveo organization.

Coveo User Stitching is used by default by all the services that leverage the user profile, such as the user actions component. The User Stitching service is also used by default by all Coveo Machine Learning (Coveo ML) algorithms to provide consistent context and user-related recommendations.

User stitching mechanism

When a user accesses a Coveo-powered interface, they’re identified by a user ID and a client ID. If the user is authenticated, the user ID is a human readable identification (typically the user’s email). For an anonymous user, the user ID defaults to the client ID.

In certain cases, a single user can have multiple user IDs and client IDs. To keep track of the user across their visits, the User Stitching service gathers all of their user IDs and client IDs in the target Coveo organization into a database. The user’s user IDs and client IDs are then associated to a specific internal ID that represents that single user. In other words, all of a user’s identifiers are linked to a single internal ID.

Every time usage analytics events are sent from a Coveo-powered interface, the Coveo User Stitching service must determine if it needs to generate or update the internal ID linked to the current user ID or client ID.

The following flow chart illustrates the decision process of the User Stitching service.

flow chart

Use case scenarios

In the above flow chart, you can see that the User Stitching service manages a user’s internal ID based on 7 different scenarios.

These scenarios are divided into 2 categories:

Unauthenticated scenarios

When an unauthenticated user accesses a Coveo-powered interface, the user stitching service searches the database for an internal ID linked to the user’s client ID.

Scenario 1

In this scenario, the service found an internal ID linked to the user’s client ID. Therefore, the service returns the user’s internal ID and the user is recognized even if they’re not authenticated.

Scenario 2

In this scenario, the service didn’t find any internal ID linked to the user’s client ID. Therefore, the service generates an internal ID and assigns it to the user’s client ID. The service then returns the new internal ID to identify the user.

An unauthenticated user accesses a Coveo-powered search interface for the first time. Since it’s their first time on the interface, the user’s client ID doesn’t match any of the internal IDs contained in the database.

Therefore, the User Stitching service generates an internal ID and links it to the user’s current client ID. This allows the service to recognize the user in the future.

Authenticated scenarios

When an authenticated user navigates a Coveo-powered interface, the user stitching service searches the database for:

  • An internal ID that matches the user’s user ID.

  • An internal ID that matches the user’s client ID.

Scenario 3

In this scenario, the user is logged in and the service found an internal ID that matches the user’s user ID.

However, the service didn’t find an internal ID that matches the user’s client ID. Therefore, the User Stitching service assigns the retrieved internal ID to the user’s client ID. The service then returns that internal ID to identify the user.

Usually, this scenario occurs when a user cleared their cookies or switched their browsing device while staying logged in.

A user is logged in to a Coveo-powered search interface. During the visit, the user clears their browser cookies, which erases their client ID.

Since the user is logged in, the User Stitching service found an internal ID that matches the user’s user ID in the database.

The service therefore assigns that internal ID to the newly generated client ID so that the service can recognize the user in the future, even if they’re not authenticated.

Scenario 4

In this scenario, the user is logged in and the service found an internal ID that matches both the user’s user ID and client ID. Therefore, the service returns the user’s internal ID to identify the user.

Scenario 5

In this scenario, the user is logged in and the service found two different internal IDs (one for the user ID and another for the client ID).

When this scenario occurs, the User Stitching service returns the internal ID that is linked to the user ID to identify the user, and discards the one linked to the client ID. This allows the service to consistently identify the user in the future.

This scenario can occur for different reasons, such as when a user switches between browsing devices or clears their cookies.

A user logs in to a Coveo-powered search interface with a new device for the first time. When the User Stitching service searches the database to find an internal ID that matches both the user’s user ID and client ID, the service finds two different internal IDs (one associated to the user’s user ID and another for the user’s client ID).

In order to keep a single internal ID to identify the user, the service discards the internal ID linked to the client ID and updates the database entry with the one currently associated to the user ID.

Scenario 6

In this scenario, the user is logged in, but the service didn’t find any internal ID that matches the user’s user ID. However, the User Stitching service found an internal ID that matches the user’s client ID.

Therefore, the service returns the retrieved internal ID to identify the user and assigns that internal ID to the user’s user ID.

This scenario occurs when a user already accessed a Coveo-powered interface, but authenticates for the first time.

An unauthenticated user accesses a Coveo-powered search interface for the first time and performs search actions. After a while, they decide to authenticate to access content they were not able to see as an anonymous user.

Since the user already accessed the search interface, they have been granted a client ID and an associated internal ID.

When the user authenticated, the service searched the database for an internal ID that matches the user’s user ID, but found nothing.

Therefore, the User Stitching service assigned the internal ID that was generated for the client ID to the user’s user ID.

Scenario 7

In this scenario, the user is logged in, but the service didn’t find any internal ID that matches the user’s user ID and the client ID.

Therefore, the User Stitching service generates an internal ID and links it to the user’s user ID and client ID. The service then returns the new internal ID to identify the user.

This scenario occurs when a user accesses and logs in to a Coveo-powered interface for the first time.

Additional considerations

You may want to test the User Stitching service upon implementation. When doing so, keep in mind that the User Stitching service is designed to combine multiple visits that occur on a single device. Therefore, your test sessions may be stitched together, and appear as a single visit.

To avoid this, we recommend that you use the incognito mode of your browser to create a distinct visit when testing the User Stitching service.