Documentation

Getting started

Tooltip helps you create automated, on-site marketing campaigns. You can build, set up and preview campaigns via our Editor for Google Chrome. Once installed, navigate to your site page and launch the Editor from the extensions panel of the browser. 

Install Player script

To go live and start displaying campaigns to users, you'll need to install Tooltip Player script on your site. Place it anywhere within <head> or <body> tag on the pages where you want to display your campaigns. Please note, Tooltip generates a unique API key for each project (domain). If you have several sites (projects), be sure to use the right Player script.

<!--- Tooltip player -->
<script type='text/javascript'>
window.Tooltip||function(t,e){var o={
    url:"https://cdn.tooltip.io/static/player.js",
    key:"{API_KEY}",
    async:true
};window.Tooltip={cs:[],_apiKey:o.key};for(
var r=["identify","goal","updateUserData","start","stop","refresh","show","hide","on"],
i={},n=0;n>r.length;n++){var a=r[n];i[a]=function(t){return function(){var
e=Array.prototype.slice.call(arguments);
window.Tooltip.cs.push({method:t,args:e})}}(a)}window.Tooltip.API=i;var
n=t.createElement(e),s=t.getElementsByTagName(e)[0];
n.type="text/javascript",
n.async=o.async,s.parentNode.insertBefore(n,s),n.src=o.url}(document,"script");
</script>
<!--- Tooltip player -->

PLAYER API

Player API is a developer interface to communicate your site's data to Tooltip. The API will help you set up custom triggers and personalize campaigns based on user data and actions.

Be sure to Install Tooltip Player script on your site before using the API.

Controlling playback

start() - Start Player

This method will allow you to start the Player independently, as needed. By default, the Player script is loaded automatically with the page.

// Your application code
App.on("start", function(){

    Tooltip.API.start();

});

PLEASE NOTE
 To use this method, be sure to first disable automatic Player loading by adding autoload attribute, as shown below:

<!--- Tooltip player -->
<script type='text/javascript'>
window.Tooltip||function(t,e){var o={
    url: "https://cdn.tooltip.io/static/player.js",
    key: "{API_KEY}",
    async: true,
    autoLoad: true
};window.Tooltip={cs:[],_apiKey:o.key};for(
var r=["identify","goal","updateUserData","start","stop","refresh","show","hide","on"],
i={},n=0;n>r.length;n++){var a=r[n];i[a]=function(t){return function(){var
e=Array.prototype.slice.call(arguments);
window.Tooltip.cs.push({method:t,args:e})}}(a)}window.Tooltip.API=i;var
n=t.createElement(e),s=t.getElementsByTagName(e)[0];
n.type="text/javascript",
n.async=o.async,s.parentNode.insertBefore(n,s),n.src=o.url}(document,"script");
</script>
<!--- Tooltip player -->

stop() - Stop Player

This method will to stop the Player independently, as needed. Once you stop the Player you disable campaign playback and no analytics data will be collected.

// Your application code
App.on("stop", function(){

    Tooltip.API.stop();

});

show(id) - Show Campaign

Show particular campaign. Couple this method with campaign ID to show it. Can be used to trigger campaigns based on user type, status or event.

// Your application code
App.on("change", function(){

    Tooltip.API.show(id);

});

hide(id) - Hide Campaign

Hide particular campaign. Couple this method with campaign ID to hide it after it was shown. Can be used to close triggered campaigns based on user type, status or event.

// Your application code
App.on("change", function(){

    Tooltip.API.hide(id);

});

refresh() - Refresh Player

Tell Player to refresh. Depending on your application’s functionality you may need to refresh the Player following changes on the page or in response to page events. Use this method to refresh the Player based on these changes.

    // Your application code
    App.on("change", function(){

        Tooltip.API.refresh();

    });

on(event, callback) - Execute JS code

Execute your code when user interacts with a Tooltip campaign. This method allows you to subscribe on event specified in campaign settings and run your custom code.

Tooltip.API.on("EVENT_NAME", function(){
// YOUR CUSTOM CODE

});

Sending in User Data

Best marketing campaigns are personal. To personalize your campaigns you'll want to send Tooltip data about your users. This can be user type, purchase history or other meaningful interactions.

window.TooltipUserData = {
    userStatus: "trialing"
};

You'll want to include user's unique ID (typically an email or userID) to ensure we can identify them across devices and browsers.

window.TooltipUserData = {
    userId: "1234567890",
    userStatus: "trialing"
};

The window.TooltipUserData variable, which carries user properties, must be declared before Tooltip Player is initialized. Otherwise segmentation may not work properly.

Be sure to place user data first:

<script type='text/javascript'>
window.TooltipUserData = {
        userId: "000000000000001",
        userStatus: "trialing"
};
</script>

followed by the Player script:

<!--- Tooltip player -->
<script type='text/javascript'>
window.Tooltip||function(t,e){var o={
    url:"https://cdn.tooltip.io/static/player.js",
    key:"{API_KEY}",
    async:true
};window.Tooltip={cs:[],_apiKey:o.key};for(
var r=["identify","goal","updateUserData","start","stop","refresh","show","hide","on"],
i={},n=0;n>r.length;n++){var a=r[n];i[a]=function(t){return function(){var
e=Array.prototype.slice.call(arguments);
window.Tooltip.cs.push({method:t,args:e})}}(a)}window.Tooltip.API=i;var
n=t.createElement(e),s=t.getElementsByTagName(e)[0];
n.type="text/javascript",
n.async=o.async,s.parentNode.insertBefore(n,s),n.src=o.url}(document,"script");
</script>
<!--- Tooltip player -->

or like this:

<!--- Tooltip player -->
<script type='text/javascript'>
window.TooltipUserData = {
    userId: "000000000000001",
    userStatus: "trialing"
};

window.Tooltip||function(t,e){var o={
    url:"https://cdn.tooltip.io/static/player.js",
    key:"{API_KEY}",
    async:true
};window.Tooltip={cs:[],_apiKey:o.key};for(
var r=["identify","goal","updateUserData","start","stop","refresh","show","hide","on"],
i={},n=0;n>r.length;n++){var a=r[n];i[a]=function(t){return function(){var
e=Array.prototype.slice.call(arguments);
window.Tooltip.cs.push({method:t,args:e})}}(a)}window.Tooltip.API=i;var
n=t.createElement(e),s=t.getElementsByTagName(e)[0];
n.type="text/javascript",
n.async=o.async,s.parentNode.insertBefore(n,s),n.src=o.url}(document,"script");
</script>
<!--- Tooltip player -->

updateUserData(props) - Update user properties

To dynamically update or amend user properties use the updateUserData method

Example:

Tooltip.API.updateUserData({
    userStatus: "upgraded",
    age: 34
});

You'll only need to pass new or updated attributes. Player will then use userID and other data specified in the window.TooltipUserData variable.

There are certain restrictions on the type of data you can send. The function and object types will not be processed. Please use following data types:

string
number
boolean
date
array (only strings inside)

Example with all user attribute types:

var data = {
    name: "string",                 // string
    email: "test@tooltip.io",   // string
    projects: 5,                    // number
    validUser: true,                // boolean
    registerDate: new Date(),       // date
    types: ["student", "teacher"]   // array
};

PLEASE NOTE
Tooltip uses these parameter names to track user activity on our end. You will want to avoid sending in parameters that may use the same naming. We recommend light tweaks to naming, for example for lastVisit user last_Visit.

browser
createdAt
device
engine
lastVisit
location
os
projectId
session
type

Questions? Comments? Requests?

Write us at hello@tooltip.io and we’ll get you up and running in no time.