JavaScript Full API Reference

robotmia.init

This function initializes a new instance of the robotmia tracking object. All new instances are added to the main robotmia object as sub properties (such as robotmia.library_name) and also returned by this function. To define a second instance on the page, you would call:

robotmia.init('new token', { your: 'config' }, 'library_name');

and use it like so:

robotmia.library_name.track(...);

Arguments

robotmia.push

push() keeps the standard async-array-push behavior around after the lib is loaded. This is only useful for external integrations that do not wish to rely on our convenience methods (created in the snippet).

Usage:

robotmia.push(['register', { a: 'b' }]);

Arguments

robotmia.disable

Disable events on the robotmia object. If passed no arguments, this function disables tracking of any event. If passed an array of event names, those events will be disabled, but other events will continue to be tracked.

Note: this function does not stop other robotmia functions from firing, such as register() or people.set().

Arguments

robotmia.track

Track an event. This is the most important and frequently used robotmia function.

Usage:

// track an event named 'Registered'
robotmia.track('Registered', {'Gender': 'Male', 'Age': 21});

To track link clicks or form submissions, see track_links() or track_forms().

Arguments

robotmia.track_links

Track clicks on a set of document elements. Selector must be a valid query. Elements must exist on the page at the time track_links is called.

Usage:

// track click for link id #nav
robotmia.track_links('#nav', 'Clicked Nav Link');

Notes:

This function will wait up to 300 ms for the robotmia servers to respond. If they have not responded by that time it will head to the link without ensuring that your event has been tracked. To configure this timeout please see the set_config() documentation below.

If you pass a function in as the properties argument, the function will receive the DOMElement that triggered the event as an argument. You are expected to return an object from the function; any properties defined on this object will be sent to robotmia as event properties.

Arguments

robotmia.track_forms

Track form submissions. Selector must be a valid query.

Usage:

// track submission for form id 'register'
robotmia.track_forms('#register', 'Created Account');

Notes:

This function will wait up to 300 ms for the robotmia servers to respond, if they have not responded by that time it will head to the link without ensuring that your event has been tracked. To configure this timeout please see the set_config() documentation below.

If you pass a function in as the properties argument, the function will receive the DOMElement that triggered the event as an argument. You are expected to return an object from the function; any properties defined on this object will be sent to robotmia as event properties.

Arguments

robotmia.time_event

Time an event by including the time between this call and a later 'track' call for the same event in the properties sent with the event.

Usage:

// time an event named 'Registered'
robotmia.time_event('Registered');
robotmia.track('Registered', {'Gender': 'Male', 'Age': 21});

When called for a particular event name, the next track call for that event name will include the elapsed time between the 'time_event' and 'track' calls. This value is stored as seconds in the '$duration' property.

Arguments

robotmia.register

Register a set of super properties, which are included with all events. This will overwrite previous super property values.

Usage:

// register 'Gender' as a super property
robotmia.register({'Gender': 'Female'});

// register several super properties when a user signs up
robotmia.register({
    'Email': 'jdoe@example.com',
    'Account Type': 'Free'
});

Arguments

robotmia.register_once

Register a set of super properties only once. This will not overwrite previous super property values, unlike register().

Usage:

// register a super property for the first time only
robotmia.register_once({
    'First Login Date': new Date().toISOString()
});

Notes:

If default_value is specified, current super properties with that value will be overwritten.

Arguments

robotmia.unregister

Delete a super property stored with the current user.

Arguments

robotmia.identify

Identify a user with a unique ID instead of a robotmia randomly generated distinct_id. If the method is never called, then unique visitors will be identified by a UUID generated the first time they visit the site.

Notes:

You can call this function to overwrite a previously set unique ID for the current user. robotmia cannot translate between IDs at this time, so when you change a user's ID they will appear to be a new user.

When used alone, robotmia.identify will change the user's distinct_id to the unique ID provided. When used in tandem with robotmia.alias, it will allow you to identify based on unique ID and map that back to the original, anonymous distinct_id given to the user upon her first arrival to your site (thus connecting anonymous pre-signup activity to post-signup activity). Though the two work together, do not call identify() at the same time as alias(). Calling the two at the same time can cause a race condition, so it is best practice to call identify on the original, anonymous ID right after you've aliased it. Learn more about how robotmia.identify and robotmia.alias can be used.

