Installing elevio on your site

When you create your account, you'll be shown a snippet of code to add to your site, simply copy this code and paste it into your site just above the closing body tag.

<script>
!function(e,l,v,i,o,n){e[i]||(e[i]={}),e[i].account_id=n;var g,h;g=document.createElement(v),g.type="text/javascript",g.async=1,g.src=o+n,h=l.getElementsByTagName(v)[0],h.parentNode.insertBefore(g,h)}
(window,document,"script","_elev","https://cdn.elev.io/sdk/bootloader/v4/elevio-bootloader.js?cid=","xxxxxxxxx");
</script>

NB. Replace "xxxxxxxxx" with your account id, found on your settings page.


Passing user information

There are a few reasons why you might want to pass user information through to elevio:

  • Restricting articles to certain:
    • email addresses
    • email domains
    • groups, e.g., 'gold plan' vs 'free plan'
  • Pre filling chat client form.
  • Pre filling support form.
  • Load existing support tickets for the logged in user.

To allow for these, you can pass through user information:

<script>
_elev.user = {
    first_name: 'John',
    last_name: 'Doe',
    email: 'john@example.com',
    phone_number: '555-555-555', // used by some of the live chat clients
    user_hash: '98aad46fd8124d2f8096fdfd2f56951850623403f683a6d85f795f96d3439b7d',
    groups: 'gold',
    traits: {
        Plan: 'Gold',
        'Monthly Spend': '$99'
    }
};
</script>

With the above, John would gain access to any articles that have been locked down to only be available to users in the gold group.

Additionally, you can lock down articles by email address, and email domain.

It is up to you which pieces of user information you want to pass through, they are not all requred.

Using the traits, you can also send through extra information that will be passed through to any support tickets so you can get a better understanding of who is sending the support request right from the ticket content.

NB. When sending email address with the user info, you MUST also send a matching user_hash
Learn how to generate the user_hash below.


The user_hash field

Whenever you send through the email address of the user, you must also send through an user_hash for this user.

This allows us to check at our end that an attempt to hijack someones account by inserting another email address isn't successful.

To create the user_hash value, create a hash value based on the users email address and your accounts 'secret' value which you can find on your settings page.

Choose a language below to see how to generate the hash:

PHP

_elev.user = {
    email: '<?php echo $user->email; ?>';
    user_hash: '<?php echo hash_hmac("sha256", $user->email, "ADD_YOUR_SECRET_ID_HERE"); ?>'
}

NB. If you have installed the widget by using a plugin, you won't need to go through this step.


Changing user in one-page apps

Typically, the user is set on page load. However if you're loading elevio on a one page app you might need to set the user after elevio has loaded.

To do this, use the _elev.changeUser() call

If need be, you can also log the user out with _elev.logoutUser()

// build the user object
var user = {
    first_name: 'John',
    last_name: 'Doe',
    email: 'john@example.com',
    phone_number: '555-555-555', // used by some of the live chat clients
    user_hash: '98aad46fd8124d2f8096fdfd2f56951850623403f683a6d85f795f96d3439b7d',
    groups: 'gold',
    traits: {
        Plan: 'Gold',
        'Monthly Spend': '$99'
    }
};

// set the user
_elev.changeUser(user);

// log the user out
_elev.logoutUser();

Setting the language

Elevio uses the browser to determine which language to use.

You can however override this to force a specific language to be used if you like, by doing something like this directly after you've set the account_id when loading the elevio script:

<script>
//...
_elev.account_id = 'xxxxxxxxxx';
_elev.lang = 'fr'; // to force French
</script>

Available options are:

  • zh - Chinese
  • cs - Czech
  • da - Danish
  • nl - Dutch
  • en - English
  • fi - Finnish
  • fr - French
  • de - German
  • hu - Hungarian
  • ja - Japanese
  • no - Norwegian
  • pt - Portuguese
  • ro - Romanian
  • rs - Russian
  • es - Spanish
  • sv - Swedish
  • vi - Vietnamese

Overriding set translations

Some of the content in the widget is hard set, and controlled by language files (i.e., not from your dashboard).

These are items like 'loading', 'sending' etc, as well as any other messages or content blocks.

You can though override any of these on a per page load basis, just add a translations object to _elev when loading, and add any overrides

<script>
//...
_elev.translations = {
    general: {
        search: 'Find'
    },
    modules: {
        articles: {
            related_articles: 'These articles might help'
        }
    }
};
</script>

The full set of items available for overrides (and their defaults) are below:

_elev.translations = 

Locking down articles

From the articles section of your dashboards, you can lock down any of the articles that you have either created or syncd from a third party knowledge base you have previously connected with.

To lock down any article, on the create or edit article screen the 'User Access Control' section will provide fields to control who can access this article. Select from the list which level of restriction you would like then enter any accepted emails, domains or groups.

The same can also be done at the category level to lock down an entire category rather than each article inside a category individually.


Override keywords for a given page

From the admin area, you can set keywords for your articles and pages, to specify which articles you'd like to appear as 'related articles' when users view the articles module.

