Please be aware there is a known issue with images on the Community. We are working to resolve this issue as quickly as possible. We apologize for the inconvenience. If you need urgent help in the meantime, please reach out to technical support or your Threekit representative.

  1. Threekit
  2. Developer Documentation
  3. Connecting and Displaying Externally (APIs)
  4. APIs

Analytics API

In this article

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.

  1. id - Id of the event
  2. 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'
  3. eventMetadata - User defined metadata for an event
  4. orgId - ID of the org linked to the event
  5. assetId - Id of the asset linked to the event, if applicable
  6. userId - Id of the user linked to the session for which events are being stored
  7. sessionId - Id of the session for which the events are being stored
  8. configId - Id of the configuration of asset, if applicable, linked to the event
  9. configuration - Full configuration object of the asset, if applicable, linked to the event
  10. device - Information about the device linked to the event. This is the User-Agent header present in the request when creating the event
  11. 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.

  1. id - Id of the event
  2. 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'
  3. eventMetadata - User defined metadata for an event
  4. orgId - ID of the org linked to the event
  5. assetId - Id of the asset linked to the event, if applicable
  6. userId - Id of the user linked to the session for which events are being stored
  7. sessionId - Id of the session for which the events are being stored
  8. configId - Id of the configuration of asset, if applicable, linked to the event
  9. configuration - Full configuration object of the asset, if applicable, linked to the event
  10. device - Information about the device linked to the event. This is the User-Agent header present in the request when creating the event
  11. 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
Was this article helpful? Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles

Powered by Zendesk