Installing Chameleon

Getting Chameleon installed, the four minute guide

Chameleon works using JavaScript - you install a couple lines of code on your site / web app and this allows you to see the Editor and for your users to see tours, when published. There are two simple steps required to get started:

Adding the Chameleon code snippet

Installing via Segment

Note: only applies if Segment installed on all pages where you intend to display tours.

If you use Segment then you can automatically install the Chameleon snippet using the "Enable with Segment" button (see image below). This will also send product data (events and user properties) you are tracking with Segment to Chameleon, to use for segmentation and conversion.

To connect Segment.com and Chameleon please follow the steps below:

  1. Login to Chameleon
  2. In the Setup page, hit "Install now" and then "Enable with Segment"
  3. Go through the Segment authorization flow (couple clicks)
  4. Use Segment.com to connect to third party apps.

Highfives — That's it, you're connected and the Chameleon Editor will now be available on the properties that Segement.com is implemented.

Installing via Google Tag Manager

You can use a snippet manager such as Google Tag Manager (GTM). To do this, follow these steps:

1. Create new tag and add the Chameleon code snippet

  1. Name your tag: Chameleon
  2. Select Custom HTML
  3. Paste your code snippet (found in your dashboard)
  4. Select All Pages for the trigger

2. Identify users and send any user property via Variables. For each user property:

  1. Create a New User-Defined Variable
  2. Select Custom JavaScript

  3. Copy and paste the following, and include the relevant variable

        function() {
          var uid = window.uid; //<REPLACE WITH USERID PROPERTY>;
          return uid;
        }
    

    1. Name the property by adding UID (in this case) in the Global Variable Name and Rename Variable fields

Ensure all data sent as variables

All 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 GTM can reference them. (email, created_at, any segment info, etc).

3. Publish the tag

Installing manually

If you don't use Segment or GTM then you can install the code manually. This only takes a few minutes, and is similar to installing other JS snippets, such as for analytics or A/B testing tools. You can invite a developer on your team to do this from the Setup page in the dashboard (see below).

Things to note

  • Make sure the snippet is included on all private pages - typically before </head>
  • Use the snippet found in your dashboard, because it contains your personalized
  • Ensure you replace current_user.id and current_user.created_at at the end of the snippet with whatever variable you use for user IDs or user records and the time that the user was added to your system.
  • You can install this on any subdomain (or locally), although we recommend installing directly on production. Learn more here

Installing Chameleon on different environments

Installing locally

Implementation environment

We recommend implementing the snippet directly on your production environment. Users will not notice this - no tours are published without explicit action from you.\n\nDoing so will save you time and energy - it will avoid dealing with differences between your development and live environments when you would later make the switch.

You can load the Chameleon Editor on your local computer if you would like to first test locally before deploying to production. To do this: add the snippet locally or to a test/staging environment, then simply reload the page.

Please feel free to contact us if you have any further questions or suggestions.

A note about authentication

To keep you authenticated (to identify you as an admin and show the Chameleon Editor) we store your authentication information in an encrypted, HttpOnly, secure cookie that is and only served to us over a secure connection (https).

Using Chameleon on multiple sites

You can use the same snippet on all three sites, and launch the Sidebar on the different sites by going via dashboard.trychameleon.com/docs and entering the different URL before hitting Launch Sidebar. This will authenticate you as an administrator on those sites and show you the Editor.

This also means that in the Sidebar you will see all the tours you are using across the sites. Anyone authorized as an admin (you can invite others at dashboard.trychameleon.com/users) will be able to edit any of these tours. If you want separation then you'll need to sign up with the separate email addresses on our site and you will essentially have different logins and accounts.

To make sure the tours show on the correct sites, you can use the URL matching for each step. To learn more about this, see URL matching.

Selectively hiding Chameleon


We split Chameleon into two parts, what your end users see (user) and what you and your team see (admins). You can hide/suppress Chameleon for each of those two groups by picking one of A, B or C below.

The use case for this: When your app and homepage are on the same subdomain and you have no other way to limit tours based on the url of the page.

When integrated directly: include this on the line after the Snippet When integrated via Segment add window.chmln || (window.chmln = {}); before one of the options in the code below

    // A. To hide Chameleon for your end users\nchmln.elusive = 'user';\n\n// B. To hide Chameleon from you and your team (to treat yourself as an end user)\nchmln.elusive = 'admin';\n\n// C. To hide Chameleon from everyone (as if it was not installed)\nchmln.elusive = 'user,admin';",

Showing Chameleon on multiple domains

As long as your plan allows it, you can show any tour you build on any domain where you've installed your Chameleon snippet.

