Skip to main content

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.

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 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 either the parameter "visitorCode" or the parameter "mappingValue" with every event in the 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"

  • 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"

  • delayed boolean

    Are those events sent with delay? Note: if this parameter is given with value true, then extra parameters related to delayed events are to be provided with every event in the body. See body description

  • 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 10 MB

  • string UTF-8

    In the case the 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 the 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 both "visitorCode" and "mappingValue" are not provided in URL query parameters and also "mappingValue" is not provided here, 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>

    only if "delayed" is provided in URL query parameters with value true:

           (required) time = <event UNIX millisecond timestamp = integerint64>

    (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 = integerint32>

           (optional) timeSincePreviousVisit = <time since previous visit in milliseconds = integerint64>

           (optional) browser = <browser name, for ex Chrome = string>

           (optional) browserIndex = <configured browser index = integerint32, null for other>

           (optional) browserVersion = <browser version = numberdouble>

           (optional) os = <operating system name, for ex Android = string>

           (optional) osIndex = <configured operating system index = integerint32, null for other>

           (optional) windowWidth = <window width = integerint32>

           (optional) windowHeight = <window height = integerint32>

           (optional) screenWidth = <screen width = integerint32>

           (optional) screenHeight = <screen height = integerint32>

           (optional) timeZoneId = <time zone id, for ex EuropeParis = 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 = integerint32, null for other>>

           (optional) referrerHref = <complete URL (aka HRef) of referrer = string>

           (optional) referrersIndices = <JSON array of <configured referrer index = integerint32, null for other>>

    only for eventType = "CONVERSION":

           (required) goalId = <goal id = integerint64>

           (optional) revenue = <revenue = numberdouble>

           (optional) negative = <is conversion to remove? = boolean>

    only for eventType = "TARGETINGSEGMENT":

           (required) id = <targeting segment id = integerint64>

    only for eventType = "EXPERIMENT":

           (required) id = <experiment id = integerint64>

           (required) variationId = <variation id, 0 for reference = integerint64>

    only for eventType = "PERSONALIZATION":

           (required) id = <personalization id = integerint64>

           (required) variationId = <variation id, 0 for reference = integerint64>

           (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 = numberdouble>

           (required) humidity = <humidity percentage = numberdouble>

           (required) pressure = <atmospheric pressure in hPa = numberdouble>

           (required) windSpeed = <wind speed in metersec = numberdouble>

           (required) cloudiness = <cloudiness percentage = numberdouble>

           (required) sunriseTime = <sunrise UNIX millisecond timestamp = integerint64>

           (required) sunsetTime = <sunset UNIX millisecond timestamp = integerint64>

           (optional) weatherCode = <weather description, for ex "Sky is Clear" = string>

    only for eventType = "CUSTOMDATA":

           (required) index = <configured custom data index = integerint32>

           (required) valuesCountMap = <JSON object of key: <value = string (max length 1024)> and value: <count = integerint32>>

           (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 = numberdouble>

           (optional) longitude = <longitude = numberdouble>

    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.

    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}}]
Responses

Request allowed, URL query processed successfully, request body will be processed

Loading...