An alternative Chameleon installation method is using a snippet manager, such as Google Tag Manager (GTM).
Below you can find a detailed step-by-step guide to installing Chameleon using GTM. The setup process will get you up and running in a few minutes.
🧑💻 Ask your developer to help you if you're not comfortable installing Chameleon this way, to ensure you'll start with the right setup.
Installing Chameleon via GTM
Installing Chameleon using Google Tag Manager is a simple process, similar with installing other analytics, that usually takes just a few minutes. This installation method has 3 essential components:
Head over to the installation page in your Dashboard, select “Install via Google Tag Manager” as your installation method, and follow these steps.
Define User Variables in GTM
Chameleon needs you to identify your users to be able to show Experiences. To do this, you'll need to use our chmln.identify({{uid}}); method, which is meant to pull user data from your app's client-side. With GTM, this data is pulled using User-Defined Variables, which will then be passed along to Chameleon.
First, you'll have to create a ‘User-Defined Variable’ of ‘Custom Javascript’ type within Google Tag Manager to enable a unique user ID to be added to the Chameleon script.
A unique User-Defined Variable must be created for each user property that you want to send to Chameleon. Defining the uid is *required for all users* and without it, they will not see any Experiences.
To create a new User-Defined Variable:
Access the Variables option in GTM and create a new User-Defined Variable.
Under Variable Configuration, select the Custom JavaScript variable type.
Use the following code snippet to define your user's
uid, by pulling it from your app.function() {
var uid = PLACEHOLDER.UID; //replace with your UID property
return uid;
}
// Name the property by adding UID (in this case) in the Global Variable Name and Rename Variable fields
ℹ
You'll need to replace the placeholder (represented in UPPERCASE) with your app's actual variable, as in the screenshot below.
You need to send a UID to identify users in Chameleon on each page, otherwise, your Experiences will not be displayed.
Repeat the same process for any other properties you want to send to Chameleon. We recommend at least email , but you can send both user properties and company properties to help you target users more precisely.
How do I know what data I should use here?
To figure out how to get the data from the page, it helps to know:
what variable namespace the user data that’s stored on the client side of your app,
how it can be accessed, and
what user properties are present.
Your app is likely storing user data within the page that your user loads. For example, it might look like the following:
window.userDatawindow.app.currentUserwindow.account.logged_in_user
ℹ These are hypothetical examples and will likely be named differently within your app. 🧑💻 We recommend asking your engineering team which variable namespace contains a unique ID for the currently logged-in user to know what to use here.
Install the snippet and identify users
The Chameleon snippet has 2 components, one that enables you to create in-app Experiences and the second to correctly identify users (and show the right in-app Experience to each one).
Create a new tag in Google Tag Manager. This tag must be named Chameleon and have the type Custom HTML.
Next:
Copy your custom Chameleon code snippet from the Chameleon Dashboard.
Paste it on the HTML field of your GTM tag between
<script>tags.Select All pages as the tag's trigger and add any exceptions.
ℹ You'll be able to modify your Triggers and add any exceptions, but note that Chameleon will only identify users and show Experiences wherever the code snippet is loaded and user data is flowing.
Sending your user data to Chameleon
Use the same process of defining User ID Variables, to send any data to Chameleon. Simply update your GTM Tag with the code from your Chameleon Dashboard, and add the name of the property inside your Tag.
This code needs to be inserted after the Chameleon code you initially added. Just like in the example below, where we're identifying users with the uid property, and also sending the email user property, for which we've previously created a User-Defined Variable.
ℹ Any data sent to Chameleon needs to be defined in these variables and interpolated into the snippet. In order to work correctly, these properties need to exist on the page so that GTM can reference them.
Publish the tag
Go ahead and publish your new tag! 🚀 Once you do this, Chameleon will be deployed to your application and you'll be able to launch in-product Experiences.
Verify your installation
The last step in your Chameleon Dashboard is to verify that Chameleon has been successfully added to your domains or subdomains and finish your installation. Domains will show up automatically if data is being received here but you can also enable additional domains.
If you install Chameleon on a domain that's different from your email domain, it will be automatically disabled, and you should manually enable it from the "Verify Installation" page or from your Environments. The same goes for new subdomains that you add to already-enabled domains, to ensure better security and that no malicious domains get added to your account by default.
Solution for asynchronously loaded user data
Some apps might load user data asynchronously -- this means the user data needed isn't available as GTM runs your tag when the page loads. In these instances, Chameleon can sometimes not load and will not work correctly.
If you're experiencing this situation, we recommend you use Custom event triggers to send events from your application to GTM, and ensure Chameleon loads after the user data is received.
Create a new Tag with the Chameleon code snippet -- follow the steps, except for 2.Identify users and send user properties.
In your app's code, add a data layer code event that runs only after your user data is loaded and available.
Set a Trigger to your Tag to run after the event you added in step 2. This tells Chameleon to run only after the data needed to identify your users is available.
Creating a Trigger in GTM
Access the Triggers option in GTM and create a new one
Choose the trigger type to be a Custom event
Save your Trigger in GTM
This way, every time a user loads your app and the event is pushed, GTM can run the trigger and the Chameleon code, ensuring your users are identified correctly.