POST /visit/events
POST/visit/events
This endpoint can be used to post data for a given visitor, such as conversion events, page view events etc.
An incoming request is rejected if the source is identified as bot or spider, according to user-agent filtering rules from IAB/ABC. Kameleoon is using single-pass method. This means nothing specific is to be done in the case request is sent from a web browser using a standard library (XHR); but in other cases the user should set a custom value to the User-Agent request header, to overwrite the default value set by the library.
Request
Query Parameters
Id of the Kameleoon project
Visitor code (Kameleoon unique id for a visitor). Note: if the parameter "visitorCode" is provided here, then it is assumed as the common value for all events in the body (bulk posting of several events restricted to the same visitor). On the contrary, if you would like to bulk post several events across several different visitors, then you must provide the parameter "visitorCode" with every event in the body
Set to true if you provide the body content in JSON format, else URL query format is assumed. See body schema
false- */*
Body
required
Events to save. Body size limited to 8 MB.
When the URL query parameter is missing the "json" key or its value is set to false, the body consists of one or more lines, with each line representing an event in a specific format. The format is as follows: <parameter 1 name>=<parameter 1 value>&<parameter 2 name>=<parameter 2 value> and so on. Make sure to escape values that may contain characters = or &, for example using the function encodeURIComponent in JavaScript.
If the URL contains the query parameter "json" with the value set to true, then the body will be a JSON array of events. Each event will be represented as a JSON object, formatted like this: {"<parameter 1 name>": <parameter 1 value>, "<parameter 2 name>": <parameter 2 value>, etc.}.
In all cases, the body will contain the following parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| visitorCode | string | Required if not provided in URL query parameters, else ignored | Kameleoon unique id for a visitor |
| nonce | string | Required | A random string of 16 hexadecimal characters, unique to each event |
| eventType | string | Required | One of the following: STATICDATA, PAGE, CONVERSION, TARGETINGSEGMENT, EXPERIMENT, PERSONALIZATION, WEATHER, CUSTOMDATA, PRODUCT, GEOLOCATION |
List of parameters for the eventType STATICDATA:
| Name | Type | Required | Description |
|---|---|---|---|
| visitNumber | int32 | Optional | Number of visits |
| timeSincePreviousVisit | int64 | Optional | Time since last visit in milliseconds |
| browser | string | Optional | Browser's name (e.g. "Safari") |
| browserIndex | int32 | Optional | Configured browser index |
| browserVersion | float64 | Optional | Browser version |
| os | string | Optional | OS name (e.g. "Windows") |
| osIndex | int32 | Optional | Configured OS index |
| windowWidth | int32 | Optional | Window width |
| windowHeight | int32 | Optional | Window height |
| screenWidth | int32 | Optional | Screen width |
| screenHeight | int32 | Optional | Screen height |
| timeZoneId | string | Optional | Time zone id (e.g. "Europe/Paris") |
| localeLanguageTag | string | Optional | Local language tag (e.g. "fr") |
| deviceType | string | Optional | One of the following: DESKTOP, TABLET, PHONE |
List of parameters for the eventType PAGE:
| Name | Type | Required | Description |
|---|---|---|---|
| herf | string | Required | Complete URL |
| canonicalHref | string | Optional | Canonical herf |
| title | string | Optional | Page title |
| keyPageIndices | JSON array | Optional | JSON array of configured key page indices (int32) |
| referrerHref | string | Optional | Complete URL of referrer |
| referrerIndices | JSON array | Optional | JSON array of configured referrer indices (int32) |
List of parameters for the eventType CONVERSION:
| Name | Type | Required | Description |
|---|---|---|---|
| goalId | int64 | Required | Id of the goal |
| revenue | float64 | Optional | Revenue generated in the goal |
| negative | Boolean | Optional, default false | Should conversion be removed? |
| metadata | JSON object | Optional | JSON object with the following structure: key = metadata id (int32), value = metadata values (JSON array of string) |
List of parameters for the eventType TARGETINGSEGMENT:
| Name | Type | Required | Description |
|---|---|---|---|
| id | int64 | Required | Segment id |
List of parameters for the eventType EXPERIMENT:
| Name | Type | Required | Description |
|---|---|---|---|
| id | int64 | Required | Experiment id |
| variationId | int64 | Required | Variation id. 0 if reference |
List of parameters for the eventType PERSONALIZATION:
| Name | Type | Required | Description |
|---|---|---|---|
| id | int64 | Required | Personalization id |
| variationId | int64 | Required | Variation id. 0 if reference |
| unexpositionCause | string | Optional | Only valid if variationId is 0. One of the following: GLOBAL_EXCLUSION, PERSONALIZATION_CAPPING, SCHEDULE, PERSONALIZATION_EXCLUSION, VISITOR_CAPPING, SCENARIO, PRIORITY |
List of parameters for the eventType WEATHER:
| Name | Type | Required | Description |
|---|---|---|---|
| temperature | float64 | Required | Temperature in Kelvin |
| humidity | float64 | Required | Humidity percentage |
| pressure | float64 | Required | Atmospheric pressure in hPa |
| windSpeed | float64 | Required | Wind speed in meters/second |
| cloudiness | float64 | Required | Cloudiness in percentage |
| sunriseTime | int64 | Required | Sunrise time as a UNIX millisecond timestamp |
| sunsetTime | int64 | Required | Sunset time as a UNIX millisecond timestamp |
| weatherCode | string | Optional | Weather description (e.g. "Sky is Clear") |
List of parameters for the eventType CUSTOMDATA:
| Name | Type | Required | Description |
|---|---|---|---|
| index | int32 | Required | Configured custom data index |
| valuesCountMap | JSON object | Required | JSON object with the following structure: key = value (string), value = count (int32) |
| overwrite | Boolean | Optional, default true | Overwrite previous values counts (or merge)? |
| mappingIdentifier | Boolean | Optional, default false | Is this custom data used as a mapping identifier? |
List of parameters for the eventType PRODUCT:
| Name | Type | Required | Description |
|---|---|---|---|
| ean | string | Required | Product code |
List of parameters for the eventType GEOLOCATION:
| Name | Type | Required | Description |
|---|---|---|---|
| country | string | Optional | Country |
| region | string | Optional | Region |
| city | string | Optional | City |
| postalCode | string | Optional | Postal code |
| latitude | float64 | Optional | Latitude |
| longitude | float64 | Optional | Longitude |
Note: in the examples below, we assume that the parameter "visitorCode" is provided in the URL query part, so this is bulk posting of several events restricted to the same visitor, and then "visitorCode" is not needed in body events.
Body example in the case the URL query parameter "json" is missing or present with value false (NB: https%3A%2F%2Fwww.supersite.com%2Fsuperpage%3Fsuperparam%3Dtrue is the escaped value of https://www.supersite.com/superpage?superparam=true, while %7B%22val1%22%3A1%2C%22val2%22%3A5%7D is the escaped value of {"val1":1,"val2":5}):
nonce=d2ce4d22083348fb&eventType=STATICDATA&browser=Safari&browserVersion=16.3&deviceType=DESKTOP&os=Windows
nonce=b0a4253d8acd01c7&eventType=PAGE&href=https%3A%2F%2Fwww.supersite.com%2Fsuperpage%3Fsuperparam%3Dtrue
nonce=4ca34741a6cc8a48&eventType=CONVERSION&goalId=2&revenue=24.99
nonce=69e2d11c519868cc&eventType=EXPERIMENT&id=5&variationId=0
nonce=9de54e5675f4e18d&eventType=CUSTOMDATA&index=3&valuesCountMap=%7B%22val1%22%3A1%2C%22val2%22%3A5%7D
Body example in the case the URL query parameter "json" is present with value true, with a "pretty" representation (not recommended):
[
{
"nonce": "d2ce4d22083348fb",
"eventType": "STATICDATA",
"browser": "Safari",
"browserVersion": 16.3,
"deviceType": "DESKTOP",
"os": "Windows"
},
{
"nonce": "b0a4253d8acd01c7",
"eventType": "PAGE",
"href": "https://www.supersite.com/superpage?superparam=true"
},
{
"nonce": "4ca34741a6cc8a48",
"eventType": "CONVERSION",
"goalId": 2,
"revenue": 24.99
},
{
"nonce": "69e2d11c519868cc",
"eventType": "EXPERIMENT",
"id": 5,
"variationId": 0
},
{
"nonce": "9de54e5675f4e18d",
"eventType": "CUSTOMDATA",
"index": 3,
"valuesCountMap": {
"val1": 1,
"val2": 5
}
}
]
Body example in the case the URL query parameter "json" is present with value true, with a "compact" representation (recommended):
[{"nonce":"d2ce4d22083348fb","eventType":"STATICDATA","browser":"Safari","browserVersion":16.3,"deviceType":"DESKTOP","os":"Windows"},{"nonce":"b0a4253d8acd01c7","eventType":"PAGE","href":"https://www.supersite.com/superpage?superparam=true"},{"nonce":"4ca34741a6cc8a48","eventType":"CONVERSION","goalId":2,"revenue":24.99},{"nonce":"69e2d11c519868cc","eventType":"EXPERIMENT","id":5,"variationId":0},{"nonce":"9de54e5675f4e18d","eventType":"CUSTOMDATA","index":3,"valuesCountMap":{"val1":1,"val2":5}}]
string
Responses
- 204
- 400
- 401
- 403
- 413
- 429
- 500
URL query was processed successfully and no content is returned
Body will be processed asynchronously, no syntax check on body was done yet
Malformed URL query syntax
Failed authentication (missing token when required, or bad token: malformed, expired, or invalid signature)
Forbidden user-agent or access denied to restricted resource
Body too large
Rate limited
Unexpected internal error