This article describes the different steps necessary to create a bridge between Kameleoon and Google Analytics as to identify visitors within GA4 audiences then target them accordingly.
In a nutshell, this is accomplished by pushing our Kameleoon unique identifier (Kameleoon visitorcode) through a custom dimension at the beginning of a visit, then by calling GA4’s APIs to retrieve all possible values of this custom dimension within a specific audience then pushing the audience name (or ID) to Kameleoon by using our Data API.
We also provide native bridges with Google Analytics 4 to send campaigns metadata (campaign name and variation name) so that you can analyze your campaigns performance in GA4.
Prerequisites
To make this integration work, you need to send the following information to your Customer Success Manager as we will require it to set up the bridge in your Kameleoon account:
- The credentials of a service account in a JSON format (to create a service account and generate the credentials, please follow the first step). Please use a compression tool to secure this file with a password then send the package separately from its password.
- The property ID of your project.
- The sitecode of your project in Kameleoon.
Step 1: Set up the authentication through a service level account
To grant a technical user account access to a Google Analytics account and privileges to retrieve data through the different available APIs, the basic requirements are the following :
- An email account with admin access to Google Analytics account that will be used to generate a project and service account;
- Access to all required Audiences (in GA4) for this account.
Create a project on Google Cloud Console
The first step is to create a new project in Google Cloud Console which is necessary to activate APIs and create tokens.
Go to the following URL : https://console.cloud.google.com/home
Login to the email account with admin access and create a new project.
Name the project according to your naming convention.
Choose the organization and location you have access to.
Note: This is why the email account has to have admin access to the organization.
Activate appropriate APIs
In order to use any API with a particular email address, it must be activated in Google Cloud Console. This is done by clicking on Library (picking up from the previous section).
Search for the 3 next APIs in the search bar and activate them as indicated below :
- Google Analytics Reporting API;
- Google Analytics Data API;
- Google Analytics API.
Now both necessary APIs are active for the given user and will be usable directly in a Web service for instance.
Create service level account
In order to allow for full automation of GA4 reporting API requests, we need to create a service level account that will bypass the need for an authentication callback.
To create such an account, click on IAM & Admin > Service accounts.
Then click on Create service account :
Now fill in a name for the account that respects your usual conventions, the service email will be generated automatically.
We recommend that you add a description so that the purpose of this account is clear to all parties.
Next choose the role for this service account. We recommend that you choose a viewer role as our bridge only requires the use of Google APIs and not the project resources directly.
Once the account is created, click on Keys.
Then click on Add key > Create new key to generate a downloadable key.
Choose the JSON format then click on Create to generate the key.
This downloads the key on your computer.
Then send these credentials in a JSON format to your Kameleoon Customer Success Manager. Please use a compression tool to secure this file with a password then send the package separately from its password.
Grant Service Account Viewer permissions for your Property
Here are the steps to access the Property Access Management page in Google Analytics 4 (GA4):
- Sign in to your Google Analytics account.
- Select the specific GA4 property you want to manage.
- Access the Admin settings.
- Look for the “Property User Management” or “Property Access Management” option.
- Click on this option to manage user access permissions for your GA4 property.
Click the blue + at the top right corner, then click Add user.
In the Email Address field, enter the email address associated with the Service Account that requires access.
In the Standard roles section, choose Viewer.
Then click Add.
Step 2: Push Kameleoon Visitorcodes in a GA4 custom dimension
The next step to configure the bridge will be to send each visitor Kameleoon visitorcode to GA4 via a custom dimension.
Using gtag.js
1. Push the visitorCode to GA4
The following code has to be added in the Kameleoon global custom script section:
if (Kameleoon.API.CurrentVisit.pageViews === 1) {Kameleoon.API.Core.runWhenConditionTrue(function () {return typeof window.google_tag_data !== "undefined";},function () {gtag.push({ 'event': 'Kameleoon Visitor Code', 'kameleoon_visitor_code': Kameleoon.API.Visitor.code });},500);}
2. Create the custom dimension in GA4
The basic requirement for this is to create a custom dimension that will be used to receive our Kameleoon Visitor Code for each visitor. Please set the dimension scope to User, name it “Kameleoon Visitor Code” and enter “kameleoon_visitor_code” as the User property.
Using Google Tag Manager
1. Push the visitorCode in the dataLayer
The following code has to be added in the Kameleoon global custom script section.
if (Kameleoon.API.CurrentVisit.pageViews === 1) {
Kameleoon.API.Core.runWhenConditionTrue(
function () {
return typeof window.google_tag_manager !== "undefined";
},
function () {
dataLayer.push({ 'event': 'Kameleoon Visitor Code', 'kameleoon_visitor_code': Kameleoon.API.Visitor.code });
},
500
);
}2. Add the GTM variable
First, you need to create a variable in GTM for the Kameleoon Visitor Code. Go to Variables and create a new Data Layer Variable.
- Name:
kameleoon_visitor_code - Variable configuration:
- Type : “Data Layer Variable”
- Data Layer Variable Name :
Kameleoon Visitor Code
The variable should be set to retrieve the value from the Data Layer.
3. Create a tag in GTM
Next, create a tag to push this data into GA4.
1. Create a Variable
- Go to GTM: Open Google Tag Manager and navigate to your container.
- Navigate to Variables: On the left-hand menu, click on “Variables.”
- Create a New Variable: Under “User-Defined Variables,” click “New.”
- Select Variable Type: Click on “Variable Configuration” and choose “Data Layer Variable.”
- Configure the Variable:
- Name:
kameleoon_visitor_code
- Variable configuration:Type : “Data Layer Variable”
- Data Layer Variable Name :
Kameleoon Visitor Code
- Name:
The variable should be set to retrieve the value from the Data Layer.
- Save the Variable.
2. Create a Trigger
- Navigate to Triggers: On the left-hand menu, click on “Triggers”.
- Create a New Trigger: Click on “New”.
- Select Trigger Type: Click on “Trigger Configuration” and choose “Custom Event”.
- Configure the Trigger:
- Trigger Name: Give your trigger a descriptive name (e.g.,
Page Type is Product).- Event Name: Enter the name of the event you want to listen for, or leave it empty if you want it to fire on any event.
- This trigger fires on: Choose “Some Custom Events”.
- Conditions: Set the condition for your
dataLayervariable.
The regex corresponds to your visitor code: /^[a-z0-9]{16}$/
- Save the Trigger: Click “Save.”
3. Attach the Trigger to a Tag
- Navigate to Tags: On the left-hand menu, click on “Tags”.
- Create or Edit a Tag: Either create a new tag or edit an existing one.
- Attach the Trigger:
- In the tag configuration, scroll to the “Triggering” section.
- Click on “Triggering” and select the trigger you created
- Save the Tag: Click “Save”.
Step 3: Create a custom data to use your GA4 Audiences in Kameleoon
In order to be able to use your GA4 Audiences in Kameleoon campaigns, you will need to set up custom data within Kameleoon.
Name your custom data “GA4 Audiences” and choose the acquisition method Custom JavaScript code.
The custom data should be set to the list of and strings types, the scope may be set to visit or page (when being set to page, it is re-evaluated on every page load).
Please use the code below in the custom data acquisition method:
Kameleoon.API.Data.retrieveDataFromRemoteSource(Kameleoon.API.Visitor.code, function(data) {
for (const [key, value] of Object.entries(data)) {
Kameleoon.API.Data.setCustomData('GA4 Audiences',key)
}
});
return { "value": null}
Then click on Next and activate the Save the values for the targeting condition associated with the custom data point option. Add the JavaScript code below and replace [SITECODE] by the Kameleoon Sitecode. To find it, please follow this documentation.
Also, make sure you replace [WEB_PROPERTY] by the right GA4 property ID.
var xhr = new XMLHttpRequest();
xhr.open(
"GET",
"https://customers.kameleoon.com/kameleoon/ga4-audience/?sitecode=[SITECODE]&web_property=[WEB_PROPERTY]",
false
);
var GA4Audiences = [];
xhr.onreadystatechange = function () {
if (this.readyState === XMLHttpRequest.DONE && this.status === 200) {
var audiences = JSON.parse(xhr.response);
audiences.map(function (audience) {
if (audience) {
GA4Audiences.push({ value: audience, label: audience });
}
});
}
};
xhr.send();
return GA4Audiences;
Click on Validate to create the custom data.
That’s it! You will now be able to use your GA4 Audiences in our Segment Builder to target your visitors in Kameleoon campaigns, by choosing the custom data in our Segment Builder and selecting in the dropdown list is among the values, which will then show a list of every audience name from GA4.
External Segment Sync for Server-side
If you would like to use GA4 Audiences with one of our SDKs, you will need to follow the guidelines provided in each SDK documentation and use the method getRemoteData.
