Resources

API – Hotspots

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 hereNote: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Wprkspace.

To enhance the viewing experience of your 3D asset within the VNTANA viewer, you can add Hotspots to your model. These, like Annotations, are visible within the viewer at designated points within 3D space to bring your customers attention to important aspects of your asset. With Hotspots you can show relevant information such as product dimensions, provide a how-to video on setting up and using the product, or just generally highlight key information about the product. Unlike Annotations, Hotspots will be publicly visible within the viewer wherever it is embedded.

Using the VNTANA Admin API, you can automate the process of creating, updating, and searching Hotspots. These can be coupled with Webhooks to automatically add Asset specific information once a newly uploaded 3D file has completed it’s optimization.

When manually creating/viewing Hotspots on the VNTANA Platform, they will appear to the right of the viewer under the hotspots tab indicated below:

In this tab, you will be able to add new Hotspots as well as view, edit, or delete any existing Hotspots. Each Hotspot is numbered, and when one is deleted these numbers will re-adjust as needed. Additionally, by default the number will not appear in the embedded version of the viewer, but you can toggle the ‘Show Hotspot numbers in Share Links’ to show these numbers if it is important to draw the users attention to the points in a specific order.

Getting Started

As with all methods using the VNTANA Admin API, before being able to use the Hotspots API you will need to achieve the correct level of authentication. For a detailed guide on the steps involved, view this guide, otherwise view this brief overview:

  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 Workspaces and store the needed UUID.

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

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

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

    • Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Workspace UUIDs.

      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.

Once authenticated, the next required piece of information is the productUuid of the Asset on the VNTANA Platform that you wish to manage Hotspots on. This uuid can be retrieved from a search using the VNTANA API as well as a variety of asset details such as name, tags, or attributes. View this guide on Searching Assets. Note: Assets in Draft status cannot be searched via the API, only those in either the Live Internal or Live Public status will be returned. Alternatively, if you have a Webhook set up to indicate when a 3D Asset has finished processing, the productUuid will be passed in the Webhook notification that is sent. View this guide to learn more about Webhooks.

Creating Hotspots

As mentioned previously, Hotspots exist within 3D space and as such, when creating a Hotspot via the API you will need to pass a parameter indicating this point. This means that unless you already know the 3D coordinate of where you wish the Hotspot to exist, using the API to create a Hotspot may not produce the desired results as you cannot reposition the hotspot once it has been created.

This key parameter, dimensions, also requires very specific formatting and will not work if there are any issues in the format. An example of this parameter is

1
“dimensions” : “{\”position\”: \”0.0m 0.0m 0.0m\”,\”normal\”: \”0.0m 0.0m 0.0m\”}”

The important element here are the escaped quotes within the curly braces. \” must surround each individual piece within the curly braces otherwise the data won’t be parsed correctly on our end. With this in mind, the endpoint to create a Hotspot on an asset is:

1
2
3
4
5
6
7
8
9
10
Method: POST
URL: /v1/hotspots
Headers: { “x-auth-token” : “Bearer ” + refreshToken }
Body: {
“dimensions” : “{\”position\”: \”0.0m 0.0m 0.0m\”,\”normal\”: \”0.0m 0.0m 0.0m\”}”,
“productUuid” : “string”,
“title” : “string”,
“type” : “TEXT”,
(Additional parameters depending on “type”, see below for each types full Body)
}
  • dimensions: Indicates the position in 3D space of the Hotspot as well as it’s normal.
  • productUuid: Unique identifier of the Asset to add the Hotspot to.
  • title: The title of the Hotspot, this is only visible on the Platform, not on the embedded version of the Viewer.
  • type: The type of Hotspot. This indicates what kind of content the Hotspot will contain and can be TEXT, IMAGE, or VIDEO.

There are additional parameters required depending on the type of Hotspot that is being created. These include the information about the image, video or just the text to add. Each individual full body is as follows:

1
2
3
4
5
6
7
{
“dimensions” : “{\”position\”: \”0.0m 0.0m 0.0m\”,\”normal\”: \”0.0m 0.0m 0.0m\”}”,
“productUuid” : “string”,
“title” : “string”,
“type” : “TEXT”,
“text” : “string”
}
1
2
3
4
5
6
7
8
{
“dimensions” : “{\”position\”: \”0.0m 0.0m 0.0m\”,\”normal\”: \”0.0m 0.0m 0.0m\”}”,
“productUuid” : “string”,
“title” : “string”,
“type” : “IMAGE”,
“blobId” : “string”,
“description” : “string”
}
  • blobId: refers to the uuid of an image that has already been uploaded. To do this you will need to call a specific endpoint to upload. View the section below on uploading a Hotspot image.

  • description: text that will show up under the image in the Hotspot, this is public and as such will be visible in the embedded viewer.

