Skip to main content

Cross-device experimentation

Kameleoon allows you to merge the browsing history and actions of the same user across different devices. This means that if a user visits your website multiple times using different devices, Kameleoon can accurately report the number of visits, and not just the number of devices used to visit. Enabling this feature in Kameleoon is straightforward, as long as you have a reliable way to identify users. (Typically, through a standard customer login.)

Using cross-device history reconciliation has three significant advantages:

  1. It gives you a coherent targeting system that considers all visits and actions across all of the visitor's devices.
  2. It ensures that a visitor always sees the same variation for a given experiment, regardless of the device they are using.
  3. It provides an accurate reporting system where unique visitors are correctly counted.

Activating cross-device history reconciliation

To use cross-device history reconciliation, you must create a new Kameleoon custom data entry and activate the Use this custom data as a unique identifier for cross-device matching option. When activated, Kameleoon treats this custom data as a unique identifier for your visitors, which will be used to map several Kameleoon visits to a unique user. You also need to set the custom data value with a unique identifier, such as a user ID, using one of the acquisition methods (Activation API or Kameleoon SDK).


If the option is inactive for your custom data, it indicates that you may already have an active custom data set up as a unique identifier. This is because you can only have one custom data of this type per project.


Incorrect configuration can impact cross-device history reconciliation and other Kameleoon operations, such as targeting and bucketing. It's important to avoid assigning a constant value, such as 0, to all visitors, as Kameleoon will interpret them as identical unique visitors.

Cross-device history reconciliation for targeting

Kameleoon automatically downloads a list of visits from other devices and stores this information in the current device's storage when a new session begins and custom data is set with a value. However, if the custom data is empty, reconciliation won't be performed at the start of the session. Reconciliation is triggered only when the custom data is passed, and targeting is re-evaluated for all active experiments and personalizations. Typically, this occurs when a user logs in to your site and provides their user ID, email, or other unique identifier.

It's important to note that once the custom data is provided, Kameleoon can retrieve it for all subsequent visits on the same device, even if the user has not yet logged in. Reconciliation occurs at the start of each subsequent visit, ensuring consistent tracking and targeting capabilities.


To maintain a coherent unified data history for a visitor, it's recommended to provide the custom data value as early as possible during their journey on your website. Kameleoon cannot retrieve this history until the custom data is set up.

Data affected by cross-device history reconciliation

The history reconciliation feature adds the list of all previous visits that are not yet known to the current device. This includes typical information such as

  • Number of visits and page views
  • Session duration
  • Acquisition channels and referrers
  • Custom data (note: custom data provided in other sessions with a visitor scope will be merged into the current session).

You can use normal targeting segments as usual, and they will function as expected. For example, a targeting condition based on the number of previous visits will accurately consider all visits, as will a condition based on the duration of the previous visit


A maximum of 25 visits can be available for cross-device reconciliation, with a 3-month retention policy applying to the retrievable data.

Cross-device history reconciliation for variation allocation consistency

The goal of cross-device history reconciliation for variation allocation is to ensure that visitors assigned to an experiment consistently see the same variation, regardless of the device they use to access the website.

However, it's important to acknowledge that maintaining this consistency can be challenging in certain scenarios. For example, if a user visits the website on their initial device, logs in, and triggers an experiment, Kameleoon may assign them to variation V1. If the same user then visits the website on another device, triggers the same experiment before logging in, they might be assigned to variation V2. This inconsistency occurs because the system has not yet recognized the user across devices. It's important to note that we intentionally do not override the variation allocation during a single visit to avoid disrupting the user experience.

To mitigate this issue and ensure consistency, it's crucial for Kameleoon to promptly recognize visitors throughout their website journey. By identifying visitors early on when they access the website from different devices, we can ensure they are consistently assigned the same variation. This approach allows Kameleoon to provide a seamless and coherent testing experience, ensuring visitors receive consistent variations across different devices.

Cross-device history reconciliation for analytics

History reconciliation impacts only the visitor view in Kameleoon reporting; the visit view remains unaffected. In the visitor model, instead of grouping multiple sessions into a single visitor record using the standard Kameleoon visitorCode value (which is only possible for returning visitors on the same device), we merge them based on the custom data value. If the custom data is empty or not provided, the visitorCode value is used instead. This approach ensures that unique visitor metrics remain accurate, even if the user is not yet identified in your customer system (though this applies only to returning visitors on the same device).

As a result, the visitor view correctly displays metrics across all devices for identified users (or known customers). For example, a single customer with three sessions on two different devices is counted as a single visitor. Without history reconciliation, the same customer would be counted as two distinct visitors (one per device).

Using custom data for session merging

Using custom data as a unique identifier for session merging is only possible for sessions saved after Kameleoon has identified which custom data to use. Therefore, we highly recommend selecting your custom data during the initial installation and configuration of Kameleoon to avoid changing it later.

For instance, if you allow Kameleoon to run for one month without enabling cross-device history reconciliation, and then activate it in the second month, a single user who visited twice (once in each month) will be counted as two different visitors. This discrepancy occurs because session merging in the first month uses the visitorCode as the key, whereas in the second month, it uses the custom data with a different value, even if the user logged in on both visits using the same device.

Any modifications to the custom data setup responsible for history reconciliation will temporarily affect visitor-based metrics accuracy.However, this inaccuracy will disappear over time.