Getting Chameleon installed is a quick process that enables you to create Experiences in your product.
If you don't use Twilio Segment or Freshpaint then you can install the code manually. This won't take long and is similar to installing other JavaScript snippets, such as for analytics or other tools.
🧑💻 Ask your developer to help you if you're not comfortable installing Chameleon this way, to ensure you'll start with the right setup.
Install Chameleon
ℹ To access the Dashboard, you need to have an account created with Chameleon. You can create one here.
Installing Chameleon directly using JavaScript is a simple process that usually takes just a few minutes, and has 2 components:
installing the core script that includes the code snippet (the Chameleon functionalities that allow you to create and publish Experiences) and identification method (the Chameleon method used to keep track of what to show to your users).
sending user data for targeting and personalization (such as user or company properties, and user events)
Optionally, you can also Encode your UIDs to prevent unauthorized access to your data. This is a step you can take during your JavaScript installation.
Head over to the installation page in your Dashboard, select “Install via Javascript” as your installation method, and follow these steps.
Configure your code snippet
By default, you'll see the core script functionalities enabled, and you can then toggle on what else to include in your code snippet. The snippet will automatically adjust to include the different code components, and you can copy the code directly from your Dashboard.
ℹ The "Core Script" is an essential component for Chameleon to work properly and identify users to know who should see your Experiences. Sending user data is strongly recommended to enable you to refine your targeting and personalize your in-app Experiences.
Encode your UIDs
In the same manner, you can choose to Encode your UIDs to prevent any unauthorized parties from identifying users.
This works by adding an encrypted user_hash (HMAC) to your installation snippet. Once you enable this, Chameleon won’t accept sign-in requests without a valid user_hash and verifies the authenticity of requests made to our API.
Toggle this option on, and from the dropdown pick the server side language of your product. Copy the Secret Key and include it in the Encode UID snippet.
ℹ You should not replace the 'Secret Key' provided to Encode your UIDs with the 'Regular Key' (that contains the code snippet). If you receive an error saying 'The key you are using is not found in Chameleon' review your code snippet to ensure you have the correct Key.
Verify and finish the installation
The last step 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.
ℹ Chameleon must be installed and be able to identify users on every page that you want Experiences to display (not just when users log in).
Helpful tips
Make sure the snippet is included on all private pages - typically before the closing
</head>tag.Ensure you replace USER.ID_IN_DB with the variables your codebase uses for user IDs/records and proceed similarly for the other PLACEHOLDERS (these are identified as all-caps words in the code snippet).
You can install Chameleon on any subdomain (or even locally), although we recommend installing directly on production.
Plan which user data to include -- discuss with your team what would be useful for targeting Chameleon Experiences or for personalizing content.
You can also send other user data (e.g. user events) from your product, by using our API. You have options to send data via our front-end JS API, our back-end REST API, or a collection of Webhooks. Learn more about how to send users' data to Chameleon.
Ensure you're identifying users correctly
Chameleon relies on accurate user data to be able to match the right Experience with the right users. When it comes to showing Experiences, URL matching, targeting specific audiences, and personalization, here are some important notes to keep in mind:
The user ID is *required for all users* (without it, they will not see any Experiences)
The user ID must be a string, even if it's a "number" put it in quotes to stringify it
The user email is necessary for some integrations to work correctly
The user created date is strongly recommended (to be able to target new or old users)
Chameleon must be installed and identify users on every page that you want Experiences to display (not just when users log in)
👇 Below is an example of the script you'll find in your Dashboard:
// This is an example script, don't forget to change the PLACEHOLDERS.
// Please confirm the user properties to be sent with your project owner.
//
chmln.identify(USER.ID_IN_DB, { // Unique ID of each user in your database, must be a string (e.g. "23443" or "590b80e5f433ea81b96c9bf6")
email: USER.EMAIL, // Put quotes around text strings (e.g. "jim@example.com")
created: USER.SIGN_UP_DATE, // Send dates in ISO or unix timestamp format (e.g. "2017-07-01T03:21:10Z" or 1431432000)
name: USER.NAME, // We will parse this to extra first and last names (e.g. "James Doe")
role: USER.ROLE, // Send properties useful for targeting types of users (e.g. "Admin")
logins: USER.LOGIN_COUNT, // Send any data about user engagement (e.g. 39)
...
project: USER.PROJECT_ID, // Send any unique data for a user that might appear in any page URLs (e.g. 09876 or "12a34b56")
company: { // For B2B products, send company / account information here
uid: COMPANY.ID_IN_DB, // Unique ID of the company / account in your database (e.g. 9832 or "590b80e5f433ea81b96c9bf7")
created: COMPANY.SIGN_UP_DATE, // To enable targeting all users based on this company property
name: COMPANY.NAME, // Send any data that appears within URLs, such as subdomains (e.g. "airbnb")
trial_ends: COMPANY.TRIAL_ENDS, // Send data about key milestones (e.g. "2017-08-01T03:21:10Z")
version: COMPANY.VERSION, // If your software varies by version then this will help show the correct guidance (e.g. "1.56")
plan: COMPANY.PLAN, // Send null when no value exists (e.g. "Gold", "Advanced")
...
spend: COMPANY.CLV // Send other properties that will help in targeting users (e.g. sales rep, source, stage)
},
});
It is also possible to display in-product Experiences to unidentified users. In this case you want to include your website visitors or any other anonymous users that visit your page. To do so, you will need to include code logic to generate a unique ID and store it in a cookie.