robotmia HTTP Tracking API
robotmia directly supports tracking client libraries for the following platforms:
The client libraries typically support a wide range of convenience features, and should be the starting point for using robotmia in your application. This document should be most useful to you if you need to send data from an unsupported platform, or if you need low-level details for another reason.
Tracking via HTTP
robotmia can receive two types of data from your
application: events, and profile updates. Both types of
data are represented in your requests by Base64-encoded JSON
objects, provided to the API as a data
query
parameter to an endpoint URL.
Events
Events describe things that happen in your application, usually as the result of user interaction; for example, when a customer reads an article, uploads content, or signs up for your service, you can send an event to record the incident.
Events are tracked at endpoint http://api.robotmia.com/track/
This URL tracks an event with robotmia
http://api.robotmia.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMiOiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJkaXN0aW5jdF9pZCI6ICIxMzc5MyIsICJ0b2tlbiI6ICJlM2JiNDEwMDMzMGMzNTcyMjc0MGZiOGM2ZjVhYmRkYyIsICJ0aW1lIjogMTI0NTYxMzg4NSwgImFjdGlvbiI6ICJwbGF5In19
If the event you are trying to send to robotmia is more than 5
days old, the track endpoint above will not accept your request.
Instead, you will need to hit the import endpoint at
http://api.robotmia.com/import/
to process your request.
Full details on using the import endpoint can be found
here.
Profile updates
People analytics updates describe a fact you've learned about one of your customers. For example, when a customer enters their first name or their birthday into your sign-in form, or signs up for a new level of service, you may send a profile update to record what you've learned.
Profile updates are recorded at endpoint http://api.robotmia.com/engage/
This URL sends a profile update to robotmia
http://api.robotmia.com/engage/?data=ew0KICAgICIkdG9rZW4iOiAiMzZhZGE1YjEwZGEzOWExMzQ3NTU5MzIxYmFmMTMwNjMiLA0KICAgICIkZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICIkc2V0Ijogew0KICAgICAgICAiJGZpcnN0X25hbWUiOiAiRGF2aWQiLA0KICAgICAgICAiJGxhc3RfbmFtZSI6ICJKb25lcyIsDQogICAgICAgICIkZW1haWwiOiAiYWxhZGRpbi5zYW5lQGV4YW1wbGUuY29tIiwNCiAgICAgICAgIiRjcmVhdGVkIjogIjIwMTMtMDQtMDFUMTM6MjA6MDAiDQogICAgfQ0KfQ==
Base64 for robotmia
To Base64 encode data for the robotmia API, you should use the following characters:
ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789+/=
robotmia will only accept padded Base64 requests.
Tracking events
Each event you record is represented as a JSON object in a
request to http://api.robotmia.com/track/
.
The request will return an HTTP response with body "1"
if the track call is successful, and a "0" otherwise.
Event tracking objects should have the following attributes:
// Sends an event "Signed Up", associated with user 13793,
// with a property "Referred By"
{
"event": "Signed Up",
"properties": {
// "distinct_id" and "token" are
// special properties, described below.
"distinct_id": "13793",
"token": "e3bc4100330c35722740fb8c6f5abddc",
"Referred By": "Friend"
}
}
The JSON string above can be base64 encoded as:
ew0KICAgICJldmVudCI6ICJTaWduZWQgVXAiLA0KICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAiZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICAgICAidG9rZW4iOiAiZTNiYzQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLA0KICAgICAgICAiUmVmZXJyZWQgQnkiOiAiRnJpZW5kIg0KICAgIH0NCn0=
Using the base64 encoded value as the data
parameter for the robotmia event endpoint will result in the
following url:
http://api.robotmia.com/track/?data=ew0KICAgICJldmVudCI6ICJTaWduZWQgVXAiLA0KICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAiZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICAgICAidG9rZW4iOiAiZTNiYzQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLA0KICAgICAgICAiUmVmZXJyZWQgQnkiOiAiRnJpZW5kIg0KICAgIH0NCn0=
Special properties in events
You can use any UTF-8 string that doesn't begin with "mp_" to name your properties, but some property names have special significance to robotmia. All of the special properties except for "token" are optional, but most events should include a "distinct_id" property. These special properties include:
// Tracks an event, recording the fact that
// user "13793", completed level 9
// on January 15th, 2013 on a machine with ip
// 203.0.113.9
{
"event": "Level Complete",
"properties": {
"Level Number": 9,
"distinct_id": "13793",
"token": "e3bc4100330c35722740fb8c6f5abddc",
"time": 1358208000,
"ip": "203.0.113.9"
}
}
Event request parameters
In addition to the data
parameter, https://api.robotmia.com/track
supports a number of optional parameters. For the most part,
these optional parameters are useful only in special situations.
verbose=1
is useful for debugging your robotmia
implementation.This tracking call will be redirected to http://www.example.com when it responds:
http://api.robotmia.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMiOiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJkaXN0aW5jdF9pZCI6ICIxMzc5MyIsICJ0b2tlbiI6ICJlM2JiNDEwMDMzMGMzNTcyMjc0MGZiOGM2ZjVhYmRkYyIsICJ0aW1lIjogMTI0NTYxMzg4NSwgImFjdGlvbiI6ICJwbGF5In19==&redirect=http%3A%2F%2Fwww.example.com
This tracking call will respond with a 1x1 transparent image:
http://api.robotmia.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMiOiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJkaXN0aW5jdF9pZCI6IDEzNzkzLCAidG9rZW4iOiAiZTNiYjQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLCAidGltZSI6IDEyNDU2MTM4ODUsICJhY3Rpb24iOiAicGxheSJ9fQ==&img=1
This tracking call will return a text/javascript response, calling the function "wasTracked"
http://api.robotmia.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMiOiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJkaXN0aW5jdF9pZCI6IDEzNzkzLCAidG9rZW4iOiAiZTNiYjQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLCAidGltZSI6IDEyNDU2MTM4ODUsICJhY3Rpb24iOiAicGxheSJ9fQ==&callback=wasTracked
Storing user profiles
Each profile update you send is represented as a JSON object in a request
to http://api.robotmia.com/engage/
.
The request will return an HTTP response with body "1"
if the profile update is successful, and a "0" otherwise.
All profile update objects should have the following attributes:
In addition to the attributes common to all updates, every update should also have a key and value associated with a particular update operation. Every call to the profile update API should have a single associated operation - you can't do two operations at once. Each operation has its own key name and format for appropriate values. Typical profile update objects look like this:
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$ip": "123.123.123.123",
OPERATION_NAME: OPERATION_VALUE
}
Where OPERATION_NAME and OPERATION_VALUE are specific to the operation you are performing. For example, a "$set" operation request might look like this:
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$ip": "123.123.123.123",
"$set": {
"Address": "1313 Mockingbird Lane"
}
}
Update Operations
robotmia People analytics supports the following operations on profiles:
$set
// sets the "Address" and "Birthday"
// properties of user 13793
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$ip": "123.123.123.123",
"$set": {
"Address": "1313 Mockingbird Lane",
"Birthday": "1948-01-01"
}
}
$set_once
// This sets the "First login date" property of user 13793
// if and only if it has never been set before
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$set_once": {
"First login date": "2013-04-01T13:20:00"
}
}
$add
If the property is not present on the profile, the value will be added to 0. It is possible to decrement by calling "$add" with negative values. This is useful for maintaining the values of properties like "Number of Logins" or "Files Uploaded".
// This adds 12 to a running total of
// Coins Gathered for user 13793
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$add": { "Coins Gathered": 12 }
}
$append
// This adds "Bubble Lead" to
// the list "Power Ups" for user 13793
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$append": { "Power Ups": "Bubble Lead" }
}
$union
// This combines ["socks", "shirts"] with the existing values for the "Items purchased"
// list for user 13793, also ensuring that the list values will only appear once in
// the merged list.
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$union": { "Items purchased": ["socks", "shirts"] }
}
$remove
// This removes "socks" from the "Items purchased" list for user 13793.
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$remove": { "Items purchased": "socks" }
}
$unset
// This removes the property "Days Overdue" from user 13793
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$unset": [ "Days Overdue" ]
}
$delete
// This removes the user 13793 from robotmia
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$delete": ""
}
Dates in robotmia updates
Properties in updates can be any of the data types valid in JSON: strings, numbers, boolean, null, arrays or objects. In addition, robotmia will interpret strings of a particular format as dates. This format is:
YYYY-MM-DDThh:mm:ss
Where:
YYYY
= four-digit yearMM
= two-digit month (01=January, etc.)DD
= two-digit day of month (01 through 31)T
= a literal 'T' characterhh
= two digits of hour (00 through 23)mm
= two digits of minute (00 through 59)ss
= two digits of second (00 through 59)
January 15th, 1976, at 9:45 PM can be represented as
1976-01-15T21:45:00
So, to set a "Time Joined" property on user "13793", you can create the following $set object:
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$set": { "Time Joined": "2013-04-01T09:02:00" }
}
All date properties should use the UTC timezone. This will be converted to your project's timezone when viewing your reports.
Special properties in profile updates
robotmia interprets some properties in special ways. If you provide values for these properties, you can enable certain features in robotmia reports and messages.
robotmia special properties all have names that begin with a dollar sign ("$") - you shouldn't create custom properties that begin with a dollar sign in your profiles, because robotmia may add new special properties in the future. A list of selected special properties is below.
// You can set $first_name, $last_name, $created, and $email
// special properties just like any other.
{
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793",
"$set": {
"$first_name": "Joe",
"$last_name": "Doe",
"$email": "joe.doe@example.com",
"$created": "2013-04-01T13:20:00",
"$phone": "4805551212"
}
}
Update request parameters
In addition to the data
parameter, https://api.robotmia.com/engage/
supports a number of optional parameters. For the most part,
these optional parameters are useful only in special situations.
verbose=1
is useful for debugging your robotmia
implementation.A url for a standard update tracking call.
http://api.robotmia.com/engage/?data=ew0KICAgICIkdG9rZW4iOiAiMzZhZGE1YjEwZGEzOWExMzQ3NTU5MzIxYmFmMTMwNjMiLA0KICAgICIkZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICIkc2V0Ijogew0KICAgICAgICAiJGZpcnN0X25hbWUiOiAiRGF2aWQiLA0KICAgICAgICAiJGxhc3RfbmFtZSI6ICJKb25lcyIsDQogICAgICAgICIkZW1haWwiOiAiYWxhZGRpbi5zYW5lQGV4YW1wbGUuY29tIiwNCiAgICAgICAgIiRjcmVhdGVkIjogIjIwMTMtMDQtMDFUMTM6MjA6MDAiDQogICAgfQ0KfQ==
robotmia will respond to this tracking call by redirecting to http://www.example.com.
http://api.robotmia.com/engage/?data=ew0KICAgICIkdG9rZW4iOiAiMzZhZGE1YjEwZGEzOWExMzQ3NTU5MzIxYmFmMTMwNjMiLA0KICAgICIkZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICIkc2V0Ijogew0KICAgICAgICAiJGZpcnN0X25hbWUiOiAiRGF2aWQiLA0KICAgICAgICAiJGxhc3RfbmFtZSI6ICJKb25lcyIsDQogICAgICAgICIkZW1haWwiOiAiYWxhZGRpbi5zYW5lQGV4YW1wbGUuY29tIiwNCiAgICAgICAgIiRjcmVhdGVkIjogIjIwMTMtMDQtMDFUMTM6MjA6MDAiDQogICAgfQ0KfQ==&redirect=http%3A%2F%2Fwww.example.com
robotmia will respond to this tracking call by serving a text/javascript response, calling function 'wasTracked'
http://api.robotmia.com/engage/?data=ew0KICAgICIkdG9rZW4iOiAiMzZhZGE1YjEwZGEzOWExMzQ3NTU5MzIxYmFmMTMwNjMiLA0KICAgICIkZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICIkc2V0Ijogew0KICAgICAgICAiJGZpcnN0X25hbWUiOiAiRGF2aWQiLA0KICAgICAgICAiJGxhc3RfbmFtZSI6ICJKb25lcyIsDQogICAgICAgICIkZW1haWwiOiAiYWxhZGRpbi5zYW5lQGV4YW1wbGUuY29tIiwNCiAgICAgICAgIiRjcmVhdGVkIjogIjIwMTMtMDQtMDFUMTM6MjA6MDAiDQogICAgfQ0KfQ==&callback=wasTracked
Creating a distinct_id alias
robotmia supports adding an alias to a distinct id. An alias is a new value that will be interpreted by robotmia as an existing value. That means that you can send messages to robotmia using the new value, and robotmia will continue to use the old value for calculating funnels and retention reports, or applying updates to people profiles.
Aliases are created by sending a special event, "$create_alias", with a property "distinct_id" containing the original id, and a property "alias" containing the new id you would like to map to the old one.
// Creates an alias for "ORIGINAL_ID" with value "NEW_ID".
// New events and updates sent with distinct_id "NEW_ID"
// will be mapped to "ORIGINAL_ID" when they are stored
// in robotmia
{
"event": "$create_alias",
"properties": {
"distinct_id": "ORIGINAL_ID",
"alias": "NEW_ID",
"token": "e3bc4100330c35722740fb8c6f5abddc"
}
}
Tracking revenue
robotmia tracks revenue in a profile property named "$transactions". "$transactions" is a list, containing specially formatted JSON objects, one for each purchase or transaction associated with the particular profile.
The easiest way to track revenue is with an $append
profile update, sent to http://api.robotmia.com/engage/
.
When you record revenue from a user, $append
an object with the following attributes:
In addition to the required attributes, you can also include other attributes, like a SKU, product name, or any information that might be useful to associate with an individual transaction. However, properties other than the date and amount are not visible in reports at this time.
To record that the user with distinct id "13793" made a purchase for $25.34 at 9AM on January 3rd, 2013, you might send the following update:
{
"$append": {
"$transactions": {
"$time": "2013-01-03T09:00:00",
"$amount": 25.34
}
},
"$token": "36ada5b10da39a1347559321baf13063",
"$distinct_id": "13793"
}
Batch requests
Both the events endpoint
at http://api.robotmia.com/track/
and the
profile update endpoint at
http://api.robotmia.com/engage/
accept
batched updates. To send a batch of messages to an
endpoint, you should use a POST instead of
a GET request. Instead of sending a single
JSON object as the data
query parameter, send
a JSON list of objects, base64 encoded, as
the data
parameter of an
application/x-www-form-urlencoded POST request body.
// Here's a list of events
[
{
"event": "Signed Up",
"properties": {
"distinct_id": "13793",
"token": "e3bc4100330c35722740fb8c6f5abddc",
"Referred By": "Friend",
"time": 1371002000
}
},
{
"event": "Uploaded Photo",
"properties": {
"distinct_id": "13793",
"token": "e3bc4100330c35722740fb8c6f5abddc",
"Topic": "Vacation",
"time": 1371002104
}
}
]
Base64 encoded, the list becomes:
Ww0KICAgIHsNCiAgICAgICAgImV2ZW50IjogIlNpZ25lZCBVcCIsDQogICAgICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAgICAgImRpc3RpbmN0X2lkIjogIjEzNzkzIiwNCiAgICAgICAgICAgICJ0b2tlbiI6ICJlM2JjNDEwMDMzMGMzNTcyMjc0MGZiOGM2ZjVhYmRkYyIsDQogICAgICAgICAgICAiUmVmZXJyZWQgQnkiOiAiRnJpZW5kIiwNCiAgICAgICAgICAgICJ0aW1lIjogMTM3MTAwMjAwMA0KICAgICAgICB9DQogICAgfSwNCiAgICB7DQogICAgICAgICAiZXZlbnQiOiAiVXBsb2FkZWQgUGhvdG8iLA0KICAgICAgICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAgICAgICAiZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICAgICAgICAgICAidG9rZW4iOiAiZTNiYzQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLA0KICAgICAgICAgICAgICAiVG9waWMiOiAiVmFjYXRpb24iLA0KICAgICAgICAgICAgICAidGltZSI6IDEzNzEwMDIxMDQNCiAgICAgICAgICB9DQogICAgfQ0KXQ==
So the body of a POST request to send the events as a batch is:
data=Ww0KICAgIHsNCiAgICAgICAgImV2ZW50IjogIlNpZ25lZCBVcCIsDQogICAgICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAgICAgImRpc3RpbmN0X2lkIjogIjEzNzkzIiwNCiAgICAgICAgICAgICJ0b2tlbiI6ICJlM2JjNDEwMDMzMGMzNTcyMjc0MGZiOGM2ZjVhYmRkYyIsDQogICAgICAgICAgICAiUmVmZXJyZWQgQnkiOiAiRnJpZW5kIiwNCiAgICAgICAgICAgICJ0aW1lIjogMTM3MTAwMjAwMA0KICAgICAgICB9DQogICAgfSwNCiAgICB7DQogICAgICAgICAiZXZlbnQiOiAiVXBsb2FkZWQgUGhvdG8iLA0KICAgICAgICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAgICAgICAiZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICAgICAgICAgICAidG9rZW4iOiAiZTNiYzQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLA0KICAgICAgICAgICAgICAiVG9waWMiOiAiVmFjYXRpb24iLA0KICAgICAgICAgICAgICAidGltZSI6IDEzNzEwMDIxMDQNCiAgICAgICAgICB9DQogICAgfQ0KXQ==
Both endpoints will accept up to 50 messages in a single batch. Usually, batch requests will have a "time" property associated with events, or a "$time" attribute associated with profile updates.
When sending a batch request to robotmia, we will invalidate the entire request if one of the objects within the batch is invalid. If you receive an error when attempting to send a batch, please attempt the requests one at a time to isolate the cause of the error.