3D CMS Documentation

Below you will find a growing collection of documentation related to VNTANA’s software offerings.

Rest API Documentation V1.0

Rest API Quick Start Guide

This guide will give you a brief overview of how to use the VNTANA Admin API in order to login to our Platform, authenticate your account, and retrieve your organizations, clients, products, and any additional information about your products, such as tags and locations. For a more comprehensive overview of our API, please check out our detailed API Documentation here.

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

1. Login to the VNTANA Platform

  • Use the following endpoint to authenticate
Method: POST
Endpoint: /v1/auth/login
Sample Request Body: { “email”: “[email protected]”, “password”: “YourPassword1” }
  • On successful authentication, a temporary user authentication token, X-AUTH-TOKEN, will be returned in the Response Headers.

2. Retrieve your Organizations List

  • After authentication, you can retrieve the list of your Organizations using the X-AUTH-TOKEN Response Header from Step 1.
Method: GET
Endpoint: /v1/organizations
Headers: { “x-auth-token”: “Bearer ” + token }
  • The token is the X-AUTH-TOKEN value retrieved after logging in. Don’t forget to add “Bearer ” before your token value.

  • The response has the list of all the Organizations in your Platform account, including important details such as the name, role, slug, and uuid of each Organization.

3. Authenticating a specific Organization (Retrieve the Refresh Token)

  • In order to authenticate a specific Organization to see the Clients and Products for that Organization, you must retrieve the Refresh Token, which is an Organization-specific token.

  • Pass the X-AUTH-TOKEN, as well as the UUID of the Organization you would like to view, as headers in the following endpoint:

Method: POST
Endpoint: /v1/auth/refresh-token
Headers: { “x-auth-token”: “Bearer ” + token, “organizationUuid”: uuid }
  • The token is still the same X-AUTH-TOKEN retrieved after successfully logging in, and the Organization UUID can be found from the list of Organizations returned in Step 2.

  • On successful authentication of the selected Organization, you will receive another X-AUTH-TOKEN Response Header. This is the Refresh Token for this Organization. Please keep in mind that the X-AUTH-TOKEN from Step 1 is different from the one described in this step (Step 3).

  • You can now access your Clients and Products for this Organization!

4. Retrieve Clients List for selected Organization

  • Pass the Refresh Token retrieved from the previous step (Step 3) to the following endpoint in order to get your list of Clients for the selected Organization:
Method: GET
Endpoint: /v1/clients/client-organizations
Headers: { “x-auth-token”: “Bearer ” + refreshToken }
  • A successful response will return the list of Clients for the selected Organization, as well as the name, role, slug, uuid, and other details for each Client.

5. Retrieve Products for Selected Client

  • In order to view the Products for a single Client, use the following endpoint:
Method: POST
Endpoint: /v1/products/clients/{clientUuid}/search
Sample Request Body: { “page”: 1, “searchTerm”: “string”, “size”: 10, “status”: “LIVE” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }
  • The list of Products retrieved can be filtered in a number of ways, including by Search Term, Tags, Locations, and Conversion Statuses. Please reference the linked full API Documentation above to see the different parameters accepted in the Request Body for this endpoint.

  • The “x-auth-token” header here also requires the Refresh Token (Organization-specific token) from Step 3.

6. Retrieve Locations

  • Use the following endpoint to get the list of Locations created under a specific Client:
Method: POST
Endpoint: /v1/locations/search
Sample Request Body: { “clientUuid”: clientUuid, “page”: 1, “size”: 5, “searchTerm”: “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }
  • The UUID for the selected Client must be passed in the request body.

  • Locations can be filtered by page, size, search term, and date. Please see the full API Documentation for a complete list of search filters.

  • The Refresh Token from Step 3 must also be passed as an “x-auth-token” header.

7. Retrieve Tags

  • Use the following endpoint to get the list of Tags created under a specific Client:
Method: POST
Endpoint: /v1/tags/search
Sample Request Body: { “clientUuid”: clientUuid, “page”: 1, “size”: 12, “searchTerm”: “string” }
Headers: { “x-auth-token”: “Bearer ” + refreshToken }
  • The UUID for the selected Client must be passed in the request body.

  • Tags can be filtered by page, size, and search term.

  • The Refresh Token from Step 3 must also be passed as an “x-auth-token” header.