1
2
3
4
5
6
7
8
9
{
“dimensions” : “{\”position\”: \”0.0m 0.0m 0.0m\”,\”normal\”: \”0.0m 0.0m 0.0m\”}”,
“productUuid” : “string”,
“title” : “string”,
“type” : “VIDEO”,
“url” : “string”,
“autoplaying” : true or false,
“description” : “string”
}
  • url: the link to the video you wish to embed in the Hotspot.

  • autoplaying: boolean flag indicating whether the video should auto-play or only play on click.

  • description: text that will show up under the image in the Hotspot, this is public and as such will be visible in the embedded viewer.

Uploading an Image for a Hotspot

To add an image to a Hotspot via the API, whether updating or creating the Hotspot, you must first upload the image. To do so, you will need to use the following endpoint:

1
2
3
4
5
Method: POST
URL: /v1/hotspots/upload/images
Headers: { “x-auth-token” : “Bearer ” + refreshToken }
Query Params: clientUuid
formData: imageFile

To do this, you will need the clientUuid that the Asset exists in. This should be readily available after the authentication process, but to see how to retrieve this view this guide. Successfully uploading the image will return the necessary blobId in the response body:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
“success”: true,
“errors”: [],
“response”: {
“blobId”: “string.png”,
“blobSize”: 128326,
“metaData”: {
“content-length”: “128326”,
“content-type”: “image/png”,
“original-name”: “string.PNG”,
“creator-uuid”: “”,
“requested-ip”: “”,
“created-date”: “2022-10-10 20:53:11”
}
}
}

Updating a Hotspot

This is very similar to creating a Hotspot, however you will need the uuid of the Hotspot you are updating. To see how to find this uuid, view the section on Searching Hotspots below. The endpoint to update is:

1
2
3
4
5
6
7
8
9
10
Method: PUT
URL: /v1/hotspots
Headers: { “x-auth-token” : “Bearer ” + refreshToken }
Body: {
“dimensions”: “string”,
“productUuid”: “string”,
“title”: “string”,
“type”: “TEXT”,
“uuid”: “string”
}

As with creating, there will be different pieces of data required depending on the type of Hotspot you are updating. Use the request body’s shown above but remember to add the uuid of the Hotspot!

Searching Hotspots

Should you need to retrieve any information on the available Hotspots for an asset, or to retrieve the Hotspots’ uuid to update it, you can use a simple endpoint to retrieve this information. Use the following to retrieve a list of the Hotspots on an Asset:

1
2
3
4
5
6
7
8
Method: POST
URL: /v1/hotspots/search
Headers: { “x-auth-token” : “Bearer ” + refreshToken }
Body: {
“page” : 0,
“size” : 10,
“productUuid” : “string”
}
  • page: indicates the page of results to return. For this endpoint 0 indicates the first page of results.
  • size: indicates the number of results that should be divided into each page. If this value is 10 and there are 11 results, the first 10 will be on page 0 and the last one will be on page 1.
  • productUuid: the uuid of the Asset to check Hotspots for.

The response will contain necessary information for each Hotspot found, including the type, blobId (for images), and url (for videos). An example response is:

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
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 3,
“grid”: [
{
“uuid”: “string”,
“type”: “TEXT”,
“productUuid”: “string”,
“title”: “Sizes”,
“dimensions”: “{\”position\”:\”0.09706711276947991m 0.1800602695730001m 0.11715832250490932m\”,\”normal\”:\”0.11383279720554229m 0.4353273432800462m 0.8930465824765799m\”}”,
“userUuid”: “string”,
“created”: “2022-10-10T18:00:47.687”,
“updated”: “2022-10-10T18:00:47.687”,
“text”: “Available in S, M, L, XL”
},
{
“uuid”: “string”,
“type”: “IMAGE”,
“productUuid”: “string”,
“title”: “Now available in Green!”,
“dimensions”: “{\”position\”:\”0.11843775115502342m 0.23042843486642145m -0.11125118207421836m\”,\”normal\”:\”0.22370296359694675m 0.25317451128934443m -0.9412011745165562m\”}”,
“userUuid”: “string”,
“created”: “2022-10-10T18:09:01.459”,
“updated”: “2022-10-10T18:09:01.459”,
“blobId”: “string.png”,
“description”: “There are 4 colors available, now including green!”
},
{
“uuid”: “string”,
“type”: “VIDEO”,
“productUuid”: “string”,
“title”: “”,
“dimensions”: “{\”position\”:\”-0.12214875213486452m 0.23683843220757944m 0.08215565938432401m\”,\”normal\”:\”-0.20375923104090954m 0.4363864658272103m 0.8763840643282226m\”}”,
“userUuid”: “string”,
“created”: “2022-10-10T19:57:11.708”,
“updated”: “2022-10-10T19:57:11.708”,
“url”: “string”,
“description”: “”,
“autoplaying”: false
}
]
}
}

Postman Collection

You can download the below Postman collection to test out each of these Hotspot based interactions. The collection includes everything needed to run a chain of endpoints for Authentication and Asset search, while the Hotspot 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 Hotspot parameters you wish to pass along such as the type

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.

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

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