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.
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 product. 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 product specific information once a newly uploaded product 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:
-
Log in using an Authentication Key or email / password.
-
Returns an x-auth-token in the Response Headers.
-
-
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.
-
-
Generate a Refresh Token for the Organization.
-
Pass the x-auth-token from Step 1 in the Request Headers.
1234{‘x-auth-token’ : ‘Bearer ‘ + x_auth_token‘organizationUuid’ : ‘string’} -
Returns the Refresh Token as the Response Header x-auth-token.
-
-
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.
-
-
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.
12345{‘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 Product on the VNTANA Platform that you wish to manage Hotspots on. This uuid can be retrieved from a search using the VNTANA API and a variety of product details such as name, tags, or attributes. View this guide on Searching Products. Note: Products 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 Product 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 will require 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
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 a product is:
- dimensions: Indicates the position in 3D space of the Hotspot as well as it’s normal.
- productUuid: Unique identifier of the product 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:
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.
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:
To do this, you will need the clientUuid that the product 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:
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:
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 a product, 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 a Product:
- 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 Product 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:
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 Product 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.