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. See https://www.iab.com/guidelines/iab-abc-international-spiders-bots-list/.
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.

Query Parameters

siteCode string required
Id of the Kameleoon project
visitorCode string
Visitor code (Kameleoon unique id for a visitor). Note: if either the parameter "visitorCode" or the parameter "mappingValue" is provided here, then it is assumed as the common value for all events provided in 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 either the parameter "visitorCode" or the parameter "mappingValue" with every event provided in body. In all cases, it is strongly recommended to provide "visitorCode" in priority over "mappingValue" when possible, for performance reasons. See description of the parameter "mappingValue"; see also body example value
mappingValue string
Value of the custom data configured as a mapping identifier (acting as a visitor cross-device id) if applicable. See the note attached to the parameter "visitorCode"
json boolean
Set to true if you provide the body content in JSON format, else URL query format is assumed. See body schema

Request Body required

Events to save. Body size limited to 1 MB

string UTF-8
In the case URL query parameter "json" is missing or present with value false, then body is made of one or several lines, each line encoding an event in the form <parameter 1 name>=<parameter 1 value>&<parameter 2 name>=<parameter 2 value> etc. (escape values that can contain characters = or & – aka JavaScript method encodeURIComponent).

In the case URL query parameter "json" is present with value true, then body is a JSON array of events, each event being a JSON object {"<parameter 1 name>": <parameter 1 value>, "<parameter 2 name>": <parameter 2 value>, etc.}.

In all cases, with following parameter list:

• (optional) visitorCode = <visitor code (Kameleoon unique id for a visitor), required if not provided in URL query parameters, else ignored = string>
• (optional) mappingValue = <value of the custom data configured as a mapping identifier (acting as a visitor cross-device id) if applicable, required if both "visitorCode" and "mappingValue" are not provided in URL query parameters and also "visitorCode" is not provided here, else ignored = string>
• (required) nonce = <random string of 16 hexadecimal characters, unique to each event = string>
• (required) eventType = <any following event type, case-insensitive = string>
• only for eventType = "STATICDATA":
      ◦ (optional) visitNumber = <visit number = integer⁄int32>
      ◦ (optional) timeSincePreviousVisit = <time since previous visit in milliseconds = integer⁄int64>
      ◦ (optional) browser = <browser name, for ex Chrome = string>
      ◦ (optional) browserIndex = <configured browser index = integer⁄int32, null for other>
      ◦ (optional) browserVersion = <browser version = number⁄double>
      ◦ (optional) os = <operating system name, for ex Android = string>
      ◦ (optional) osIndex = <configured operating system index = integer⁄int32, null for other>
      ◦ (optional) windowWidth = <window width = integer⁄int32>
      ◦ (optional) windowHeight = <window height = integer⁄int32>
      ◦ (optional) screenWidth = <screen width = integer⁄int32>
      ◦ (optional) screenHeight = <screen height = integer⁄int32>
      ◦ (optional) timeZoneId = <time zone id, for ex Europe⁄Paris = string>
      ◦ (optional) localeLanguageTag = <locale language tag, for ex fr = string>
      ◦ (optional) deviceType = <device type = one of ["DESKTOP", "TABLET", "PHONE"]>
• only for eventType = "PAGE":
      ◦ (required) href = <complete URL (aka HRef) = string>
      ◦ (optional) canonicalHref = <canonical URL = string>
      ◦ (optional) title = <page title = string>
      ◦ (optional) keyPagesIndices = <JSON array of <configured key page index = integer⁄int32, null for other>>
      ◦ (optional) referrerHref = <complete URL (aka HRef) of referrer = string>
      ◦ (optional) referrersIndices = <JSON array of <configured referrer index = integer⁄int32, null for other>>
• only for eventType = "CONVERSION":
      ◦ (required) goalId = <goal id = integer⁄int64>
      ◦ (optional) revenue = <revenue = number⁄double>
      ◦ (optional) negative = <is conversion to remove? = boolean>
• only for eventType = "TARGETINGSEGMENT":
      ◦ (required) id = <targeting segment id = integer⁄int64>
• only for eventType = "EXPERIMENT":
      ◦ (required) id = <experiment id = integer⁄int64>
      ◦ (required) variationId = <variation id, 0 for reference = integer⁄int64>
• only for eventType = "PERSONALIZATION":
      ◦ (required) id = <personalization id = integer⁄int64>
      ◦ (required) variationId = <variation id, 0 for reference = integer⁄int64>
      ◦ (optional if variationId = 0 (reference), useless else) unexpositionCause = <unexposition cause = one of ["GLOBAL_EXCLUSION", "PERSONALIZATION_CAPPING", "SCHEDULE", "PERSONALIZATION_EXCLUSION", "VISITOR_CAPPING", "SCENARIO", "PRIORITY"]>
• only for eventType = "WEATHER":
      ◦ (required) temperature = <temperature in Kelvin = number⁄double>
      ◦ (required) humidity = <humidity percentage = number⁄double>
      ◦ (required) pressure = <atmospheric pressure in hPa = number⁄double>
      ◦ (required) windSpeed = <wind speed in meter⁄sec = number⁄double>
      ◦ (required) cloudiness = <cloudiness percentage = number⁄double>
      ◦ (required) sunriseTime = <sunrise UNIX millisecond timestamp = integer⁄int64>
      ◦ (required) sunsetTime = <sunset UNIX millisecond timestamp = integer⁄int64>
      ◦ (optional) weatherCode = <weather description, for ex "Sky is Clear" = string>
• only for eventType = "CUSTOMDATA":
      ◦ (required) index = <configured custom data index = integer⁄int32>
      ◦ (required) valuesCountMap = <JSON object of key: <value = string (max length 1024)> and value: <count = integer⁄int32>>
      ◦ (optional) overwrite = <overwrite previous values counts (or apply a merge)? = boolean>
      ◦ (optional) mappingIdentifier = <is this custom data used as mapping identifier? = boolean>
• only for eventType = "PRODUCT":
      ◦ (required) ean = <product code = string>
• only for eventType = "GEOLOCATION":
      ◦ (optional) country = <country = string>
      ◦ (optional) region = <region = string>
      ◦ (optional) city = <city = string>
      ◦ (optional) postalCode = <postalCode = string>
      ◦ (optional) latitude = <latitude = number⁄double>
      ◦ (optional) longitude = <longitude = number⁄double>

See examples below.

Note: in the examples below, we assume that either the parameter "visitorCode" or the parameter "mappingValue" is provided in the URL query part, so this is bulk posting of several events restricted to the same visitor, and then both "visitorCode" and "mappingValue" are not needed in body events.

In the case 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 - %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

In the case 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
    }
  }
]

In the case 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}}]

Responses

Successful operation, events are saved

POST /visit/events​

POST /visit/events