VNTANA Logo - White
Book a Call
Get Started Free

Resources

API – Analytics

API Base URL: https://api-platform.vntana.com

For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.

When you publish your 3D to the VNTANA Platform and share it externally, we will keep track of a few handy metrics for you. These include 3D views, AR views, and user interaction (interaction within the viewer itself), and through the Admin API this information can be obtained and easily integrated into your own systems. The data can be filtered by a date interval and categorized by device type of users, and a domain can be added to your individual Products to allow for the retrieval of the metrics generated by a specific domain.

Authentication

As with all usage of the Admin API, you must first generate a valid refresh token. This refresh token will be used by each endpoint to indicate the Organization the data should be pulled from. Below is a condensed version of the Authentication flow, or for a complete guide visit this resource.

  1. Log in using an Authentication Key or email / password.

    • Returns an x-auth-token in the Response Headers.

  2. Retrieve a list of Organizations and store the needed Organization’s UUID.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      { ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token }

    • This step can be skipped if the Organization UUID is already stored locally.

  3. Generate a Refresh Token for the Organization.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      2
      3
      4
      {
      ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token
      ‘organizationUuid’ : ‘string’
      }

    • Returns the Refresh Token as the Response Header x-auth-token.

  4. Retrieve a list of Clients / Folders and store the needed UUID.

    • Pass the x-auth-token in the Request Headers.

    • This step can be skipped if the Client / Folder UUID is already stored locally.

  5. Generate a Refresh Token for the Client / Folder (Organization Admin / Owner users must skip this step).

    • Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Client UUID’s.

      1
      2
      3
      4
      5
      {
      ‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
      ‘organizationUuid’ : ‘string’,
      ‘clientUuid’ : ‘string’
      }

    • Returns the Refresh Token as the Response Header x-auth-token.

Retrieving Metrics Dashboard

If you just want to retrieve a general overview of the totals, you can call your metrics dashboard. For a single Organization, this endpoint will return the totals for 3D views, AR views, and user engagement, as well as the individual metrics and product details of the most viewed product during the indicated date interval. The returned metrics can also be filtered by folders, products, and a single domain. The endpoint is the following:

1
2
3
4
5
6
7
8
9
10
Endpoint: /v2/metrics/dashboard
Method: POST
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
“startDate”: “2023-06-01T00:00:00”,
“endDate”: “2023-07-01T23:59:59”,
“clientUuids” : [“string”],
“productsUuid” : [“string”],
“domain”: “vntana.com”
}

The request body takes a number of filters to produce the metrics you wish to view.

  • startDate: [string] Timestamp indicating the earliest date to grab the metrics from.

  • endDate: [string] Timestamp indicating the latest date to grab the metrics from.

  • clientsUuids: [string array] List of UUID’s for all Folders you wish to include in the metrics returned. Pass null to include all.

  • productsUuid: [string array] List of UUID’s for all Products you wish include in the metrics returned. Pass null to include all.

  • domain: [string] The domain where the 3D viewers are embedded. This must be included in the embed code / share link when you add it to your site. Pass null to include all.

