This guide explains how to integrate your third-party A/B experiment tool with Google Analytics to allow your users to run A/B experiment variants in your tool and then interpret the results in Google Analytics.
Who this is for
The guide is intended for third-party A/B experiment solution providers. If you want to learn about the integration between Google Analytics and third-party A/B experiment solutions, see Integrating with a third-party experiment tool.
Overview
The integration between your third-party experiment tool and Google Analytics requires you to use:
- Google Analytics 4 events to add users to a variant
- Google Analytics Admin API to create an audience for the users who have been added to each variant
- OAuth 2.0 to get user consent to creating audiences on behalf of the user. Learn more about OAuth 2.0
Additionally, the user who starts the experiment in your tool must be an Editor (or above) in the Google Analytics property.
Add the exp_variant_string parameter to an event
You need to create an identifier for each variant and
then add the identifier to the exp_variant_string
parameter in
the following experience_impression
event. You'll use the parameter to
create an audience to associate a user with a variant.
gtag('event', 'experience_impression', {
// Replace the value with the Experiment-variant ID
exp_variant_string: "ABC-F2948574-3495F49"
});
Send the experience_impression
event when a user is added to a
variant (e.g., when an experiment page loads).
Format the parameter
To avoid duplication across experiments and other partners,
we recommend using the format XXX-YYYYYYYYY-ZZZZZZZZ
for the
exp_variant_string
parameter value, where:
XXX
is the ID for your third-party toolYYYYYYYYY
is the ID of the experienceZZZZZZZZ
is the ID of the variant
You can use any number of characters for your tool, experiences, and variants.
Define an audience using the exp_variant_string parameter
Audiences allow you to group users who have been added to a variant,
based on the exp_variant_string
parameter. By using this parameter as the
membership condition for an audience, you can add users to the
appropriate audience based on the variant they have been added to.
To create audiences for new experiences and
archive audiences for ended experiences, use the properties.audiences
resource
in the Google Analytics Admin API.
Create audiences
The following request body creates an audience for users who have been
added to a variant with the ID ABC-F2948574-3495F49
using the
properties.audiences.create
method. Note that you can adjust the membership
duration based on the length of the experience (max: 540).
We recommend that you set the atAnyPointInTime
parameter to true
to reduce
data discrepancies across experiments. When you set the parameter to true
, a
user who has been assigned to a passed experiment can be assigned to a new
experiment. When you set the parameter to false
or if it's unset, the user
cannot be added to a new experiment if they've already been assigned to a passed
experiment.
{
"displayName": "Audience ABC - experiment F2948574 variant 3495F49",
"membershipDurationDays": 30,
"filterClauses": [
{
"clauseType": "INCLUDE",
"simpleFilter": {
"scope": "AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS",
"filterExpression": {
"andGroup": {
"filterExpressions": [
{
"orGroup": {
"filterExpressions": [
{
"eventFilter": {
"eventName": "experience_impression",
"eventParameterFilterExpression": {
"andGroup": {
"filterExpressions": [
{
"orGroup": {
"filterExpressions": [
{
"dimensionOrMetricFilter": {
"fieldName": "exp_variant_string",
"stringFilter": {
"matchType": "EXACT",
"value": "ABC-F2948574-3495F49"
},
"atAnyPointInTime": true
}
}
]
}
}
]
}
}
}
}
]
}
}
]
}
}
}
}
]
}
The previous code snippet creates the following audience:
- Audience name: "Audience ABC - experiment F2948574 variant 3495F49"
- Audience definition: "Include Users when: events with the name 'experience_impression' have a parameter named 'exp_variant_string' with a value that exactly matches 'ABC-F2948574-3495F49'"
- Membership duration: 30 days
Archive audiences
When an experience ends, you need to archive the audience using the
properties.audiences.archive
method. Archiving audiences lets you free up
space for users to create more experiences. Users will still be able to access
data from their archived audiences using historical data in Google Analytics.
Audience targeting
Audience targeting enables your customers to focus an experiment on a group of users who exhibit specific behaviors on their website. For example, a customer can use audience targeting to target high-value customers with special offers and incentives. Through audience targeting, only users in the audience are shown an experiment.
You can enable your customers to set up audience targeting by importing the users in an audience from Google Analytics and then comparing the User IDs or device identifiers from Google Analytics with the identifiers in your system. When these identifiers match, the user is added to the experiment.
To export users from Google Analytics and import them into your client, use the Audience List API. The Audience List API provides a daily snapshot of the users in an audience and lets you export the User IDs or device identifiers in an audience.
We recommend only requesting an Audience List once per day per audience.
Limitations
Pausing experiences
Pausing audiences in Google Analytics 4 is not possible.
To enable users to pause experiences, you must:
- Stop sending the event that triggers when a user becomes a member of a variant
- Ignore any events while the experience is paused
- Add report filters to the Google Analytics report to exclude the paused time
Alternatively, you can provide users with a link to manually change the date in Google Analytics.
Reprocessing experience data
If users are missing event information, Analytics can reprocess their experience data. When Google Analytics re-processes experience data, archived audiences from ended experiences are lost. However, users can still retrieve their experience data through events with exp_variant_string in Explorations. This is less accurate than audiences as events that happened before and after the experience will be present in explorations.
Sampling experience data
If users can be allocated to multiple concurrent audiences, customers expose themselves to cardinality issues (which can cause the "(other)" row to appear). The probability of this happening increases as the concurrent experience count increases and the number of audiences used for other purposes (e.g., Ads bidding) increases.
However, if the customer uses Google Analytics 360, Google Analytics will enable automatic expanded data sets when data aggregates under the "(other)" row to give them a more complete picture of their data.
Comparison limits
Google Analytics 4 reports can display up to 4 comparisons at once. When a user has more than 4 variants, the user can swap their audiences in comparisons. Consider prioritizing variants with the best conversion rates.