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. 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!
Additional Information
Important: In order to create/update a Hotspot on a Product, the Product must be deactivated first. You should first check that the Product’s status is not LIVE, and if it is you must update the Product and set autoPublish to false. View the below example to see the update endpoint, and view the guide on Searching Products for a more detailed look at the available methods.
Before attempting to create a hotspot or Updating a product’s status, you can check the response body of a product search. If you’re implementing this and already know the productUuid and did not have to search products to obtain it, you can directly pull the given products information using this endpoint:
Simply add the productUuid to the endpoint’s URL. If you do not already have it, you will have to implement the search methods shown in this guide. Regardless of which method you choose, you will retrieve the following information:
You are looking for the parameter status. In this body, the status is LIVE which means you must first deactivate it so that it is in DRAFT status. To do this you can use the following endpoint:
This endpoint takes a list called items containing the status and uuid of each product you wish to change the status of. uuid here is the productUuid you are changing the status to. This same method can then be used after the Hotspot is created to update the status to LIVE.
Important: Remember to reset the Product’s status to LIVE after creating/updating a Hotspot otherwise the embedded viewer will not show the Product!
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.