-
Notifications
You must be signed in to change notification settings - Fork 0
Event Ingest API
Welcome to the Data Cortex API version 1.
This API allows ingest of events into the Data Cortex analytics engine.
All calls are made on the standard data ingestion endpoint:
https://api.data-cortex.com
Calls to the API are made with a POST to the API endpoint.
POST /<org>/1/track?current_time=<time>
<org> - string - Should be replaced with the organization short name.
<time> - string - ISO 8601 date and time in UTC. This is the time the request is sent.
The request should contain a JSON body. The client should be sure to set the the Content-Type header to "application/json". The body is considered a "bundle". Each bundle can contain multiple events. The bundle has global properties and then a list of events.
The body should have the following structure:
{
/* global properties */
"api_key": "xxxx",
/* ... */
"events": [ ... ]
}
The events list must have at least one item in the list. It may have up to 100 items in the list.
The API responds with the following depending on the result.
Events have been successfully processed.
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 2
Date: Sun, 10 Nov 2013 04:24:17 GMT
OK
Bad request. Check with Data Cortex documentation and verify that you are sending all required fields and valid data types in those fields.
HTTP/1.1 400 Bad Request
Bad API key. Check with Data Cortex and verify your API key. Productions clients should treat this as a fatal error and remove all events queued.
HTTP/1.1 403 Forbidden
Internal server error. Clients should treat these as soft errors and resend the request.
HTTP/1.1 500 Internal Server Error
Example requests here.
The bundle has the following global properties.
api_key - string - The api key specific to this application. Applications can have more than 1 API key, but can not be shared between applications.
app_ver - string - The version of the application. 16 character maximum.
server_ver - string - (optional) The version of the server. 16 character maximum.
config_ver - string - (optional) The version of the configuration. 16 character maximum.
user_tag - string - (optional) A unique ID for the user. Should only be inserted if the application is able to determine a unique stable user identity. User tags should be unique per user across the organization. If they are not unique for a particular organization, they should be prefixed per application to make them unique. 62 character maximum. Also see user anonymized data.
For this and all other optional tags (facebook_tag, twitter_tag, etc.): If the value is not available, it must be omitted, otherwise all users associated with the placeholder value will be mapped to the same user_id.
facebook_tag - string - (optional) The facebook ID of the user. 62 character maximum. Also see user anonymized data.
twitter_tag - string - (optional) The twitter ID of the user. 62 character maximum. Also see user anonymized data.
google_tag - string - (optional) The google ID of the user. 62 character maximum. Also see user anonymized data.
game_center_tag - string - (optional) The iOS Game Center ID. Also see user anonymized data.
device_tag - string - A unique ID for the device. IDFA for iOS, MAC Address for Android, a randomly generated value for the browser stored in a cookie or localStorage. 62 character maximum. Also see user anonymized data.
If no device_tag is available (for example, on Amazon Kindle devices), the the client should create unique tag to use as the device_tag. The generated device_tag should be stored for future use, so a stable device_tag can be sent with all requests originating from that device.
device_type - string - type of device. 16 character max. e.g.
desktop, iphone, iphone3g, iphone4, iphone5s, iphone5c, android
os - string - The OS of the device. 16 character max. e.g.
ios, mac, windows
os_ver - string - The OS version. 16 character max.
browser - string - (optional) The browser in use. 16 character max.
browser_ver - string - (optional) The browser version. 16 character max.
country - string - (optional) The uppercase 2 letter ISO 3166-1 alpha-2 country code of the device location. Should not be included if the application can not determine the device location. If application does not pass in device location, location will be determined by geo-mapping the the geo_ip_address (if present) or the requestor IP address.
geo_ip_address - string - (optional) The IP address to use to use for geo-mapping if country is not present. Only used if country is not present.
language - string - (optional) The lowercase 2 letter ISO 639-1 language code. For browser applications it will be filled in with the value of "Accept-Language" if this property missing and the header is present. This field must be sent if the "Accept-Language" header is not present in the request.
group_tag - string - (optional) A tag used to group related events. Please see your product manager or your event definition spec for the contents of this tag. 32 character maximum.
events - list of objects - A list of events. Each event is a dictionary containing several properties specific to that event.
All calls (except experiment track) have these taxonomy properties. Please see your product manager for definition of what to put in each field for the particular event.
kingdom - string - (optional) Taxonomy of the event. 32 character maximum.
phylum - string - (optional) Taxonomy of the event. 32 character maximum.
class - string - (optional) Taxonomy of the event. 32 character maximum.
order - string - (optional) Taxonomy of the event. 32 character maximum.
family - string - (optional) Taxonomy of the event. 32 character maximum.
genus - string - (optional) Taxonomy of the event. 32 character maximum.
species - string - (optional) Taxonomy of the event. 32 character maximum.
float1 - number - (optional) Value for the event.
float2 - number - (optional) Value for the event.
float3 - number - (optional) Value for the event.
float4 - number - (optional) Value for the event.
All event types (except for experiment track) support the event index property. This property is useful for reconsiling data integrity from client to server.
event_index - number - (optional) Event index. Must be an integer, can not be fractional.
Includes all the taxonomy properties. In addition should have the following.
type - string - "install"
event_datetime - string - ISO 8601 date and time of the event in UTC. (e.g. 2013-11-07T10:42Z)
online_status - string - (optional) Online status of the device when the event occurred. The following values should be used:
offline, online-wifi, online-cellular
Includes all the taxonomy properties. In addition should have the following.
type - string - "dau"
event_datetime - string - ISO 8601 date and time of the event in UTC. (e.g. 2013-11-07T10:42Z)
online_status - string - (optional) Online status of the device when the event occurred. The following values should be used:
offline, online-wifi, online-cellular
Includes all the taxonomy properties. In addition should have the following.
type - string - "event"
event_datetime - string - ISO 8601 date and time of the event in UTC. (e.g. 2013-11-07T10:42Z)
online_status - string - (optional) Online status of the device when the event occurred. The following values should be used:
offline, online-wifi, online-cellular
Includes all the taxonomy properties. In addition should have the following.
type - string - "economy"
event_datetime - string - ISO 8601 date and time of the event in UTC. (e.g. 2013-11-07T10:42Z)
online_status - string - (optional) Online status of the device when the event occurred. The following values should be used:
offline, online-wifi, online-cellular
spend_amount - number - Amount of spend.
spend_currency - string - Currency of the spend event. Real world currencies should use ISO 4217 currency codes, e.g. USD, EUR, GBP. Real world values will be converted to USD for the analytics using the average daily exchange rate for that day. Virtual currencies should make sure they do not overlap with ISO 4217 currency codes; the best way to do this is generally to make virtual currencies all lower case. 16 character maximum.
spend_type - string - (optional) Type of spend.
This event allows you to link different social networks to the device_tag of the user. In general, it is preferable to use the Global properties and send these values each time. If that is infeasible for your application, then you can use this explicit event.
This event does not include all the taxonomy properties. Only has the following:
type - string - "link"
event_datetime - string - ISO 8601 date and time of the event in UTC. (e.g. 2013-11-07T10:42Z)
user_tag - string - (optional) A unique ID for the user. Should only be inserted if the application is able to determine a unique stable user identity. User tags should be unique per user across the organization. If they are not unique for a particular organization, they should be prefixed per application to make them unique. 62 character maximum. Also see user anonymized data.
facebook_tag - string - (optional) The facebook ID of the user. 62 character maximum. Also see user anonymized data.
twitter_tag - string - (optional) The twitter ID of the user. 62 character maximum. Also see user anonymized data.
google_tag - string - (optional) The google ID of the user. 62 character maximum. Also see user anonymized data.
game_center_tag - string - (optional) The iOS Game Center ID. Also see user anonymized data.
Includes all the taxonomy properties. In addition should have the following. If the organization is using user anonymized data, the tags in this call should be anonymized in the same manner as other places in the api. See user anonymized data.
type - string - "message_send"
event_datetime - string - ISO 8601 date and time of the event in UTC. (e.g. 2013-11-07T10:42Z)
network - string - Social network for the message send. For known networks the following should be used:
facebook, twitter, google, email, sms
channel - string - (optional) Type of send on the social network.
from_tag - string - The social network id of the sender.
to_list - list of strings - List of social network id's this message was sent to. Each string has a 62 character maximum.
Includes all the taxonomy properties. In addition should have the following. If the organization is using user anonymized data, the tags in this call should be anonymized in the same manner as other places in the api. See user anonymized data.
type - string - "message_click"
event_datetime - string - ISO 8601 date and time of the event in UTC. (e.g. 2013-11-07T10:42Z)
network - string - Social network for the message click. For known networks the following should be used:
facebook, twitter, google, email, sms
channel - string - (optional) Type of message on the social network.
from_tag - string - Social network ID of the sender of the message that was clicked. 62 character maximum.
to_tag - string - Social network ID of the recipient of the message that was clicked. 62 character maximum.
Does not include all the taxonomy properties. Only has the following:
type - string - "experiment"
event_datetime - string - ISO 8601 date and time of the event in UTC. (e.g. 2013-11-07T10:42Z)
experiment_name - string - Name of the experiment. 32 character maximum.
variant_name - string - Name of the variant. 32 character maximum. Send the empty string ("") to indicate the device has stopped being enrolled in the experiment.
The API takes several elements of user identifying data: user_tag, facebook_tag, game_center_tag, device_tag. Depending on your particular data privacy policy you may choose to hash these data points before transmitting them to Data Cortex.
This data is used to correlate usage by users on multiple devices and platforms. The output of the hash function should be stable across all application usage and across devices and applications for your organization. Therefor, if you choose to hash this data before transmitting it, the suggested procedure is to use global static key and use an HMAC (e.g. HMAC-SHA256) to hash the value before transmission.
If the client encounters an error when sending to the backend service it should make sure to not resend the request immediately. At a minimum it should wait 30 seconds between attempts. Ideally the client should implement random exponential backoff.