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 A/B 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 history reconciliation 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 like Data Layer integration or Activation API.


If the option is not active for your custom data, it means you may already have an active custom data used as a unique identifier, as you can only have one custom data of this type per project.


Make sure that the transmission of the custom data to Kameleoon is correctly configured. An incorrect configuration can affect cross-device history reconciliation and other Kameleoon operations such as targeting. Don't provide a constant value like 0 to all visitors as Kameleoon will consider them all to be the same unique visitor. Also, don't select multiple custom data as unique identifiers.

Cross-device history reconciliation for campaign targeting

If the setup is done correctly (as described in the previous paragraph), Kameleoon will automatically download the list of visits that occurred on other devices and store this information in the current device's Local Storage when a new session begins and the custom data is present. However, if the custom data is empty, reconciliation won't be performed at the start of the session. It will only be triggered when the custom data is passed, and targeting will be re-evaluated for all active experiments and personalizations (a network call is made to Kameleoon's server). This usually occurs when the user logs in to your site and provides their user id, email or other unique identifier to Kameleoon.

It's important to note that once the custom data is provided, it will be present for the visitor's next visit, and reconciliation will occur at the start of the following session. This is independent of the visitor's logged-in status in your system, as Kameleoon remembers the identifier for a long period of time.


To ensure a coherent unified data history for a visitor, it's recommended to provide the custom data as early as possible during their journey on your website. Kameleoon won't be able to provide this history before the custom data is passed.

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 their usual information, such as:

  • Number of visits and page views
  • Length of session
  • Acquisition channels and referrers
  • Key pages viewed
  • Custom data (note that custom data provided in other sessions, and scoped to the visitor, will be merged on the current one).

You can use normal targeting segments as usual, and they will work as expected. For example, a targeting condition based on the number of previous visits will correctly take into account all visits, as will a targeting condition based on the previous visit duration.


A maximum of 25 visits can be available for cross-device experimentation and a 2-month retention policy applies to the data that can be retrieved.

Cross-device history reconciliation for variation allocation consistency

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

However, it is important to acknowledge that in certain scenarios, maintaining this consistency can be challenging. For instance, consider the situation where a user visits a website on their initial device, logs in, and triggers an A/B test, and Kameleoon assigns them to variation V1. If the same user then visits the website on another device and triggers the same A/B test 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 deliberately chose not to override the variation allocation during a single visit in order to avoid disrupting the user experience.

To mitigate this issue and uphold consistency, it is 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 that they are assigned the same variation consistently. By doing so, Kameleoon can provide a seamless and coherent testing experience, ensuring that visitors receive consistent variations across different devices.

Cross-device history reconciliation for analytics

History reconciliation only impacts 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 ensures that unique visitor metrics are accurate even if the user is not yet identified in your customer system (although it only applies to returning visitors on the same device).

As a result, the visitor view displays metrics correctly across all devices for identified users (or known customers). 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 the 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 that you choose your custom data during the initial installation and configuration of Kameleoon so that you never have to change the custom data setup.

For example, if you allow Kameleoon to run for one month without cross-device history reconciliation, and then activate it during the second month, a single user who made two visits, one during each month, will be counted as two different visitors. This is because the key used for session merging during the first month will be visitorCode, but during the second month it will be the custom data with a different value, even if the user was logged in on both visits and using the same device.

Any changes to the custom data setup responsible for history reconciliation will result in temporarily inaccurate visitor-based metrics. However, this inaccuracy will disappear over time.