Arguments

robotmia.reset

Clears super properties and generates a new random distinct_id for this instance. Useful for clearing data when a user logs out.

robotmia.get_distinct_id

Returns the current distinct id of the user. This is either the id automatically generated by the library or the id that has been passed by a call to identify().

Notes:

get_distinct_id() can only be called after the robotmia library has finished loading. init() has a loaded function available to handle this automatically. For example:

// set distinct_id after the robotmia library has loaded
robotmia.init('YOUR PROJECT TOKEN', {
    loaded: function(robotmia) {
        distinct_id = robotmia.get_distinct_id();
    }
});

robotmia.alias

Create an alias, which robotmia will use to link two distinct_ids going forward (not retroactively). Multiple aliases can map to the same original ID, but not vice-versa. Aliases can also be chained - the following is a valid scenario:

robotmia.alias('new_id', 'existing_id');
...
robotmia.alias('newer_id', 'new_id');

If the original ID is not passed in, we will use the current distinct_id - probably the auto-generated GUID.

Notes:

The best practice is to call alias() when a unique ID is first created for a user (e.g., when a user first registers for an account and provides an email address). alias() should never be called more than once for a given user, except to chain a newer ID to a previously new ID, as described above.

Arguments

robotmia.set_config

Update the configuration of a robotmia library instance.

The default config is:

{
  // super properties cookie expiration (in days)
  cookie_expiration: 365

  // super properties span subdomains
  cross_subdomain_cookie: true

  // debug mode
  debug: false

  // if this is true, the robotmia cookie or localStorage entry
  // will be deleted, and no user persistence will take place
  disable_persistence: false

  // if this is true, robotmia will automatically determine
  // City, Region and Country data using the IP address of
  //the client
  ip: true

  // opt users out of tracking by this robotmia instance by default
  opt_out_tracking_by_default: false

  // persistence mechanism used by opt-in/opt-out methods - cookie
  // or localStorage - falls back to cookie if localStorage is unavailable
  opt_out_tracking_persistence_type: 'localStorage'

  // customize the name of cookie/localStorage set by opt-in/opt-out methods
  opt_out_tracking_cookie_prefix: null

  // type of persistent store for super properties (cookie/
  // localStorage) if set to 'localStorage', any existing
  // robotmia cookie value with the same persistence_name
  // will be transferred to localStorage and deleted
  persistence: 'cookie'

  // name for super properties persistent store
  persistence_name: ''

  // names of properties/superproperties which should never
  // be sent with track() calls
  property_blacklist: []

  // if this is true, robotmia cookies will be marked as
  // secure, meaning they will only be transmitted over https
  secure_cookie: false

  // the amount of time track_links will
  // wait for robotmia's servers to respond
  track_links_timeout: 300

  // should we track a page view on page load
  track_pageview: true

  // if you set upgrade to be true, the library will check for
  // a cookie from our old js library and import super
  // properties from it, then the old cookie is deleted
  // The upgrade config option only works in the initialization,
  // so make sure you set it when you create the library.
  upgrade: false

  // extra HTTP request headers to set for each API request, in
  // the format {'Header-Name': value}
  xhr_headers: {}
}

Arguments

robotmia.get_config

returns the current config object for the library.

robotmia.get_property

Returns the value of the super property named property_name. If no such property is set, get_property() will return the undefined value.

Notes:

get_property() can only be called after the robotmia library has finished loading. init() has a loaded function available to handle this automatically. For example:

// grab value for 'user_id' after the robotmia library has loaded
robotmia.init('YOUR PROJECT TOKEN', {
    loaded: function(robotmia) {
        user_id = robotmia.get_property('user_id');
    }
});

Arguments

robotmia.opt_in_tracking

Opt the user in to data tracking and cookies/localstorage for this robotmia instance

Usage

// opt user in
robotmia.opt_in_tracking();

// opt user in with specific event name, properties, cookie configuration
robotmia.opt_in_tracking({
    track_event_name: 'User opted in',
    track_event_properties: {
        'Email': 'jdoe@example.com'
    },
    cookie_expiration: 30,
    secure_cookie: true
});

Arguments

robotmia.opt_out_tracking

