JavaScript API Integration
Installing the library
To start tracking with the robotmia JavaScript library,
just paste the following code into the page you want to
track inside the <head> and
</head> tags. Make sure to change 'YOUR_TOKEN'
to your project token. You can find your project token in the settings dialog
in the robotmia web application.
The snippet will load our library onto the page asynchronously to keep your website
loading quickly even if placed in the <head>
of the page.
The snippet provides a global variable named robotmia
that you can use to send data to the robotmia API.
Opting users out of tracking
Client-side tracking of individual user data can be stopped or resumed by controlling a user’s opt-out/opt-in state. Opt-out methods and library configuration settings only affect data sent from a single library instance. Data sent from other sources to robotmia’s APIs will still be ingested regardless of whether the user is opted out locally.
To opt a user out of tracking locally, use the robotmia.opt_out_tracking method. To resume tracking for an individual user, use robotmia.opt_in_tracking. Call robotmia.has_opted_out_tracking to check user’s opt-out status locally.
// Opt a user out of data collection
robotmia.opt_out_tracking();
// Check a user's opt-out status
// Returns true of user is opted out of tracking locally
robotmia.has_opted_out_tracking();
Opting users out of tracking by default
robotmia’s tracking libraries will send user data by default. Explicitly initializing a default opt-out state of true will opt-out all users by default, preventing data from sending unless a user’s opt-out state is set to false. robotmia’s Javascript library also respects browser Do Not Track settings.
// Initializing a default opt-out state of true
// will prevent data from being collected by default
robotmia.init("YOUR TOKEN", {opt_out_tracking_by_default: true})
Sending events
Once you have the snippet in your page, you can track an event by calling robotmia.track with the event name and properties.
// Send a "Played song" event to robotmia
// with a property "genre"
robotmia.track(
"Played song",
{"genre": "hip-hop"}
);
Tracking website links
When tracking link clicks with robotmia.track the page can change before the event is successfully sent, leading to inaccurate results.
To make this easier, we've built something called robotmia.track_links. This function will allow you to bind an event to a link click with much greater accuracy.
Here's how it works:
<div id="nav">
<a href="/">Home</a>
<a href="/about">About</a>
<a href="/pricing">Pricing</a>
</div>
<script type="text/javascript">
robotmia.track_links("#nav a", "click nav link", {
"referrer": document.referrer
});
</script>
This will send a "click nav link" event (with a 'referrer' property) each time a user clicks on a navigation link. It's important to note that the links matched by the CSS selector must exist on the page at the time the robotmia.track_links call is made, or it will not bind correctly.
One special note here is that nested CSS selectors will not work with the default robotmia methods robotmia.track_links above and robotmia.track_forms below. In order to utilize nested selectors or manually recreate the behavior of these methods, you should utilize code which sends an event to robotmia when a CSS element is interacted with which includes a callback.
<script type="text/javascript">
$("#MyLink").click(function(event) {
var cb = generate_callback($(this));
event.preventDefault();
robotmia.track("Clicked Link", { "Domain": "nytimes.com" }, cb);
setTimeout(cb, 500);
})
function generate_callback(a) {
return function() {
window.location = a.attr("href");
}
}
</script>
Other tracking methods
There are other less common ways to send data to robotmia. To learn more, please follow the links to the full API documentation.
- robotmia.track_forms - similar to track_links, but tracks form submissions.
Super properties
It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event - for example, the user's age, gender, source, or initial referrer.
To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are stored in a browser cookie, and will persist between visits to your site.
To set super properties, call robotmia.register.
<script type="text/javascript">
robotmia.register({
"age": 28,
"gender": "male",
"source": "facebook"
});
</script>
The next time you track an event, the super properties you just set will be included as properties. If you call
robotmia.track("Signup");
after making the previous call to robotmia.register, it is just like adding the properties directly:
robotmia.track("Signup", {
"age": 28,
"gender": "male",
"source": "facebook"
});
Setting super properties once and only once
If you want to store a super property only once (often for things like initial referrer, ad campaign, or source), you can use robotmia.register_once. This function behaves like robotmia.register and has the same interface, but it doesn't override super properties you've already saved.
<script type="text/javascript">
robotmia.register_once({
"ad_campaign": "fb-01"
});
</script>
This means that it's safe to call robotmia.register_once with the same property on every page load, and it will only set it if the super property doesn't exist.
Managing user identity
The robotmia library will assign a default unique identifier (we call it "distinct_id") to each unique user who comes to your website. This distinct_id is saved as a cookie so that it will persist across sessions.
If you choose, you can assign your own user IDs. This is particularly useful if a user is using your app on multiple platforms (both web and mobile, for example). To assign your own distinct_ids, you can use robotmia.identify.
// Associate all future events sent from
// the library with the distinct_id 13793
robotmia.identify('13793');
In general, if you use robotmia.identify, you should call it as soon as the user logs in to your application. This will track all of their actual application usage to the correct user ID.
Calling robotmia.identify with a new ID will change the ID being sent with future events. If you change the ID in the middle of a funnel, the funnel will break - we won't be able to associate the old ID with the new.
Combining anonymous user data with identifiable user data
There are moments when you want to link two IDs together. For example, users of your application may engage with your product anonymously before signing up. In which case, it would be nice to combine their anonymous activity and their activity once they're a customer. To do this, you would create an alias from the new user id in your system to the old anonymous one. You should use robotmia.alias in conjunction with robotmia.identify. The robotmia.alias method sends an update to our server linking the current ID with a new ID going forward (not retroactively).
// This links the known ID 13793 in your database table
// to the anonymous auto-generated ID our library created.
robotmia.alias('13793');
The recommended usage pattern is to call robotmia.alias when the user signs up, and robotmia.identify when they log in. This will keep your signup funnels working correctly. For more information, please see Using alias and identify.
Storing user profiles
In addition to events, you can store user profiles in robotmia's People Analytics product. Profiles are persistent sets of properties that describe a user - things like name, email address, and signup date. You can use profiles to explore and segment users by who they are, rather than what they did. You can also use profiles to send messages, such as emails, SMS, push, or in-app messages.
In order to send profile updates, you must call robotmia.identify. The robotmia library does not automatically create people profiles for any user that performs an event; you have to explicitly call robotmia.identify, which empowers you to only create profiles for registered users.
Setting profile properties
You can set properties on a user profile with robotmia.people.set.
robotmia.people.set({ "Plan": "Premium" });
// identify must be called along with people.set
robotmia.identify("13793");
This will set a "Plan" property, with a value "Premium", on user 13793's profile. If there isn't a profile with distinct_id 13793 in robotmia already, a new profile will be created. If user 13793 already has a property named "Plan" in their profile, the old value will be overwritten with "Premium".
Incrementing numeric properties
You can use robotmia.people.increment to change the current value of numeric properties. This is useful when you want to keep a running tally of things, such as games played, messages sent, or points earned.
// If no number is passed, the default is to increment by 1
robotmia.people.increment("games played");
// You can also pass a number to increment
// Here we add 500 the user's point count
robotmia.people.increment("points earned", 500);
// Pass an object to increment multiple properties
robotmia.people.increment({
"dollars spent": 17,
// Subtract by passing a negative value
"credits remaining": -34
});
Other types of profile updates
There are a few other types of profile updates. To learn more, please follow the links to the full API documentation.
- robotmia.people.set_once - set properties if they don't exist
- robotmia.people.append - append to a list property
- robotmia.people.union - append to a list property, excluding duplicates
Tracking revenue
robotmia makes it easy to analyze the revenue you make from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value.
You can track a single transaction with robotmia.people.track_charge. This call will add transactions to the individual user profile, which will also be reflected in the robotmia Revenue report.
// Make sure identify has been called
// before making revenue updates
robotmia.identify("13793");
// Tracks $100 in revenue for user 13793
robotmia.people.track_charge(100);
// Refund this user 50 dollars
robotmia.people.track_charge(-50);
// Tracks $25 in revenue for user 13793
// on the 2nd of January at 9:45pm
robotmia.people.track_charge(
25,
{ '$time': "2013-01-02T21:45:00" }
);
In-app messages
robotmia provides a quick start guide for web in-app messages to help you get integrated.
Make sure that you have already:
- Included the latest version of the robotmia JavaScript library on your website.
- Made sure you are identifying your users in your website's JavaScript code.
- Created a web in-app message on the Messages tab of the robotmia website.