VNTANA makes it easy to create 3D configurators. Simply upload multiple colorways and group them into one 3D web viewer. This is the fastest and easiest way to instantly deploy 3D configurators at scale. No coding or 3D model adjustments needed from your team. Our patented optimization ensures the individual 3D models load fast, versus having to build a single, custom 3D model with multiple textures and materials.
Creating a Simple Configurator / Variant Group
To create a Variant Group, you must create a Asset. While in the Asset creation screen, an option will be present to Create or Add to an existing Variant Group. Check this box, then select ‘New Variant Group’ and enter the desired name of the Variant Group. We generally recommend you name the Variant Group after the base Asset’s name if you’re only adding Colorways of one Asset to the Variant Group.
Once the Variant Group has been created, you can add additional Assets to it if they’ve already been uploaded. From the Asset Library list view select one or more Assets and click the breadcrumbs button and then ‘Add to Variant Group’ button in the upper right corner.
Once your Variant Group is created, it can be accessed via the Variant Groups tab under your Workspace in the left panel.
Integrating Your Variant Group
Just like with an individual Asset, you can easily integrate the Variant Group viewer in your site or as a shareable link. To add the viewer to any page you can generate a ready-to-go iFrame directly from the Variant Group on the Platform. From the Variant Group’s page, you will see the iFrame tag towards the top right, with two buttons. To copy the iFrame code, press the copy button circled below:
With this iFrame you can directly embed the viewer into your Website. You can also customize the size either by adding a class to the tag or simply adjusting the width and height. If you wish to disable the full screen capabilities, simply remove the paramter allow=”fullscreen” from the iFrame tag. Note: though the user won’t be able to enter full screen, the button will remain, see Embed Parameters below to hide the full screen button.
In addition to the ability to copy a ready-to-use iFrame of your Variant Group viewer, you can also copy an embed link which can be shared allowing anyone to view your Variant Group as a single page Viewer. This embed link is utilized by the iFrame which just containerizes the Viewer on your website. To copy this embed link, go to the page of the Variant Group you wish to share, and click the Share button next to the iFrame code, circled below.
Embed Parameters
In addition to the ability to customize the size of the iFrame viewer and adding your own CSS by using a class, you can change the buttons that are visible in the Viewer, just like with an individual Asset’s viewer. These settings are changed by attaching Query Parameters to the embed link.
- fullScreen=0 – By adding this to the embed link you will hide the full screen button from the viewer.
- mobileARView=0 – By adding this to the embed link you will hide the View in AR button when a user is viewing on a mobile device.
- qrCode=0 – By adding this to the embed link you will hide the View in AR button when a user is viewing on a desktop computer.
- domain= – Add this and set it equal to the domain where the iFrame will be embedded allowing you to filter Analytics data by the Domain Source from the Refine Report panel on the Analytics Dashboard, so you can easily track 3D Views per origin site.
An example embed link is: https://embed.vntana.com?productUuid=f015c218-b806-4dd1-9f1c-38342f181876&clientSlug=samples&organizationSlug=demo&fullScreen=0&mobileARView=0&qrCode=0
The embed link and iFrame can also be constructed via the API by retrieving the necessary information. For more information on this, view this guide.
Note: As mentioned above, in order for a Variant Group to be viewable via an iFrame or embed link it must be Published as must the individual Assets within. If an individual Asset is still a draft, it simply will not appear in the viewer and the viewer will show the following message if there are no Published Assets or the Variant Group itself is not Published.
Variant Group API Integration
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 Workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Workspace.
The Variant Group View on the VNTANA Platform allows you to group 3D Assets into one viewer. These products can be color variants of one product, or various unique products from one line. The Variant Group View can be used to compare models for QA purposes, or the embed link/iframe can be used to show a single viewer on your website for all the products you wish to include.
This guide will walk you through the features of the Variant Group as accessible via our API, showing you how to create, view and edit a Variant Group. For more information on other aspects of the VNTANA Platform API you can view this Quick Start Guide, or for a full list of API Endpoints view this page.
As with all Admin API endpoints, you must first properly authenticate and generate a Refresh Token. For a more detailed look at authenticate view this guide.
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 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.
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.
12345{‘x-auth-token’ : ‘Bearer ‘ + refreshToken,‘organizationUuid’ : ‘string’,‘clientUuid’ : ‘string’}Returns the Refresh Token as the Response Header x-auth-token.
Create a Variant Group
When working with Variant Group’s you can either search for an existing Variant Group or create one. Previously referred to as a ‘Variant Group’, in order to create a Variant Group you will use the following Endpoint:
clientUuid: [Required] The UUID of the Workspace you wish to create the Variant Group in.
description: [Optional] A description of the assets included in the Variant Group.
name: [Required] The name of the Variant Group. Multiple Variant Groups can share the same name.
productsUuids: [Optional] A list of UUID’s for assets to add to the Variant Groups. No assets need to be added at creation, they can be added after the fact.
tagsUuids: [Optional] A list of UUID’s for tags to add to the Variant Groups. No tags need to be added at creation, they can be added after the fact. Note: these tags are linked to the Variant Group only, not the individual assets that are added to the Variant Group.
This Endpoint passes parameters in the URL of the Post request and the refreshToken in the Request Headers. An example URL:
A successful response will return the UUID of the newly created Variant Group:
Test this process using the below Postman collection. To run the collection as a whole, simply set the necessary global variables and select the endpoints you wish to use. To run the endpoints individually simply activate the deactivated headers and ensure each endpoint has the necessary data. You can view our guide on Postman collections here.
Create a Variant Group Collection
Search Variant Groups
In order to add Assets to a Variant Group that has already been created, you need to have the UUID of the Variant Group. You can save this locally and skip this step, but if you need to find the UUID use the following Endpoint:
clientUuids: [Optional] A list of Workspace UUID’s to pull Variant Groups from.
page: [Required] Indicates the ‘page’ of results to be returned.
size: [Required] Indicates the number of results to return per page.
searchTerm: [Optional] Used to filter the list of returned Variant Groups.
Search Term Usage Example:
There are two Variant Groups, Test Variant Group and Sample.
Test Variant Group:
Includes assets variant_sample, test_product, product_1, and no tags.
Sample:
Includes assets product_1, product_2, and the tag Test
If the searchTerm test is passed to the Endpoint, both Variant Groups will be returned because Test Variant Group contains test in the Variant Group name and Sample contains test as a tag. However, if sample is passed as the searchTerm, only the Variant Group Sample, will be returned as the search Endpoint won’t detect that sample exists in one of the Product names within Test Variant Group.
The results of a successful Variant Group search will be structured as such:
- totalCount: This represents the total number of Variant Groups that matched the search criteria but does not represent the number of results returned. The size parameter passed in the Request Body determines the max number of results to be returned, so unless you know you should get the exact match first it is best to pass size large enough to get all results.
- uuid: The UUID of the Variant Group in question, used to add assets.
- name: The name of the Variant Group. This does not need to be unique when creating, so there can be multiple Variant Groups with the same name.
- productsUuids: List of assets currently in the Variant Group.
Any combination of parameters returned in the Response Body can be used to pull the correct Variant Group from the list. This may require the use of other Endpoints before or after if choosing to use Asset UUID’s to find a Variant Group. See the above linked documentation to see how to search for Assets .
Test this process using the below Postman collection. To run the collection as a whole, simply set the necessary global variables and select the endpoints you wish to use. To run the endpoints individually simply activate the deactivated headers and ensure each endpoint has the necessary data. You can view our guide on Postman collections here.
Search Variant Groups Collection
Add Asset to Variant Group
Finally, the a Variant Group without any Assets isn’t very useful. To add to a Variant Group that already exists, you will need to have the Variant Group UUID as well as the Asset UUID you wish to add. To see how to retrieve a Asset UUID, view this guide on searching Assets.
You’ll notice the two query parameters are both plural. You can add multiple Assets in one API call and to multiple Variant Groups, for both parameters the UUID’s simply need to be separated by a comma. An example URL looks like this:
A successful request will return a list of the Variant Group UUIDs that the Assets were added to. To see more on Variant Group API interactions view the full Admin API guide above.
Test this process using the below Postman collection. To run the collection as a whole, simply set the necessary global variables and select the endpoints you wish to use. To run the endpoints individually simply activate the deactivated headers and ensure each endpoint has the necessary data. You can view our guide on Postman collections here.
Add Asset to Variant Group Collection