This article explains how to troubleshoot the Experience Accelerator by understanding how it works.
Basic Principles of the Experience Accelerator
The Experience Accelerator uses "consistency of allocation" based on the uid. The same uid will always allocate the same combination of variations (assuming it is still active), or exclusion (if only a % of the total traffic is to be included in the experiment).
With consistent behavior for every uid, we can make independent requests for different assets and get the same combination allocation every time. This is what enables us to create dynamic assets that define the javascript or css that needs to be applied.
This assumes that all Experience Accelerator environments are configured to use the hashring. This is a prerequisite for any Experience Accelerator experiment.
Client-side data storage
There are 3 types of integration described here.
- When the data-evolv-uid data attribute is set there is no local storage of the uid.
- When the data-evolv-uid data attribute is not set the evolv:uid is set in Local Storage.
- When the data-evolv-sid data attribute is set there is no session storage of the sid.
- When the data-evolv-sid data attribute is not set the evolv:sid is set in Session Storage.
3rd Party Cookies
- evolv:uid
Experiment specific
- evolv:cids:[eid]
- evolv:sid:[eid]
These cookies are set and accurate to the cids that have been received, but they do not control any rendering and they are not used for data transfer.
Expected calls to server
Dynamic Assets - assets.css and assets.js
These are the files that provide the changes to be applied - together they are the combination of variants that a user has been allocated.
Expected arguments
This is a get request. The URL contains the environment id and uid.
- https://participants.evolv.ai/v1/{environment_id}/{uid}/assets.css
Again -- if the same uid is used then you will get the same allocation result. The only cases where this will change are:
- The previously allocated combination has been deactivated
- The % traffic throttling has changed
configuration.json
This JSON file describes the client information the system knows and the configuration of experiments in the environment.
Each node can contain a _predicate. This contains information about whether or not the node is applicable. These node keys will match the keys found on the asset files and are used to identify if a change should be applied.
Expected arguments
This is a get request. The URL contains the environment id and uid.
- https://participants.evolv.ai/v1/{environment_id}/{uid}/configuration.json
allocations
This returns the allocated combination and some other key information for a uid.
| uid, sid | It parrots back the values it was sent for these |
| eid, cid | The experiment and allocated combination ids are returned. This is important for any integrations with tools that would be required to know the user and their allocated combination. |
| audience_query | The rules to evaluate which users should be entered into the experiment. This is evaluated against the context set by ‘evolv.context.update(_context)’. |
| excluded |
If the user was excluded due to a less than 100% traffic limit setting, this will be true. |
On every call to evolv.context.update Evolv will check to see if any predicates now match, or no longer match. It will apply the new matches. If an entry page predicate now matches the context, a confirmation event will be sent.
Expected arguments
This is a post request that takes uid and sid as parameters.
- https://participants.evolv.ai/v1/{environment_id}/allocations
events
Every entry page (see configuration.json -> is_entry_point) will fire an event of confirmation on every page load.
Non-entry pages will not.
Expected arguments
This is a post request that takes uid, sid, eid and cid as parameters (among other secondary info).
- https://participants.evolv.ai/v1/{environment_id}/allocations
DEBUGGING - What is active
Call:
evolv.client.getActiveKeys()
To get a list of every key that should be applied.
DEBUGGING - Why isn’t my change applying?
First - what are the changes I expect to see?
Let’s say you’ve loaded this page:
To find out which changes may be applied you need to look at the loaded asset.css and asset.js files. In the example below, we could expect to see the ReactLogo with a ‘blueviolet’ text color.
We can see that the variant has a key of ‘evolv_web_tgv4hbyz4_tfq6hoxze’. This tells us the context we would expect to see this change in. Looking at the configuration.json request, we can find the ‘tgv4hbyz4’ context in the first experiment. We can see it has a predicate rule that the url must match the base64 encoded regex.
Decoding that regex, we see the regex pattern:
Checking the current page url against this regex we see it doesn’t match.
We need the path to have an ‘exact/’ at the end.
Going to the right page we see the change is applied.
Matching an audience
Take this example - where we have already verified we are using the correct url, but the change is not applied.
We can check the audience rules by looking at the predicate for the ‘web’ node in the configuration.json call.
To get into the experiment we need to set the ‘updated’ value to ‘abc’. This is done with
evolv.context.update({'updated': 'abc'});This can be done at any point, and the changes will be reevaluated.
And the changes apply.
The keys entered will be evaluated directly to the context on the client. Audiences will be evaluated against the combination of the remote and local contexts.
These custom conditions can be defined in the audience builder.