API Documentation - medullan/navocat-collector GitHub Wiki
COMMANDS
- IDENTIFY
- PROFILE
- PAGE
- TRACK
- ENDSESSION
OVERVIEW
Every command in the API can be accessed through one of two means: a JSON post or a GIF get request.
A POST request in JSON format can be sent to the JSON version of the command route. This means is intended for server-side code. The request parameters can be encoded in the query string or included in the post body.
Alternately, a GET request can be made to the GIF version of the command route. This method is preferred for client-side code, as there are no cross-domain permission issues. The response in the case of the GIF route will be a 1x1 clear pixel GIF image, and the response may also contain a first-party cookie with the user’s analytics profile id.
Every request except endsession must contain a dataset token. This value indicates the dataset to which the analytics event should be recorded. Any request omitting the dataset token will get an error response, and the event will not be recorded.
All the endpoints will return a non 200 http code if required parameters are missing, or an internal error occurs. It's a best practice to validate these http codes on the client.
A client_id is generated for all http calls to ensure the availability of this id to assist with session unification.
It's highly recommended to read the Navocat Collector Workflow Document for context on the order in which the following APIs should be called in practice.
API Summary
IDENTIFY
- POST /identify.json
- GET /identify.gif
Stores identifying info for any user, and returns an analytics profile id for that user, which is used in all subsequent calls.
PROFILE
- POST /profile.json
- GET /profile.gif
Stores profile info for any user, which is added to that user’s subsequent analytics events.
PAGE
- POST /page.json
- GET /page.gif
Records a web page view, persists the hit to disk and google analytics.
TRACK
- POST /track.json
- GET /track.gif
Records a user interaction of any other type, persists the hit to disk and google analytics.
IDENTIFY
- POST /meda/identify.json
- GET /meda/identify.gif
Example
POST /meda/identify.json
{
"dataset":"b0645ee624fae74a77207ae8868cf1c2",
"member_id":"100"
}
GET /meda/identify.gif?dataset=b0645ee624fae74a77207ae8868cf1c2&member_id=100
Parameters
| Parameter | Required | Description |
|---|---|---|
| dataset | REQUIRED | The dataset in which the user should be looked up or recorded. |
| member_id | REQUIRED | A unique identifier for the user |
Description
The IDENTIFY command is used to uniquely identify a user to the analytics system. It is typically used as a user logs in, or on the first page view. The response to the IDENTIFY command is a Meda profile_id.
If the user matching the given params is found in the dataset, then the user’s profile id is returned. If the user does not yet exist, then a profile is created and the new profile_id is returned.
Instead of returning the profile_id, the identify.gif response will set the profile_id in a first-party cookie. This cookie is used automatically by any subsequent calls to page.gif or track.gif.
PROFILE
- POST /meda/profile.json
- GET /meda/profile.gif
Example
POST /meda/profile.json
{
"dataset":"b0645ee624fae74a77207ae8868cf1c2",
"profile_id:"1a95b992c3f111e3af1544fb42fffe8c",
"gender":"male",
"health_segment"="healthy_engaged"
}
GET /meda/profile.gif?dataset=b0645ee624fae74a77207ae8868cf1c2&gender=male&health_segment=healthy_engaged
Parameters
| Parameter | Required | Description |
|---|---|---|
| dataset | REQUIRED | The dataset to record the profile data |
| profile_id | REQUIRED (JSON) or FROM COOKIE (GIF) | The user profile to record the data, obtained from the IDENTIFY call |
| {profile_attribute} | OPTIONAL (many) | All other params add attributes to the user profile |
Description
The PROFILE command is used to embellish each user in the dataset with profile attributes.
The data added to each profile is included in each analytic event by that user.
PAGE
- POST /meda/page.json
- GET /meda/page.gif
Example
POST /meda/page.json
{
"dataset":"b0645ee624fae74a77207ae8868cf1c2",
"profile_id":"1a95b992c3f111e3af1544fb42fffe8c",
"client_id":"4a953492c32511e3a34546b42ff6e82",
"title":"Home",
"hostname":"http://www.example.com",
"path":"/index.html"
}
GET /meda/page.gif?dataset=b0645ee624fae74a77207ae8868cf1c2&profile_id=1a95b992c3f111e3af1544fb42fffe8c&client_id=4a953492c32511e3a34546b42ff6e82&title=Home&hostname=http%3A%2F%2Fwww.example.com&path=%2Findex.html
Parameters
| Parameter | Required | Description |
|---|---|---|
| client_id | REQUIRED (JSON) or FROM COOKIE (GIF) | A client Identifier so GA can identify your session |
| hostname | REQUIRED | Web page host. Recorded as “Hostname” in GA |
| path | REQUIRED | Web page path (without host). Recorded as “Path” in GA |
| profile_id | OPTIONAL (JSON) or FROM COOKIE (GIF) | The user profile for which the hit is recorded. Used to identify your profile information in the collector and distinguish between a new existing user session and a totally new user. Saved as user_id in GA however it is not a visible field. |
| title | OPTIONAL | Web page title, usually the document title, but can also be any descriptive name. Recorded as “Descriptive Title” in GA |
| referrer | OPTIONAL | Optional referring page path, defaulting to the request’s HTTP_REFERER header. Recorded as “Referrer” in GA |
| user_ip | OPTIONAL | Optional user IP address, defaulting to the request’s REMOTE_ADDR header. Recorded as “User IP Address” in GA, and used to geo |
| user_agent | OPTIONAL | Optional user agent, defaulting to the request’s HTTP_USER_AGENT header. |
| user_language | OPTIONAL | User browser language. Recorded as “User language” in GA |
| screen_depth | OPTIONAL | User monitor color depth. Recorded as “Screen depth” in GA |
| screen_resolution | OPTIONAL | User screen resolution. Recorded as “Screen resolution” in GA |
The PAGE command records a "page view” type hit, corresponding to a single page load.
TRACK
- POST /meda/track.json
- GET /meda/track.gif
Example
POST /meda/track.json
{
"dataset":"b0645ee624fae74a77207ae8868cf1c2",
"profile_id":"1a95b992c3f111e3af1544fb42fffe8c",
"client_id":"4a953492c32511e3a34546b42ff6e82",
"category":"my_campaign",
"action":"survey_completed",
"label":"satisfaction_survey",
"value":"90"
}
GET /meda track.gif?dataset=b0645ee624fae74a77207ae8868cf1c2&profile_id=1a95b992c3f111e3af1544fb42fffe8c&client_id=4a953492c32511e3a34546b42ff6e82&category=my_campaign&action=survey_completed&label=satisfaction_survey&value=90
Parameters
| Parameter | Required | Description |
|---|---|---|
| dataset | REQUIRED | The dataset to which the hit is recorded |
| profile_id | OPTIONAL (JSON) or FROM COOKIE (GIF) | The user profile for which the hit is recorded. Used to identify your profile information in the collector and distinguish between a new user session and a totally new user. Saved as user_id in GA however it is not a visible field. |
| client_id | REQUIRED (JSON) or FROM COOKIE (GIF) | A client Identifier so GA can identify your session |
| action | REQUIRED | The name of the action taken by the user that this event represents. Recorded as “Event action” in GA |
| category | REQUIRED | The high-level category of the recorded event. Recorded as “Event Category” in GA |
| label | OPTIONAL | A label for the action taken, often used to provide additional context. Recorded as “Event label” in GA |
| value | OPTIONAL | A numeric value associated with the event, if applicable, such as a dollar amount or a numeric score. Recorded as “Event value” in GA |
| title | OPTIONAL | Web page title, usually the document title, but can also be any descriptive name. Recorded as “Descriptive Title” in GA |
| hostname | OPTIONAL | Web page host. Recorded as “Hostname” in GA |
| path | OPTIONAL | Web page path (without host). Recorded as “Path” in GA |
| referrer | OPTIONAL | Optional referring page path, defaulting to the request’s HTTP_REFERER header. Recorded as “Referrer” in GA |
| user_ip | OPTIONAL | Optional user IP address, defaulting to the request’s REMOTE_ADDR header. Recorded as “User IP Address” in GA, and used to geo-locate the end user |
| user_agent | OPTIONAL | user agent, defaulting to the request’s HTTP_USER_AGENT header. Recorded as “User Agent” in GA, and used to derive device, OS, browser and version. |
| user_language | OPTIONAL | User browser language - Recorded as “User language” in GA |
| screen_depth | OPTIONAL | User monitor color depth. Recorded as “Screen depth” in GA |
| screen_resolution | OPTIONAL | User screen resolution. “Screen resolution” in GA |
The TRACK command is used to record an arbitrary event representing any action performed by an end user. This event is described by a high-level “category”, a specific “action”, a descriptive “label” that provides more context, and a numeric “value” if the event is measurable quantitatively.
ENDSESSION
- GET /meda/endsession.gif
Example
GET /meda/endsession.gif
Parameters
No parameters required
It removes an identified user session with the collector. Also, it returns a 1x1 clear GIF image.