Note: this integration is available to Enterprise customers only at this time.
ClearBrain allows you to send your user data to the ClearBrain platform via Google Tag Manager. Using a Custom Image Tag pixel, you can send page views, events, and user properties to ClearBrain to power your user predictions.
Step 1: Create a GTM Connection in ClearBrain
To get started, go to the "Data - Connections" tab, and click the "New Connection" button. Choose the Google Tag Manager option, and a list of form fields will appear:
Name the connection with a unique name, and click "Create Connection".
Within the connection, we provide templates for "pixel" tags that you can use to configure custom image tags in GTM.
There are three types of pixel tags to choose from, depending on the GTM Triggering condition you select in Step 3 later:
- Page Pixel: Use this pixel for GTM tags triggered on Page View triggers
- Track Pixel: Use this pixel for GTM tags triggered on Click, User Engagement, or Custom Event triggers
- Identify Pixel: Use this pixel for GTM tags triggered on login or signup, to pass in authenticated user attributes (see Step 5c for more info)
Step 2: Create a Custom Image tag in Google Tag Manager
With a GTM connection enabled in ClearBrain, proceed to your Google Tag Manager console.
From the main dashboard, select the "Tags" tab in the left menu, and click "New" to start the new Tag creation:
In the popup modal that appears, click the "Tag Configuration" box, and select the "Custom Image" option from the tag type options:
A form field will then appear titled "Image URL". Insert the pixel URL you selected in Step 1 from the ClearBrain UI into this field:
Step 3: Set the Triggering conditions for your Pixel Tag
With your basic tag configuration complete, the next step is to configure the conditions that will trigger your pixel events to be sent to ClearBrain.
To set this up, click the "Triggering" box in the Tag Creation modal (it will be be below the "Tag Configuration" box).
Once selected, you will be prompted to select from a set of triggers you have pre-configured in Google Tag Manager. Choose one of your existing triggers, or click "+" to add a new custom trigger.
Important Note: the pixel URL you chose in Step 1 should inform the type of trigger you select here:
- If you select a "Page View" trigger, make sure you are using a Page Pixel from Step 1
- If you select a "Click", "User Engagement", or "Custom Event" trigger, make sure you are using the Track pixel from Step 1
- If you select a trigger related to Sign Up or Login, make sure you are using the Identify pixel from Step 1
Step 4: Add Variables to your Pixel Tag
With the pixel and triggering conditions configured into your GTM tag, we have the basic firing conditions set up. However to leverage your data to its fullest capacity, we'll need to append additional information about your user attributes and events to each GTM tag.
We can append this information via variables in GTM. To add a variable to your GTM pixel, you'll need to follow a series of steps.
First, you have to declare a variable name at the end of the image Pixel URL you entered in Step 2.
Declare the variable name with a
& sign followed by the name you want to give the variable, and then a
= sign. For example, if you want to add a variable for page_referrer, you would append the string
&page_referrer= to the end of the Pixel URL:
The pixel URL templates provided in the ClearBrain UI already include a write_key parameter -- keep this required parameter.
Important Note: When naming the variables, for certain attributes we require using ClearBrain reserved variable names, outlined in Section 5 below.
Once the name is declared, you will next want to set a value for the variable you have defined. To set a value, click the lego icon next to the image URL field:
Once selected, you will be prompted to select from a set of variables you have pre-configured in Google Tag Manager.
Choose one of your existing variables, or click "+" to add a new custom variable.
Once you have added your variables, they will be appended to the end of your Google Tag pixel.
Important Note: when adding multiple variables to the Pixel URL, make sure each variable is separated by an
Step 5: Add Required Variables to your Pixel Tag
Before saving your Pixel tag, note there are some specific variables we require you add to your pixel. These include both name and user identity attributes, which must be declared in a specific format to ensure ClearBrain can automatically generate them as inputs for predictions.
Below we outline the variables to include, and the required format.
Step 5a: Add a user identifier variable to all your Pixel Tags
To associate each of the events triggered by your GTM tag with a specific user, we require that you add variables with user identifiers.
We require the following variables be explicitly declared on the respective Pixel tags:
- anonymous_id - the identifier for an anonymous user (required for all Pixel tags)
- user_id - the identifier for an authenticated user (required for Identify Pixel, optional for Track Pixel and Page Pixel)
- email - the email address of an authenticated user (optional for all Pixels)
So for instance for an email address identifier, you could append the pixel URL with
&email= to declare the variable, and then select the appropriate variable (using the lego icon in Step 4) to complete the string as
Step 5b: Add a Name variable to your Page & Track Pixel Tags
To classify the events or pageviews triggered by your GTM tag, we require you set a "name" variable for the Track pixel you instrument (it is optional for Page pixels). This will enable you to have each distinct event be classified separately.
- name - the distinct name of the event or page to be triggered
You can define a name by appending the pixel URL with:
&name=, and then selecting the respective "Event" or "Page" variable from the menu, completing the string to be something like
If there is no dynamic "Event" or "PageView" variable, simply provide a static value for the Tag name, i.e.
Step 5c: Add user attribute variables to your Identify Pixel Tags
In addition to the Page & Track Pixel tags, we recommend adding at least one additional tag using the Identify pixel URL.
You would use this Tag to send variables associated with properties or facets of a user (rather than an event), on login or signup triggers. These could include variables such as plan_name, gender, etc.
Simply declare and select the appropriate variable name as described in Step 4, and make sure to add it to the Identify Pixel tag implemented.
In totality, each of your GTM pixel URLs should look like something to the effect of:
Includes variables: write_key (required), anonymous_id (required), user_id (optional), email (optional), name (optional)
Includes variables: write_key (required), anonymous_id (required), user_id (optional), email (optional), name (required)
Includes variables: write_key (required), anonymous_id (required), user_id (required), email (optional)
And with these steps complete, click "Save" and you're done setting up your GTM pixel tag!
Repeat Steps 1 - 5 for as many event triggers you would like, and map out your entire user journey as distinct tags into ClearBrain. Each tag will be leveraged as both an inputs and goals for your predictions in ClearBrain.