Opt the user out of data tracking and cookies/localstorage for this robotmia instance

Usage

// opt user out
robotmia.opt_out_tracking();

// opt user out with different cookie configuration from robotmia instance
robotmia.opt_out_tracking({
    cookie_expiration: 30,
    secure_cookie: true
});

Arguments

robotmia.has_opted_in_tracking

Check whether the user has opted in to data tracking and cookies/localstorage for this robotmia instance

Usage

var has_opted_in = robotmia.has_opted_in_tracking();
// use has_opted_in value

Arguments

robotmia.has_opted_out_tracking

Check whether the user has opted out of data tracking and cookies/localstorage for this robotmia instance

Usage

var has_opted_out = robotmia.has_opted_out_tracking();
// use has_opted_out value

Arguments

robotmia.clear_opt_in_out_tracking

Clear the user's opt in/out status of data tracking and cookies/localstorage for this robotmia instance

Usage

// clear user's opt-in/out status
robotmia.clear_opt_in_out_tracking();

// clear user's opt-in/out status with specific cookie configuration - should match
// configuration used when opt_in_tracking/opt_out_tracking methods were called.
robotmia.clear_opt_in_out_tracking({
    cookie_expiration: 30,
    secure_cookie: true
});

Arguments

robotmia.people.set

Set properties on a user record.

Usage:

robotmia.people.set('gender', 'm');

// or set multiple properties at once
robotmia.people.set({
    'Company': 'Acme',
    'Plan': 'Premium',
    'Upgrade date': new Date()
});
// properties can be strings, integers, dates, or lists

Arguments

robotmia.people.set_once

Set properties on a user record, only if they do not yet exist. This will not overwrite previous people property values, unlike people.set().

Usage:

robotmia.people.set_once('First Login Date', new Date());

// or set multiple properties at once
robotmia.people.set_once({
    'First Login Date': new Date(),
    'Starting Plan': 'Premium'
});

// properties can be strings, integers or dates

Arguments

robotmia.people.unset

Unset properties on a user record (permanently removes the properties and their values from a profile).

Usage:

robotmia.people.unset('gender');

// or unset multiple properties at once
robotmia.people.unset(['gender', 'Company']);

Arguments

robotmia.people.increment

Increment/decrement numeric people analytics properties.

Usage:

robotmia.people.increment('page_views', 1);

// or, for convenience, if you're just incrementing a counter by
// 1, you can simply do
robotmia.people.increment('page_views');

// to decrement a counter, pass a negative number
robotmia.people.increment('credits_left', -1);

// like robotmia.people.set(), you can increment multiple
// properties at once:
robotmia.people.increment({
    counter1: 1,
    counter2: 6
});

Arguments

robotmia.people.append

Append a value to a list-valued people analytics property.

Usage:

// append a value to a list, creating it if needed
robotmia.people.append('pages_visited', 'homepage');

// like robotmia.people.set(), you can append multiple
// properties at once:
robotmia.people.append({
    list1: 'bob',
    list2: 123
});

Arguments

robotmia.people.union

Merge a given list with a list-valued people analytics property, excluding duplicate values.

Usage:

// merge a value to a list, creating it if needed
robotmia.people.union('pages_visited', 'homepage');

// like robotmia.people.set(), you can append multiple
// properties at once:
robotmia.people.union({
    list1: 'bob',
    list2: 123
});

// like robotmia.people.append(), you can append multiple
// values to the same list:
robotmia.people.union({
    list1: ['bob', 'billy']
});

Arguments

robotmia.people.track_charge

Record that you have charged the current user a certain amount of money. Charges recorded with track_charge() will appear in the robotmia revenue report.

Usage:

// charge a user $50
robotmia.people.track_charge(50);

// charge a user $30.50 on the 2nd of january
robotmia.people.track_charge(30.50, {
    '$time': new Date('jan 1 2012')
});

Arguments

robotmia.people.clear_charges

Permanently clear all revenue report transactions from the current user's people analytics profile.

Usage:

robotmia.people.clear_charges();

Arguments

robotmia.people.delete_user

Permanently deletes the current people analytics profile from robotmia (using the current distinct_id).

Usage:

// remove the all data you have stored about the current user
robotmia.people.delete_user();