POST https://admin.threekit.com/api/analytics/events
Create an event and return the details
REST Endpoint
POST https://admin.threekit.com/api/analytics/events?bearer_token=[bearer_token]&orgId=[orgId]
Query Parameters
Name |
In |
Type |
Required |
Description |
bearer_token |
query |
string |
false |
Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token. |
orgId |
query |
string |
false |
Retrieve list of products of a particular organization. For the token's organization, it retrieves the list of all products. For a public organization it retrieves the list of shared products. |
body |
body |
createBody |
true |
Event creation fields |
Body Parameters
{
"eventType": "product session start",
"eventMetadata": {},
"orgId": "91e138bc-fada-44e7-bc6c-492620622570",
"assetId": "bee4a155-5b92-48ad-b3fb-f14a235637a5",
"userId": "9a04aeee-ecae-4edd-9462-0f36341e83e9",
"sessionId": "553eedf9-a42e-465e-a833-894109ec21ac",
"configId": "613ed936-5137-4029-99d7-2ea1e48dec5b",
"configuration": {},
"device": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0",
"metric": 1
}
Response Codes
Status |
Meaning |
Description |
Schema |
200 |
OK |
Create an event successfully and return it's details |
None |
401 |
Unauthorized |
none |
None |
422 |
Unprocessable Entity |
Request to create an event with an invalid parameter value |
None |
Example Implementations
Code
CURL
curl --request POST \
--url https://admin.threekit.com/api/analytics/events \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"eventType":"product session start","eventMetadata":{},"orgId":"91e138bc-fada-44e7-bc6c-492620622570","assetId":"bee4a155-5b92-48ad-b3fb-f14a235637a5","userId":"9a04aeee-ecae-4edd-9462-0f36341e83e9","sessionId":"553eedf9-a42e-465e-a833-894109ec21ac","configId":"613ed936-5137-4029-99d7-2ea1e48dec5b","configuration":{},"device":"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0","metric":1}'
Node.JS
var http = require("https");
var options = {
"method": "POST",
"hostname": "admin.threekit.com",
"port": null,
"path": "/api/analytics/events",
"headers": {
"content-type": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
eventType: 'product session start',
eventMetadata: {},
orgId: '91e138bc-fada-44e7-bc6c-492620622570',
assetId: 'bee4a155-5b92-48ad-b3fb-f14a235637a5',
userId: '9a04aeee-ecae-4edd-9462-0f36341e83e9',
sessionId: '553eedf9-a42e-465e-a833-894109ec21ac',
configId: '613ed936-5137-4029-99d7-2ea1e48dec5b',
configuration: {},
device: 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
metric: 1
}));
req.end();
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://admin.threekit.com/api/analytics/events",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\"eventType\":\"product session start\",\"eventMetadata\":{},\"orgId\":\"91e138bc-fada-44e7-bc6c-492620622570\",\"assetId\":\"bee4a155-5b92-48ad-b3fb-f14a235637a5\",\"userId\":\"9a04aeee-ecae-4edd-9462-0f36341e83e9\",\"sessionId\":\"553eedf9-a42e-465e-a833-894109ec21ac\",\"configId\":\"613ed936-5137-4029-99d7-2ea1e48dec5b\",\"configuration\":{},\"device\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0\",\"metric\":1}",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer {access-token}",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Example responses
[
{
"id": "78aa0bcc-ed1f-4156-958c-3b7cffbae606",
"eventType": "product AR not available",
"eventMetadata": {},
"orgId": "d7e8d7a2-93b1-43d5-bf20-32195396598c",
"assetId": "6e4b65b7-862b-4cd9-b183-c07d82d5beed",
"assetName": "Example Product A",
"assetMetadata": {},
"configId": "94e932d8-4edf-4198-a8c4-097fab9402d5",
"configuration": {},
"userId": null,
"sessionId": "b6f1b4b7-fd44-461d-8b90-79561a716370",
"device": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36",
"referer": "https://examplewebsite.com/examplepagea",
"createdAt": "2020-07-30T15:27:23.058Z"
}
]
{
"error": {
"type": "create_event_error",
"message": "Create event error"
}
}
GET https://admin.threekit.com/api/analytics/events
Retrieve the list of events for an org. Each event will contain the following field.
- id - Id of the event
- eventType - Type of event. Currently the supported event types are - 'product download', 'product session start', 'product session end', 'product configuration set', 'product configuration attribute set', 'product interaction', 'product cart-add', 'product ordered', 'product social share', 'product AR not available', 'product AR offered', 'product AR download', 'product AR mobile transition offered', 'product AR mobile transition completed'
- eventMetadata - User defined metadata for an event
- orgId - ID of the org linked to the event
- assetId - Id of the asset linked to the event, if applicable
- userId - Id of the user linked to the session for which events are being stored
- sessionId - Id of the session for which the events are being stored
- configId - Id of the configuration of asset, if applicable, linked to the event
- configuration - Full configuration object of the asset, if applicable, linked to the event
- device - Information about the device linked to the event. This is the User-Agent header present in the request when creating the event
- createdAt - Event creation date
REST Endpoint
GET https://admin.threekit.com/api/analytics/events?bearer_token=[bearer_token]&orgId=[orgId]&metadata=[metadata]&device=[device]&referer=[referer]
Query Parameters
Name |
In |
Type |
Required |
Description |
bearer_token |
query |
string |
false |
Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token. |
orgId |
query |
string |
false |
Retrieve list of products of a particular organization. For the token's organization, it retrieves the list of all products. For a public organization it retrieves the list of shared products. |
metadata |
query |
string |
false |
Retrieve information by their metadata. Must be passed in as a stringified JSON. |
device |
query |
string |
false |
Retrieve events with a specific user agent header. Must be converted to an escaped query string. |
referer |
query |
string |
false |
Retrieve events for for a specific page(referer header). This can also be used to fetch all events for a specific origin header. Must be converted to an escpaed query string. |
Response Codes
Status |
Meaning |
Description |
Schema |
200 |
OK |
List of events for a specific org. Each event will contain the asset name and metadata, if applicable |
None |
403 |
Forbidden |
Request to access events of an invalid or unauthorized org |
None |
Example Implementations
Code
CURL
curl --request GET \
--url https://admin.threekit.com/api/analytics/events \
--header 'authorization: Bearer {access-token}'
Node.JS
var http = require("https");
var options = {
"method": "GET",
"hostname": "admin.threekit.com",
"port": null,
"path": "/api/analytics/events",
"headers": {
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://admin.threekit.com/api/analytics/events",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer {access-token}"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Example responses
{
"events": [
{
"id": "78aa0bcc-ed1f-4156-958c-3b7cffbae606",
"eventType": "product AR not available",
"eventMetadata": {},
"orgId": "d7e8d7a2-93b1-43d5-bf20-32195396598c",
"assetId": "6e4b65b7-862b-4cd9-b183-c07d82d5beed",
"assetName": "Example Product A",
"assetMetadata": {},
"configId": "94e932d8-4edf-4198-a8c4-097fab9402d5",
"configuration": {},
"userId": null,
"sessionId": "b6f1b4b7-fd44-461d-8b90-79561a716370",
"device": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36",
"referer": "https://examplewebsite.com/examplepagea",
"createdAt": "2020-07-30T15:27:23.058Z"
}
]
}
{
"error": {
"type": "unauthorized",
"message": "Unauthorized"
}
}
GET https://admin.threekit.com/api/analytics/events/{id}
Retrieve the details of an event. This includes the asset name and asset metadata, if applicable. Each event contains the following field.
- id - Id of the event
- eventType - Type of event. Currently the supported event types are - 'product download', 'product session start', 'product session end', 'product configuration set', 'product configuration attribute set', 'product interaction', 'product cart-add', 'product ordered', 'product social share', 'product AR not available', 'product AR offered', 'product AR download', 'product AR mobile transition offered', 'product AR mobile transition completed'
- eventMetadata - User defined metadata for an event
- orgId - ID of the org linked to the event
- assetId - Id of the asset linked to the event, if applicable
- userId - Id of the user linked to the session for which events are being stored
- sessionId - Id of the session for which the events are being stored
- configId - Id of the configuration of asset, if applicable, linked to the event
- configuration - Full configuration object of the asset, if applicable, linked to the event
- device - Information about the device linked to the event. This is the User-Agent header present in the request when creating the event
- createdAt - Event creation date
REST Endpoint
GET https://admin.threekit.com/api/analytics/events/{id}?bearer_token=[bearer_token]
Query Parameters
Name |
In |
Type |
Required |
Description |
id |
path |
string |
true |
ID of the event to be retrieved |
bearer_token |
query |
string |
false |
Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token. |
Response Codes
Status |
Meaning |
Description |
Schema |
200 |
OK |
Fetch a specific event by its id |
None |
404 |
Not Found |
Request to fetch an event using an invalid id |
None |
Example Implementations
Code
CURL
curl --request GET \
--url https://admin.threekit.com/api/analytics/events/string \
--header 'authorization: Bearer {access-token}'
Node.JS
var http = require("https");
var options = {
"method": "GET",
"hostname": "admin.threekit.com",
"port": null,
"path": "/api/analytics/events/string",
"headers": {
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://admin.threekit.com/api/analytics/events/string",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer {access-token}"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Example responses
[
{
"id": "78aa0bcc-ed1f-4156-958c-3b7cffbae606",
"eventType": "product AR not available",
"eventMetadata": {},
"orgId": "d7e8d7a2-93b1-43d5-bf20-32195396598c",
"assetId": "6e4b65b7-862b-4cd9-b183-c07d82d5beed",
"assetName": "Example Product A",
"assetMetadata": {},
"configId": "94e932d8-4edf-4198-a8c4-097fab9402d5",
"configuration": {},
"userId": null,
"sessionId": "b6f1b4b7-fd44-461d-8b90-79561a716370",
"device": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36",
"referer": "https://examplewebsite.com/examplepagea",
"createdAt": "2020-07-30T15:27:23.058Z"
}
]
{
"error": {
"type": "event_not_found",
"message": "Event not found"
}
}
GET https://admin.threekit.com/api/analytics/events/views
Allows a user to fetch analytics based on different event types. By default the period is fetches events for, are the subscription start date of the org and the current date.
REST Endpoint
GET https://admin.threekit.com/api/analytics/events/views?bearer_token=[bearer_token]&orgId=[orgId]&metadata=[metadata]&device=[device]&referer=[referer]&subStartDate=[subStartDate]&endDate=[endDate]&range=[range]&eventType=[eventType]
Query Parameters
Name |
In |
Type |
Required |
Description |
bearer_token |
query |
string |
false |
Public access token used to authorize the request. Requests may only come from the token's allowed domains. This parameter is mandatory when making requests from a browser. Outside of the browser instead supply a bearer header using a private access token. |
orgId |
query |
string |
false |
Retrieve list of products of a particular organization. For the token's organization, it retrieves the list of all products. For a public organization it retrieves the list of shared products. |
metadata |
query |
string |
false |
Retrieve information by their metadata. Must be passed in as a stringified JSON. |
device |
query |
string |
false |
Retrieve events with a specific user agent header. Must be converted to an escaped query string. |
referer |
query |
string |
false |
Retrieve events for for a specific page(referer header). This can also be used to fetch all events for a specific origin header. Must be converted to an escpaed query string. |
subStartDate |
query |
string |
false |
Set the starting date to fetch views from. It defaults to the subscription start date if this parameter is not provided. The accepted foramt is YYYY/MM/DD. |
endDate |
query |
string |
false |
Set the end date of the period to fetch views from. It defaults to the current date if not provided. |
range |
query |
string |
false |
Fetch views by range. This can either be annual, monthly or daily views. It only accepts three values - "year", "month" or "date". |
eventType |
query |
string |
false |
Fetch views based on a specific event |
Enumerated Values
Parameter |
Value |
range |
year |
range |
month |
range |
day |
eventType |
product download |
eventType |
product session start |
eventType |
product session end |
eventType |
product configuration start |
eventType |
production configuration attribute set |
eventType |
product cart-add |
eventType |
product ordered |
eventType |
product social share |
eventType |
produce AR not available |
eventType |
product AR offered |
eventType |
product AR download |
eventType |
product AR mobile transition offered |
eventType |
product AR mobile transition completed |
eventType |
product renders |
Response Codes
Status |
Meaning |
Description |
Schema |
200 |
OK |
Analytics of an event type specific org. It will list the annual, monthly or daily annalytics depending on the range query parameter |
None |
Example Implementations
Code
CURL
curl --request GET \
--url https://admin.threekit.com/api/analytics/events/views \
--header 'authorization: Bearer {access-token}'
Node.JS
var http = require("https");
var options = {
"method": "GET",
"hostname": "admin.threekit.com",
"port": null,
"path": "/api/analytics/events/views",
"headers": {
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
PHP
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://admin.threekit.com/api/analytics/events/views",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer {access-token}"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Example responses
[
{
"count": 2,
"perPage": 30,
"page": 1,
"sort": "-cumulative",
"views": [
{
"year": 2021,
"views": 3000,
"cumulative": 3000
},
{
"year": 2020,
"views": 2000,
"cumulative": 2000
}
]
}
]
[
{
"count": 2,
"perPage": 30,
"page": 1,
"sort": "-cumulative",
"views": [
{
"year": 2021,
"month": 5,
"views": 300,
"cumulative": 500
},
{
"year": 2021,
"month": 4,
"views": 200,
"cumulative": 200
}
]
}
]
[
{
"count": 2,
"perPage": 31,
"page": 1,
"sort": "-cumulative",
"views": [
{
"year": 2021,
"month": 5,
"day": 5,
"views": 10,
"cumulative": 25
},
{
"year": 2021,
"month": 5,
"day": 4,
"views": 15,
"cumulative": 15
}
]
}
]
Schemas
createBody
{
"eventType": "product session start",
"eventMetadata": {},
"orgId": "91e138bc-fada-44e7-bc6c-492620622570",
"assetId": "bee4a155-5b92-48ad-b3fb-f14a235637a5",
"userId": "9a04aeee-ecae-4edd-9462-0f36341e83e9",
"sessionId": "553eedf9-a42e-465e-a833-894109ec21ac",
"configId": "613ed936-5137-4029-99d7-2ea1e48dec5b",
"configuration": {},
"device": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0",
"metric": 1
}
Properties
Name |
Type |
Required |
Restrictions |
Description |
eventType |
string |
true |
none |
Specify the type of event to be stored. The supported event types ar listed below |
eventMetadata |
object |
false |
none |
User defined event related metadata |
orgId |
string |
true |
none |
ID of the org linked to the event |
assetId |
string |
false |
none |
ID of the asset linked to the event |
userId |
string |
false |
none |
ID of the user using the session linked to the event |
sessionId |
string |
true |
none |
ID of the session linked to the event |
configId |
string |
false |
none |
ID of the configuration of a product. This can either be the short ID or the complete UUID of the configuration stored in configurations-service |
configuration |
object |
false |
none |
Complete configuration object of a product. This can be used in place of configId place as well |
device |
string |
false |
none |
This is the device being used for the session linked to the event. By default it will be extracted from the User-Agent header present in a request |
metric |
float |
false |
none |
Can be used to store arbitrary metric for an event. It defaults to 1 if not provided. Numbers with decimal places are supported |
Enumerated Values
Property |
Value |
eventType |
product download |
eventType |
product session start |
eventType |
product session end |
eventType |
product configuration start |
eventType |
production configuration attribute set |
eventType |
product cart-add |
eventType |
product ordered |
eventType |
product social share |
eventType |
produce AR not available |
eventType |
product AR offered |
eventType |
product AR download |
eventType |
product AR mobile transition offered |
eventType |
product AR mobile transition completed |