Additional Notes

  • In order to authenticate another Organization, the Refresh Token for that Organization must be retrieved (repeat Step 3). Simply pass the temporary user authentication token from Step 1, as well as the UUID of the Organization you wish to view (retrieved from Step 2), into the Refresh Token endpoint (Step 3). On success, you will be able to see the Refresh Token (Organization-specific token) for the Organization you have selected to view.

  • Once you have the new Refresh Token, you can repeat Steps 4-7 in order to retrieve the Clients, Products, Locations, and Tags for that Organization.

3D Webviewer

Integrate VNTANA 3D Web Viewer via iFrame

Steps to Obtain iFrame Embed Code

  1. Login to your account on the VNTANA Platform
  2. Click on Products in the left-hand navigation menu
  3. Select the Product you want to view
  4. In the Embed Code section from the Product View Page, click on the Copy button to copy the entire Embed Code (circled in red below). The iFrame is now copied to your clipboard and can be used anywhere on your site. Just paste it in the HTML of the page you would like to include the 3D Web Viewer.

Additional Notes

  • Make sure your Product is LIVE, so it can be viewed publicly. Click the “Publish to API” button from the Product View Page to publish your product and set its review state to Live.
  • The <iframe> src is the URL to the 3D asset in a Standalone Viewer Page. This shareable link can be copied by clicking the Share button, which is below the Copy button.
  • The asset can easily be swapped out for another asset in your Product List by changing the productUuid value. productUuid can be found on the Product View Page labeled Product ID (see pictures below).
  • The Client Slug and Organization Slug are static values for all of your Products under the same Client and Organization.

Updating Appearance and Controls in 3D Web Viewer

Before adding the 3D Web Viewer to your site, you may want to update and finalize the appearance of the 3D asset and the controls you want available to viewers of your website. You can update these settings by clicking on the Settings button in the 3D Viewer from the Product View Page.

  • Wireframe
    • Check this option if you want to show the Wireframe of the model.
  • Normals
    • Check if you want to show the Normals for the model.
  • Rotate
    • Check if you want the 3D asset to slowly rotate around its center, allowing users to passively view all angles of the asset.
  • Enable Zoom
    • Default setting is checked. Uncheck this option if you do not want users to be able to zoom in and out of the 3D asset by scrolling.
  • Exposure
    • Increase or decrease the amount of light in the viewer.
  • Lighting
    • Choose the HDRI map in which you want to display your 3D model.

Styling the 3D Web Viewer

  • The width and height of the <iframe> can be changed to better fit your site.
  • The <iframe> style can be updated with custom CSS if needed.
  • The background color of the viewer is white. More background options, including a transparent background, will be added soon for greater customization on your site!

VNTANA Viewer Component Integration

Overview

The VNTANA Viewer is an optimized, standards compliant rendering platform for displaying Khronos GLTF 2.0 content in browsers that provide full support for WebGL 2.0. The viewer component has been developed to be a portable JavaScript Universal Module Definition (UMD) library able to be dynamically loaded and included in web apps or web components. The library includes all dependencies and GUI controls in the packaged component and is therefore standalone and has no dependencies.

Library functions, parameters, and integration

To integrate the viewer into an existing web app or component requires including the UMD module vnview.js using an HTML <script> tag or dynamic loading method. It also requires including the styles.css CSS file.

The library currently exposes one function, createvnviewer, on the global namespace vnview which creates and returns a viewer class that can be used to load and render content.

var viewer = vnview.createvnviewer(element, options);

The element parameter is an HTML5 DOM element that will contain the viewer. If this element is an existing HTML5 Canvas element, that will be used as the canvas element for WebGL rendering. If element parameter is not an HTML5 Canvas, the DOM element will be used as the parent element for a new HTML5 Canvas element that is the size of the parent element.

The options parameter is a JavaScript object that defines parameters for the setup and context of the viewer. To use an embedded viewer, the following options object should be used:

var options = {embedded: true, preset: ”, cameraPosition: null};

Viewer content

GLTF content can be loaded into the viewer using the loadObject(url) method which takes a url to the model file:

viewer.loadObject(url)
.catch((e) => onError(e))
.then(() => { cleanup(); });

onError() and cleanup() are application specific asynchronous callbacks to handle errors or cleanup (hiding a spinner animation after successfully loading the content for example).

If the loadObject method is called again, it will remove the existing content and load the new model. The content of the viewer can be cleared by calling the clear() method of the viewer class:

viewer.clear()

Contact [email protected] to request access to our Viewer Component Library source code.