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
To create a Configurator, you must create a Product. While in the Product creation screen, an option will be present to Create or Add to an existing Configurator. Check this box, then select ‘New Configurator’ and enter the desired name of the Configurator. We generally recommend you name the Configurator after the base Product’s name if you’re only adding Colorways of one Product to the Configurator.
Once the Configurator has been created, you can add additional Products to it if they’ve already been uploaded. From the Product list view select one or more Products and click the ‘Add to Configurator’ button in the upper right corner.
Once your Configurator is created, it can be accessed via the Configurator tab in the Products view of your folder, as shown below.
Integrating Your Configurator
Just like with an individual Product, you can easily integrate the Configurator 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 Configurator on the Platform. From the Configurator’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 Configurator viewer, you can also copy an embed link which can be shared allowing anyone to view your Configurator 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 Configurator 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 Product’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 Configurator to be viewable via an iFrame or embed link it must be Published as must the individual Products within. If an individual Product 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 Products or the Configurator itself is not Published.
Configurator 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 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.
The Configurator View on the VNTANA Platform allows you to group products into one viewer. These products can be color variants of one product, or various unique products from one line. The Configurator 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 Configurator as accessible via our API, showing you how to create, view and edit a Configurator. 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.
Note: There is a discrepancy in how Configurators are referred to on the Platform and in the API. This feature is being built from a legacy feature of the VNTANA Platform called ‘Variants’, and as such the API Endpoints still refer to this feature as ‘Variant’.
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 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.
-
Create a Configurator
When working with Configurator’s you can either search for an existing Configurator or create one. Previously referred to as a ‘Variant Group’, in order to create a Configurator you will use the following Endpoint:
clientUuid: [Required] The UUID of the Client / Folder you wish to create the Configurator in.
description: [Optional] A description of the products included in the Configurator.
name: [Required] The name of the Configurator. Multiple Configurators can share the same name.
productsUuids: [Optional] A list of UUID’s for products to add to the Configurator. No products 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 Configurator. No tags need to be added at creation, they can be added after the fact. Note: these tags are linked to the Configurator only, not the individual products that are added to the Configurator.
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 Configurator:
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 Configurator Collection
Search Configurators
In order to add Products to a Configurator that has already been created, you need to have the UUID of the Configurator. 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 Client / Folder UUID’s to pull Configurator’s 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 Configurator’s.
Search Term Usage Example:
There are two Configurators, Test Configurator and Sample.
Test Configurator:
Includes products configurator_sample, test_product, product_1, and no tags.
Sample:
Includes products product_1, product_2, and the tag Test
If the searchTerm test is passed to the Endpoint, both Configurators will be returned because Test Configurator contains test in the Configurator name and Sample contains test as a tag. However, if sample is passed as the searchTerm, only the Configurator Sample, will be returned as the search Endpoint won’t detect that sample exists in one of the Product names within Test Configurator.
- totalCount: This represents the total number of Configurator’s 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 Configurator in question, used to add products.
- name: The name of the Configurator. This does not need to be unique when creating, so there can be multiple Configurator’s with the same name.
- productsUuids: List of products currently in the Configurator.
Any combination of parameters returned in the Response Body can be used to pull the correct Configurator from the list. This may require the use of other Endpoints before or after if choosing to use Product UUID’s to find a Configurator. See the above linked documentation to see how to search for Products.
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 Configurators Collection
Add Product to Configurator
Finally, the a Configurator without any Products isn’t very useful. To add to a Configurator that already exists, you will need to have the Configurators UUID as well as the Product UUID you wish to add. To see how to retrieve a Product UUID, view this guide on searching Products.
You’ll notice the two query parameters are both plural. You can add multiple Products in one API call and to multiple Configurators, 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 Configurator UUID’s that the Products were added to. To see more on Configurator 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 Product to Configurator Collection