A successful response will look like the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
{
“success”: true,
“errors”: [],
“response”: {
“total3DViews”: 1659,
“totalARViews”: 4,
“userEngagement”: 4,
“avgNumberInteractions”: 2,
“mostViewedProduct”: {
“productUuid”: “string”,
“productDetails”: {
“updatable”: true,
“uuid”: “string”,
“clientUuid”: “string”,
“organizationUuid”: “string”,
“name”: “string.glb”,
“description”: “”,
“locations”: [],
“tags”: [],
“attributes”: {},
“status”: “LIVE_PUBLIC”,
“conversionStatus”: “COMPLETED”,
“materialBlobId”: null,
“asset”: {
“generationRequestUuid”: “string”,
“thumbnailBlobId”: “string.png”,
“thumbnailSize”: 1309710,
“assetBlobId”: “string.glb”,
“assetOriginalName”: “string.glb”,
“assetOriginalSize”: 113770992,
“conversionFormats”: [
“GLB”,
“USDZ”,
“FBX”
],
“models”: [
{
“uuid”: “string”,
“conversionFormat”: “GLB”,
“modelBlobId”: “string.glb”,
“modelSize”: 12459496,
“conversionStatus”: “COMPLETED”,
“error”: null,
“optimizationThreeDComponents”: {
“poly”: 160041,
“tri”: 160041,
“vertex”: 92821
},
“originalThreeDComponents”: {
“poly”: 618104,
“tri”: 618104,
“vertex”: 981978
}
},
{
“uuid”: “string”,
“conversionFormat”: “FBX”,
“modelBlobId”: “string.fbx”,
“modelSize”: 15027072,
“conversionStatus”: “COMPLETED”,
“error”: null,
“optimizationThreeDComponents”: {
“poly”: 160041,
“tri”: 160041,
“vertex”: 92821
},
“originalThreeDComponents”: {
“poly”: 618104,
“tri”: 618104,
“vertex”: 981978
}
},
{
“uuid”: “string”,
“conversionFormat”: “USDZ”,
“modelBlobId”: “string.usdz”,
“modelSize”: 12320226,
“conversionStatus”: “COMPLETED”,
“error”: null,
“optimizationThreeDComponents”: {
“poly”: 160041,
“tri”: 160041,
“vertex”: 92821
},
“originalThreeDComponents”: {
“poly”: 618104,
“tri”: 618104,
“vertex”: 981978
}
}
],
“retry”: false,
“conversionStatusDetails”: {
“GENERATE_THUMBNAILS”: “ACTION_COMPLETED”,
“GENERATE_WEB_FORMATS”: “ACTION_COMPLETED”
}
},
“autoPublish”: false,
“rendererConfigs”: “{\”autoRotate\”:false,\”showEnvironment\”:false,\”environment\”:\”Default\”,\”exposure\”:1.2,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”Transparent\”,\”yaw\”:0.6253755867801701,\”pitch\”:1.3678558177515272,\”distance\”:0.5286963127619948,\”fov\”:27.77109754165616,\”targetPointX\”:0.010051338168805648,\”targetPointY\”:0.0013893968360488178,\”targetPointZ\”:-0.007128788613566205,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:true,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”zoomLimits\”:{\”minimumRadius\”:-1,\”maximumRadius\”:-1,\”minimumFieldOfView\”:-1,\”maximumFieldOfView\”:-1},\”shading\”:\”diffuse\”}”,
“modelOpsParameters”: {
“OPTIMIZATION”: {
“desiredOutput”: “AUTO”,
“obstructedGeometry”: “true”,
“poly”: “75000”,
“forcePolygonCount”: “false”
},
“DRACO_COMPRESSION”: {
“enabled”: “true”
},
“TEXTURE_COMPRESSION”: {
“aggression”: “2”,
“maxDimension”: “4096”,
“lossless”: “false”,
“useKTX”: “false”,
“bakeAmbientOcclusion”: “true”
},
“AR_SCALING”: null,
“ORIENTATION”: null,
“PIVOT_POINT_ALIGNMENT”: {
“pivotPoint”: “center”
}
},
“created”: “2022-12-19T20:56:36.041”,
“updated”: “2023-07-14T03:08:42.044”,
“pipelineUuid”: “664a5d17-18d0-4bed-86b6-ab89Bcfa0b23”,
“presetUuid”: null,
“presetName”: null,
“isUpdatable”: true,
“variantGroups”: null,
“integrationAttributes”: {}
},
“total3DViews”: 57,
“totalARViews”: 0,
“userEngagement”: 4,
“avgNumInteractions”: 2
}
}
}

There is a lot of data returned pertaining to the most viewed product. This includes the individual metrics recorded for it, as well as information on all the optimized formats of the Product.

Retrieving 3D or AR Views Data

If you wish to retrieve a breakdown of the 3D or AR view data, you can call the following endpoint:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Endpoint: /v2/metrics/views-data
Method: POST
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
“viewType”: “3DView” or “ARView”,
“actionTypes”: [“view”] or [“click”, “scan”],
“returnFields”: [“device”],
“startDate”: “2022-12-01T00:00:00”,
“endDate”: “2023-01-17T23:59:59”,
“dateInterval”: “WEEK”,
“clientUuids”: [“string”],
“productsUuid”: [“string”],
“domain”: null
}