In some cases however, you may want to override this from code. You can do this by setting the keywords attribute, like this

_elev.keywords = ['keyword1', 'keyword2'];

This will take precedence over any keywords that you may have set in the admin area for the give page.


Enable / Disable modules on the frontend

When you load the script, you can now send a list of modules that would normally load (get their ID from your module list page), that you explicitly do not want to load.

For example, if you wanted to not display the modules with IDs of 123 and 321 on certain pages of your site, you can do so with the following

_elev.disabledModules = [123, 321];

If need be, you can also disable any loaded modules later using the following (NB the modules need to be enabled from your dashboard, the following overrides those settings):

_elev.disableModules([123, 321]); // disable modules later
_elev.enableModules([123, 321]); // enable modules later

Opening a chosen module from code

By using markup

When someone clicks on the tab on your site, it will as you'd expect, open. If you want to open it on some other event though, you can add a small snippet of code to any element of your site to open the desired module.

To do this simply add a data-elevio-module attribute to an element on your site and assign it either a module type or a module ID. Setting a module type is the easiest but it assumes that you only have one module of each type.

<a href="#" data-elevio-module="support">Support</a>
<a href="#" data-elevio-module="34">Support</a>

By using javascript

Sometimes you might want to trigger an article or a module open from your own script, using the below methods you can achieve this:

window._elev.openArticle(123);
window._elev.openModule('articles');

The modules you can open are:

  • articles
  • chat
  • comments
  • custom_form (assuming you only have one, otherwise, use the module ID)
  • intercom
  • rss
  • single_article (assuming you only have one, otherwise, use the module ID)
  • support

Opening 'inline tips'

In the same way you can open a specific article in the side bar, you can also have it open as a small inline popup

<span data-elevio-inline="2570">Inline tip example</span>
Inline tip example

Opening to a specific support article

In addition to openening a specific module from any element on your page, you can also open directly to any specific article in your knowledge base with a similar piece of code.

In your articles section, each article has a special ID that can be used to directly open the article (there's even a handy 'instructions' link in the table that will give you the exact code you need to copy and paste).

We call these contextual opens, to create a contextual open just add a data-elevio-article attribute to any element on the page and assign it the ID of the article you'd like to open, here's an example

<span data-elevio-article="1">Welcome!</span>
Welcome! | Another example

Note that clicking on the item will open the articles section, and jump directly to the requested article.

NB. This functionality relies on the "articles" module being installed for your widget.


Using the 'push in margin' setting

For some sites, it makes sense to show the elevio tab beside the content, not over the top of it.

In these cases, you can enable the 'push in margin' option in your settings. This will mean elevio basically pushes in from the side, rather than appearing over the top of content.

You can also enable / disable this on a per page basis by using the API as follows:

_elev.pushin = 'true'; // or 'false'

Override display settings per page

In your account settings, you can set the following items as your default settings:

  • Theme (light / dark)
  • Menu side (left / right)
  • Menu position (wall / floor / button)
  • Tab teaser (shown when menu position is set to 'floor')
  • Main color
  • Push in margins

However, should you need to you can override each of these settings when loading the script on any page with the following:

_elev.theme = 'dark'; // or 'light'
_elev.side = 'left'; // or 'right'
_elev.docked_position = 'wall'; // or 'floor' or 'button'
_elev.tab_teaser = 'Need a hand?';
_elev.main_color = '#000000'; // or 'black', or 'rgb(0, 0, 0)'
_elev.pushin = 'true'; // or 'false'

Available events

If you'd like to take an action when a particular event has occured in elevio, you can do so using the _elev.events object.

At this stage, the only available event is afterLoad

This is fired after elevio has completed it's loading, so you can use it if you'd like to automatically open a particular article or module on page load, here's an example of that in action

_elev.events = {
    'afterLoad': function () {
        // what you'd like to do after elevio has loaded, e.g.,
        _elev.openModule('articles');
    }
};

Using third party APIs

In some cases you might want to call some of the API endpoints for a third party plugin that elevio is using.

To do so, populat the third_party object when setting up elevio with the API calls you'd like to make when we setup the third party.

You can use this for the following third parties:

Olark: (use 'olark', see API docs here and here)
Zopim: (use '$zopim', see API docs here)
Livechat: (use '__lc' or 'LC_API', see API docs here)
Smooch: (use 'smooch_settings' to set any items you want to use in the Smooch.init call, see API docs here)

See below for an example using Olark:

_elev.third_party = {
    'olark': function(olark){
        olark.configure('locale.chat_input_text', "Type here and hit  to chat");
    }
};

Playground

You can control almost everything about your tab from your dashboard, however at run time you can use all of the above help to override your settings.

Use the below tool to play around with the overrides (you can also use the preview tool for a more 'point and click' experience)

Click on the 'JS' tab below to experiment with the overrides.

See the Pen GJovLR by Chris Duell (@duellsy) on CodePen.

© 2017 Elevio Pty. Ltd. All rights reserved.