If you have tour steps that only show on a specific URL, you'll need to use URL matching, to make sure that the step will show on the different domains. For instance if the URL you build your tour on is 'http://demo-app.mydomain.com/user/settings', you'll want to use wildcards depending on how the domain can change.

  • If the subdomain changes, you might match your tour-step to "http://*.mydomain.com/user/settings"
  • If the path changes, you might match your tour-step to "http://demo-app.mydomain.com/*"
  • If you allow your users to install your app on their domain, you may want to match your step to the path of your app, using "*/user/settings/". If matching to the path won't work, take a look at User variables to include your user's domain, or the hostname of the page they're working on.

If you use a page User Action to redirect tours to a different page, you'll also need to update the URL you use to transition-to that page. To do this, you'll want to use User variables within the User Action to make sure the page is the correct location.

Launching the editing Sidebar

Once a page is loaded where your snippet is installed, that domain will show up in your dashboard. From there you can click 'Visit' to launch the Editor Sidebar on your site. This will identify you as an administrator so you see the Editor.

Enabling advanced segmentation

You can show variations of tours to different user groups. You can create these groups (segments) using any data you already collect about a user. This helps you create more personalized UX which should lead to higher engagement and conversion.

If you have setup Chameleon using Segment then you are automatically sending user data to Chameleon, and you can automatically use this in the Editor. If you setup manually, then you will need to send user data manually.

Sending additional user properties

As part of the Chameleon snippet, you already identify users with a unique ID:

chmln.identify({uid:})

You can simply send additional pieces of data about that user in this statement. At minimum, we recommend sending: created date and email, but you should send whatever you would like to use to differentiate users (e.g. role, plan, source, spend etc.)

An example of how you would alter the above JavaScript follows:

chmln.identify({uid:'currentUser.id', created:'currentUser.createdAt', email:'currentUser.email'})

We also track some basic properties that you can use, such as: platform, device, screen, browser, IP address, locale, city, state, country, timezone, and language.

Seeing existing user properties

To see all the user properties currently being sent, you can run some code in your local browser. \n\nOpen the JavaScript console, under Developer Tools (or hitting CMD + ALT + J for Chrome on Mac) and paste the following code and hit Enter:

chmln.data.segment_properties.where({kind: 'profile', source: 'chmln'}).map(function(p) { return p.get('prop') })


Here are some more examples of what you might send. More available on our Github

<script type="text/javascript">
  // Add the snippet here with account id (i.e. '<%= ENV['CHAMELEON_ACCOUNT_TOKEN'] %>')
  // Assuming you have exposed `helper_method :current_user` in your `ApplicationController`
  <% if current_user.present? %>
      chmln.identify({
          uid: '<%= current_user.id %>',
          created: '<%= current_user.created_at.iso8601 %>',
          email: '<%= current_user.email %>',
          plan: '<%= current_user.account.plan_name %>',
          spend: '<%= current_user.account.plan_cost %>'
      });
  <% end %>
</script>
// Add the snippet here with account id (i.e. config.chameleonAccountId)
// Assuming you preload your page with a current user

(function() {
  if(currentUser.id) {
    chmln.identify({
      uid: currentUser.id,
      created: currentUser.createdAt,
      email: currentUser.email,
      plan: currentUser.planName,
      spend: currentUser.planCost
    });
  }
})();
// Add the snippet here with account id (i.e. config.chameleonAccountId)
// Assuming you call `currentUserLoaded` after fetching the user

(function() {
  var currentUserLoaded = function(currentUser) {
    chmln.identify({
      uid: currentUser.id,
      created: currentUser.createdAt,
      email: currentUser.email,
      plan: currentUser.planName,
      spend: currentUser.planCost
    });
  };

  var xhr = $.get('/user.json');
  xhr.done(function(data) {
    // Setup other aspects of the environment

    currentUserLoaded(data.user);
  });
})();
<script type="text/javascript">
  // Add the snippet here with account id (i.e. <?php echo $GLOBALS['chameleonAccountId'] ?>)
  // Assuming your page has loaded the current user as the object $current_user
  <?php if (var_dump((bool) $current_user->present)): ?>
    chmln.identify({
      uid: '<?php echo $current_user->id ?>',
      created: '<?php echo $current_user->created_at ?>',
      email: '<?php echo $current_user->email ?>',
      plan: '<?php echo $current_user->account->plan_name ?>',
      spend: '<?php echo $current_user->account->plan_cost ?>'
    });
  <?php endif; ?>
</script>

Timestamps

Chameleon will interpret a property as a timestamp for a few reasons:\n\n1. If the timestamp is ISO 8601 standard, Chameleon will always assume the value is a timestamp.\n2. If the timestamp is a Unix Timestamp that falls between 1973 and 2033 and the name is either 'created', or ends in '_at' or '_time'. \n\nChameleon will interpret any of these properties as a timestamps: {started: \"2016-09-05T15:45:39+00:00\", ended: \"2016-09-05T15:45:39Z\", created: 1472985601, started_at: 1095292800, ended_at: 1095352800}.

Sending user actions

You can also segment based on which actions a user takes inside your product. You can send these events through our API. Read Create Events for more information.