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

siteCode stringrequired

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
Default value: false

*/*

Body

required

Events to save. Body size limited to 3 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 Limited to 100 characters
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") Limited to 100 characters
browserIndex	int32	Optional	Configured browser index
browserVersion	float64	Optional	Browser version
os	string	Optional	OS name (e.g. "Windows") Limited to 100 characters
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 Limited to 2048 characters
canonicalHref	string	Optional	Canonical URL Limited to 2048 characters
title	string	Optional	Page title Limited to 256 characters
keyPageIndices	JSON array	Optional	JSON array of configured key page indices (int32) No more than 256 indices
referrerHref	string	Optional	Complete URL of the referrer Limited to 2048 characters
referrerIndices	JSON array	Optional	JSON array of configured referrer indices (int32) No more than 256 indices

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) No more than 256 ids No more than 256 values for each id Every value is limited to 2048 characters

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") Limited to 100 characters

List of parameters for the eventType CUSTOMDATA:

Name	Type	Required	Description
index	int32	Required	Configured custom data index
mappingIdentifier	Boolean	Optional, default false	Is this custom data used as a mapping identifier?
valuesCountMap	JSON object	Required	JSON object with the following structure: key = value (string), value = count (int32) No more than 256 values Every value is limited to 2048 characters if "mappingIdentifier" is false, 100 else
overwrite	Boolean	Optional, default true	Overwrite previous values counts (or merge)?

List of parameters for the eventType PRODUCT:

Name	Type	Required	Description
ean	string	Required	Product code Limited to 100 characters

List of parameters for the eventType GEOLOCATION:

Name	Type	Required	Description
country	string	Optional	Country Limited to 100 characters
region	string	Optional	Region Limited to 100 characters
city	string	Optional	City Limited to 100 characters
postalCode	string	Optional	Postal code Limited to 100 characters
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

URL query was processed successfully and no content is returned
Body will be processed asynchronously, no syntax check on body was done yet

400

Malformed URL query syntax

401

Failed authentication (missing token when required, or bad token: malformed, expired, or invalid signature)

403

Forbidden user-agent or access denied to restricted resource

413

Body too large

429

Rate limited

500

Unexpected internal error

Loading...