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

  • 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 "visitorCode" is not provided in URL query parameters, 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>

          ◦ (optional) metadata = <JSON object of key: <metadata id (as string) = string> and value: <metadata values = JSON array of <metadata value = string>>>

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

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

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

Loading...