Event Data Format
Please read general information about Tracking Api first.
EventBunker supports a flexible JSON format as event data structure. Mandatory fields are event_name in your json data and a valid write api key.
In principal we support JSON types; string, number, float, null, boolean, string array, number array, bool array and nested object contaning same types mentioned earlier in object fields. Arrays that have mixed string and number values are not supported. Objects with another nested object inside it are also not supported for now.
EventBunker is using JSON Schema Validation, specifically this version, for incoming json parsing and validation, so you will get an error from validator if your request is not valid against our schema.
You will find our JSON Schema here for your convenience : https://eventbunker.io/example_event_body.json
You do not have to know about JSON schema validation to use EventBunker apis, we will provide easy to understand, plain English validation error message responses from api.
Pre-defined Event Data Fields
In additional to reserved fields, which you can not overwrite, we have also defined field names for common event analytics use-cases. All of these fields are optional except event_name
| Field Name | Required | Type | Description |
|---|---|---|---|
| event_name | Yes | string | Name of Event. Max 2000 unique names. Only letters[a-z][A-Z], numbers, dot(.) or underscore(_) or hyphen(-) |
| timestamp | No | string | Date of event in the format that must be parsable by JS Date format link Timezone will be converted to UTC in database. Examples; "2021-10-10T14:48:00", "2021-10-10T14:48:00.000", "2021-10-10T14:48:00.000+09:00" |
| customer_identifier | No | string | Your customer's identifier, can be any string value. You can use it to write and query data for single user. Please click for usage detail |
| metric_name | No | string | If you also want to use EventBunker as a timeseries database. Please set event_name to metric or similar fixed value for this. Or you can use event_name as main category name for your metric_name You will have to provide a event_name value to query metrics with a metric_name value |
| metric_value | No | float | Float value for metric_name. Will be used for sum, max, min, avg, etc.. type of aggregation |
Reference
JS Date format
There is an additional feature in write api keys when a customer_identifier attached to it, read more at How to Use Api Keys
All Other Possible Field Types
Like mentioned above, EventBunker works with many kind of JSON types. Here we will list all of the types we support as JSON can be pretty complex if you use nested data a lot. Refer here for JSON types.
Field names should be valid string. Only letters[a-z][A-Z], numbers, dot(.) or underscore(_) or hyphen(-).
| Field Type | Description | Example |
|---|---|---|
| string | Any json string value | {"my_field": "my_string_value_is_the_best_"} |
| number | Any json number value, int and float | {"my_number_field": 123.45} |
| null | Just null json type | {"my_null_field": null} |
| boolean | A json bool value | {"my_bool_field": true} |
| string array | A json array with string elements | {"my_string_array": ["cat", "dog"]} |
| number array | A json array with number elements | {"my_number_array": [123, 124, 125.88]} |
| boolean array | A json array with boolean elements | {"my_bool_array": [true, false, false]} |
| object | A json object, can contains any possible types listed above | {"my_object": { "a_string_field": "somevalue", "an_array_field": [true, false, false ], "and_number_field": 123.45 } } |
- 2-level nested object, which is a nested object inside a nested object, is not supported at this moment.
- An array containing objects is also not supported because it would be hard to query on this data type. If you absolutely need one of not supported types, please contact us.
Reserved Fields and Descriptions
Reserved field names are listed in table below, if your request data contains this fields then you will get a json schema validation error. All of these fields are saved in our datastore, so you can leverage any field in Query Api
| Field Name | Reserved | Type | Description |
|---|---|---|---|
| _eb_timestamp | Yes | number | UTC timestamp when the event received by api |
| _eb_unique_req_id | Yes | string | Random and unique id, given by api for each request |
| _eb_organization_id | Yes | string | Your Account Id |
| _eb_project_id | Yes | string | Your Project Id |
| _eb_write_key | Yes | string | Write key which is used in this api call |
| _eb_raw_json | Yes | string | Raw JSON request body |
| _eb_user_hash | Yes | string | Daily User HASH value from request origin. Combination of User Agent and IP address. OPTIONAL |
| _eb_ip | Yes | string | IP address which POST request has been sent. OPTIONAL |
| _eb_country | Yes | string | Country information from IP2Location |
| _eb_city | Yes | string | City information from IP2Location |
| _eb_metro_code | Yes | string | US Metro code information from IP2Location |
| _eb_latitude | Yes | float | Latitude information from IP2Location. OPTIONAL |
| _eb_longitude | Yes | float | Longitude information from IP2Location. OPTIONAL |
| _eb_timezone | Yes | string | Timezone information from IP2Location |
| _eb_http_referrer | Yes | string | Http referer header, if exists |
| _eb_http_origin | Yes | string | Http origin header, if exists |
| _eb_utm_source | Yes | string | Http Query utm_source parameter, if exists |
| _eb_utm_medium | Yes | string | Http Query utm_medium parameter, if exists |
| _eb_utm_campaign | Yes | string | Http Query utm_campaign parameter, if exists |
| _eb_browser | Yes | string | Request browser name, if user-agent header is valid |
| _eb_device_type | Yes | string | Request device info, if user-agent header is valid |
| _eb_device_vendor | Yes | string | Request device vendor info, if user-agent header is valid |
| _eb_operating_system | Yes | string | Request OS, if user-agent header is valid |