This endpoint must be called individually for either 3D or AR views, with the viewType parameter determining which is returned.

  • viewType: [string] Indicates whether to return 3D or AR views. Takes 3DView or ARView.

  • actionTypes: [string array] Indicates the devices to consider when returning the views data. Takes view if looking for 3DView data or click and scan.

  • returnFields: [string array] Pass device to have the response data indicate what device type each entry pertains to.

  • startDate: [string] Timestamp indicating the earliest date to pull data from.

  • endDate: [string] Timestamp indicating the latest date to pull data from.

  • dateInterval: [string] Indicates how to partition the data, takes DAY, WEEK, or MONTH.

  • clientUuids: [string array] List of Folder UUID’s you wish to pull the data from. Pass null to include all.

  • productsUuid: [string array] List of Product UUID’s you wish to pull the data from. Pass null to include all.

  • domain: [string] A domain you wish to filter the results by. Unless the domain has been properly added to your Products embed code / share link this won’t return any data. Pass null to include all.

The response will vary depending on the information provided, with the general structure being the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 21,
“grid”: [
{
“deviceCategory”: “desktop”,
“dateInterval”: “20230627”,
“count”: 9
},
{
“deviceCategory”: “desktop”,
“dateInterval”: “20230605”,
“count”: 51
}
]
}
}

A successful response will return a list of entries based on the criteria set in the request. Each entry will include:

  • count: The number of recorded 3D or AR views.

  • dateInterval: Condensed timestamp indicating the dates included in the count. This is based on the dateInterval parameter passed in the request body, and will contain different data depending on the interval type passed.

    • The above example response is based on a DAY interval, showing the full date – 20230605 is year+month+day so it is June 5th, 2023.

    • If WEEK is passed, the timestamp will be returned as year+week. If the actual date range desired was June 1st, 2023 to July 1st, 2023, then for a WEEK interval, you might get an entry with a dateInterval response as 202322, because June 1st falls in the 22nd week of 2023.

    • if MONTH is passed, it’ll simply be year+month, so for the date range of June 1st, 2023 to July 1st, 2023 you might see an entry with dateInterval of 202306.

  • deviceCategory: Indicates the device type the entry is for. Can be desktop, mobile, or tablet.

Retrieving a Summary Report

Finally, you can also generate a summary report containing all applicable Products and their individual 3D, AR, and user engagement metrics broken down by device type. The response is a base64 encoded string that can be decoded and stored as an excel sheet.

The endpoint to retrieve this report is as follows:

1
2
3
4
5
6
7
8
9
10
Endpoint: /v2/metrics/summary-report
Method: POST
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Request Body: {
“startDate”: “2022-11-01”,
“endDate”: “2022-12-31”,
“clientUuids”: [“string”],
“productUuids”: [“string”],
“domain”: “string”
}

  • startInterval: [string] Timestamp indicating earliest date to pull data from.

  • endInterval: [string] Timestamp indicating latest date to pull data from.

  • clientUuids: [string array] List indicating the Folder UUID’s from which you wish to view the data. Pass null to include all.

  • productUuids: [string array] List indicating the Product UUID’s you wish to include in the summary. Pass null to include all.

  • domain: [string] A domain you wish to filter the results by. Unless the domain has been properly added to your Products embed code / share link this won’t return any data. Pass null to include all.

The response will contain the following information:

1
2
3
4
5
6
7
8
{
“success”: true,
“errors”: [],
“response”: {
“document”: “base64 encoded string”,
“contentType”: “application/vnd.openxmlformats-officedocument.spreadsheetml.sheet”
}
}

The document contains the report as a base64 string representation of the excel data. 

The Domain Parameter

Each of the above endpoints has a request parameter called domain. This allows you to filter the metrics returned by only those generated at a specific domain. However, in order for a metric capture to be tied to the domain it occurred at, the domain has to be added as a parameter to either the iframe embed code or the share link. Only one domain can be added to the embed at a time, but you can have different domains in the same Products embed code on multiple sites. Meaning you can use domain A in the embed code added to site A, while using domain B in the same Products embed code that’s added to site B.

For more information on embed codes / share links, visit this guide.

Postman Collection

You can download the below Postman collection to test out each of these Metrics. The collection includes everything needed to run a chain of endpoints for Authentication, while the Metrics endpoints will require some manual input for the various parameters needed in these endpoints. To run any part as a collection, simply uncheck any Authentication endpoints you don’t need based on your user access (see our Authentication guide for a detailed explanation) as well as enter the Metrics parameters you wish to pass along for filtered results. 

To run the endpoints individually, make sure to activate the deactivated X-AUTH-TOKEN header for each endpoint, and ensure all the necessary parameters are entered in the body or query params of each. For more information on using Postman collections, see our guide.

Postman

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.
Learn More

Tap the magnifying glass to the left of your screen to search our resources.

OK