Understanding User Stitching

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 (e.g., 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 visitor 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 visitor ID.

In certain cases, a single user can have multiple user IDs and visitor IDs. To keep track of the user across their visits, the User Stitching service gathers all of their user IDs and visitor IDs in the target Coveo organization into a database. The user’s user IDs and visitor 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 visitor ID.

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

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:

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 visitor ID.

Scenario 1

In this scenario, the service found an internal ID linked to the user’s visitor 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 visitor ID. Therefore, the service generates an internal ID and assigns it to the user’s visitor 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 visitor 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 visitor ID. This allows the service to recognize the user in the future.

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 visitor 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 visitor ID. Therefore, the User Stitching service assigns the retrieved internal ID to the user’s visitor 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 visitor 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 visitor 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 visitor 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 visitor 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 visitor 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 visitor ID, the service finds two different internal IDs (one associated to the user’s user ID and another for the user’s visitor ID).

In order to keep a single internal ID to identify the user, the service discards the internal ID linked to the visitor 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 visitor 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 visitor 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 visitor 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 visitor ID.

Therefore, the User Stitching service generates an internal ID and links it to the user’s user ID and visitor 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.

Recommended Articles