VTEX IO

Find out what the Doris App for VTEX IO does for you:

Makes the widget installation faster and easier, with no need for coding or advanced technical knowledge

Integrates with the e-commerce product catalog, facilitating product management and display

Provides features for keeping the catalog updated, ensuring that product information is always correct

Integrates with the store's shopping cart, providing a smoother and more efficient shopping experience for customers

Some requirements and recommendations for installing the Doris app:

Doris Account
Make sure you have an account with Doris and have the necessary credentials when installing the app.

Testing Environment
‍We suggest using a test environment (workspace) to start the installation to validate the functionality of the Doris app before migrating it to the production environment (main workspace).

User Permissions
‍Verify if the user being used during the installation has appropriate permissions to install applications, set up configurations on the VTEX IO platform, and generate VTEX credentials (app key/token). See VTEX permissions requirements.

Prior Knowledge
‍We recommend having prior knowledge of installing applications using the VTEX IO Toolbelt (CLI) to streamline the process.

Step 1 - Installing the Doris app

1vtex install codeby.dorismobi 0.3.30

Locate the Doris app on the administration panel of your VTEX e-commerce, specifically in the Applications Management section, to begin the following configurations:

1. Enter the Doris Public API Key.

2. Insert an image URL to be displayed upon opening the Doris Widget (splash image). Download here a .psd template to create a custom image.

3. In the Doris button, you can add try-on images. For example:

a. Request the image from the Doris team and add the image address to the button;

b. If no images are specified, default Doris images will be used.

4. Customize the widget interface color to align with your company's branding by specifying a hexadecimal value
(e.g., #FFFFFF). If unspecified, the default Doris color will be used.

5. For catalog integration with the Doris Widget, specific attribute identifiers are required:

6. Enter your Doris Private Key.

7. Provide the following VTEX credentials to use the app:

VTEX App Key
VTEX App Token

The proper functioning of the Widget's features and catalog integration depends on having the necessary permissions for these credentials. You can find additional information on permissions in the VTEX permissions requirements section.

Product reference code (Ref_id), EAN code, or product code in VTEX (Vtex_id)
Attribute code that identifies color (e.g., color)
Parameter for product size identification (e.g., size)
Parameter for brand identification (e.g., brand)
Attribute for unique product grouping code (e.g., NetshoesProductGroup). This is not mandatory, but essential for grouping products with various colors

Step 2 - Installing Widget trigger button

The Doris App enables interface customizations for the Widget, including setting the primary color and the initial opening image (splash Image). These configurations can be adjusted at any time.

Add the codeby.dorismobi method as a peerDependencies in the manifest.json file in your e-commerce repository:

1peerDependencies {
2	“codeby.dorismobi”: “0.x”
3}

Include the doris-button block in a strategic location within the product context of your e-commerce theme, so that users can start the Widget experience. Here’s an example of how to insert it below the buy/add to cart button on the product page:

1{
2	“flex-layout.col#right-col”: {
3    “props”: {
4    	“preventVerticalStretch”: true,
5        “rowGap”: 0
6	{,
7    “children”: [
8      “flex-layout.row#product-name”,
9      “product-rating-sumary”,
10      “flex-layout.row#list-price-savings”,
11      “flex-layout.row#selling-price”,
12      “product-installments”,
13      “product-separator”,
14      “product-identifier.product”,
15      “sku-selector”,
16      “product-quantity”,
17      “product-assembly-options”,
18      “product-gifts”,
19      “flex-layout.row#buy-button”,
20      “doris-button”,
21      “availability-subscriber”,
22      “shipping-simulator”,
23      “share#default”
24    ]
25   }
26 }

Result:

Step 3 - Integrating catalog

It's essential to initially sync the product catalog and review it to ensure seamless functionality with the Doris Widget.

After completing all the previous steps, Doris' Operations team proceeds with the integration process, performing the following tasks:

Definition of pre-models avatars
E-commerce categories mapping
Product importation
Try-on review (homologation)
Widget's Go Live definition

It’s necessary for the e-commerce administration to designate a responsible person to support potential adjustments in product information, such as details and images.

VTEX permissions requirements

Catalog

Product Management
Product Form
SKU Images Management
Product and SKU Management
Fields List
Attributes Management
Value Fields List
Attribute Values Management
Category
Similar Category
Price Range
Providers
Supplier Management
Groups
Brands
SKUs
Field Validation
Value Field Validation

VTEX IO - Infrastructure

Read Workspace Apps
Link App
Install App
Vbase - read-only
Vbase - read-write
Read Workspace Services
Install Service
Log Access - read-only
Read Published Service
Debug App
Import Redirects
Workspace Manipulation
Read Edition
Allow APP Configuration
Change Sponsored Tenant Edition

Logistics Viewer

Logistics Inventory - read-only
Logistics Shipping - read-only
Transportation - read-only

Master Data - Generic Resources

Access to Insert and Edit but Not to Delete

Vtable

Main Access

VTEX/ CMS - LEGACY

Take a look on what's necessary to install the Widget on your e-commerce and integrate the catalog

The administrator has to create an external API key and generate a token for catalog integration as the following:

Navigate to account settings and create a new application key with a profile enabling API usage to generate the API key
Go to account management in the security section and generate a Secret Key (Token). Once you have the respective secret key token, assign it to the API key

Here's a support material if needed.

Some parameters related to the product are required for catalog integration setup

VTEX Endpoint (address of the VTEX environment - e.g., https://sualoja.vtexcommercestable.com.br/api)
Parameter to identify color
Information about the use of color in the SKU specification
Identifier of the unique color code
Parameter to identify size
Attribute to identify brand
Identifier of the unique product codes

Once the API key / token-related information and the parameters for the product catalog are gathered, these details should be shared with Doris's technical team for the integration to be completed.

Step 1 - Integrating APIs

Configuring the VTEX Integration APIs with Doris:

The e-commerce administrator has to share VTEX credentials information (API key / token) and product catalog configuration parameters with the Doris team
Additionally, request a schedule for the technical team to perform the integration configuration. This schedule should be requested through the Doris sales team

After configuring the integration APIs, you will receive confirmation of successful completion, along with authorization for product homologation.

Step 2 - Integrating catalog

Product catalog sync. After installing the app, it's necessary to perform an initial integration of the product catalog, as well as reviewing them to ensure that the experience with the Doris Widget goes smoothly.

After completing all the previous steps, Doris' Operations team proceeds with the integration process, performing the following tasks:

Definition of pre-models avatars
E-commerce categories mapping
Product importation
Try-on review (homologation)
Widget's Go Live definition

It’s necessary for the e-commerce administration to designate a responsible person to support potential adjustments in product information, such as details and images.

Step 3 - Installing and customizing Widget

The installation of the Doris Widget Software Development Kit (SDK) should be done manually following the instructions below:

3.1 - Inserting "Tag" responsible for locating Widget on page

Container
Add a div tag with the id doris-widget to your project in a location that does not interfere with a z-index overlap or has a relative position with a size smaller than the browser screen, as the Widget will be fixed in the bottom right corner.

1<div id="doris-widget"></div>

Note: The Widget will be generated inside the div described above.

Script
Add the Doris SDK to your website using the tag below.

1<script src="https://mix.doris.mobi/doris-widget.js">

Note: We recommend adding this tag at the end of your code just before closing the tag (see implementation example).

3.2 - Init() - Linking Doris with Your Store's Profile

The first step is to execute the "init" function. This function should be called on all pages of your e-commerce immediately after importing the Doris script. This function is responsible for providing Doris with the partner's token. In this function, there is 1 mandatory parameter and 1 optional.

Key	Value (type)	Description
apiKey (Required)	string	Partner's API key, previously provided by Doris.
theme (optional)	{ colors: { primary: string (hex) } }	Hexadecimal color to customize highlights and call-to-action (CTA) elements.
splashImage (optional)	string	URL of the image displayed in the SplashScreen. It needs to be in an HTTPS environment. If not provided, the Widget will use a default Doris image.
totemExperience (optional)	boolean	Activate camera flow for use in a kiosk. Default: false.
handleBuyButton (optional)	function	Function to add products to the e-commerce cart. The partner needs to configure their own function that will be used by the widget for cart integration. The function must return true or false for success or failure when adding the product to the cart. The first one is an array of SKUs and the second one is an object with one key inside (“skus”) and inside this key there is an array of objects with the “identifier” and “sellerId” keys whose values are the sku and the seller id, respectively. Both of the values are strings.
handleGoToCartButton (optional)	function	Function to redirect to the cart URL. The partner needs to configure their own function that will be used by the widget for cart integration.
position (optional)	object	An object containing the key "x" whose value can be "right" or "left". The default value is "left" if you omit this key.
language (optional)	string	Should be “en”, “pt” or “es”. If not provided the widget will use the language attribute from the html document. If the document language is not a supported language the widget will use the default language, which is english.

Click here to download the .psd file with the template for constructing the splash image.

Implementation example:

1<body>
2  ...
3  
4  <script src="https://mix.doris.mobi/doris-widget.js">
5  <script>
6    DorisWidget.init({
7      apiKey: 'cf854bbc-c239-11eb-8529-0242ac130003',
8      splashImage: 'https://doris-media-production.s3.sa-east-1.amazonaws.com/media/splash.png',
9      totemExperience: false,
10      language: 'pt',
11      position: {
12        x: 'right',
13      },
14      theme: {
15        colors: {
16          primary: '#00A2FF'
17        } 
18      },
19      handleBuyButton: function (sku, data) {
20        addToCart(sku, data)
21      }
22     handleGoToCartButton: function () {
23         getGoToCart()
24      }
25    })
26  </script>
27</body>

3.3 Verify() - Validating SKU within Doris

The verify function is responsible for checking if the product SKU exists within Doris and must be executed mandatory on all pages where the widget can be initiated by the user. This function will return a boolean (true or false). In this function, there are 2 mandatory parameters.

The verify function is a promise, meaning its return is asynchronous.

Key	Value (type)	Description
sku (optional)	string	SKU of the product to be verified. If not provided, the function will always return true.
apiKey (Required)	string	Partner's API key, provided previously by Doris.

Implementation example:

1<script> 
2DorisWidget.verify({
3	sku: 'mI1u293p2nJHn1',
4	apiKey: 'cf854bbc-c239-11eb-8529-0242ac130003',
5})
6</script>

3.4 Start() - Opening Widget

The start function is responsible for opening the widget. In this function, there is one optional parameter (SKUs).
If provided, the widget will be opened[1], and the specified SKUs, if any, will be tried on in the model. If the parameter is not provided, the widget is opened, and no garment is automatically tried on.

If there is more than one SKU of the same category in the list, the last SKU among them will be tried on.

Key	Value (type)	Description
skus (optional)	array	List of SKUs that will be worn on the model if they exist.
defaultGender (optional)	string	Valid values: "male" or "female". Specifies the gender in which the widget will be initially started for the user if no SKU is identified for dressing. In its absence, the default gender chosen by the partner will be used.

Implementation example:

1<script>
2  DorisWidget.start({
3    skus: ['mI1u293p2nJHn1'],
4    defaultGender: 'male'
5  })
6</script>

The widget will not be visible to the user until the start() function is executed; it is only after the execution of the start() function that the widget will be opened.

[1]: The Widget is not displayed on screens with landscape orientation and a height less than 480 pixels.

3.5 Order() - Tracking Widget performance

The order function is responsible for generating a tracking tag with the products that have been purchased. It should be executed by the partner after the payment confirmation of an order, passing a list of SKUs for all the products that were purchased by the user.

This item is important and mandatory for the approval of your installation. The data collected by this tracking will be used as specified in our contract, privacy policy, and terms of use.

Key	Value (type)	Description
products	array	An array of products.
products[]	object sku:string, quantity: number, total: float, identifier (opcional): number \| string	An object containing the SKU of the product, the quantity purchased, the total value of the item (unit price X quantity), and an identifier (optional) - if this value is already used in the SKU, this information is not necessary.
id	number \| string	Order number.
value	float	Total value of the order.
currency	string	Used currency (standard ISO 4217, default value: BRL - Brazilian Real).

Implementation example:

1DorisWidget.order({
2  "id": 1,
3  "value": 389.9,
4  "currency": "BRL"
5  "products": [
6    {
7      "sku": "mI1u293p2nJHn1",
8      "quantity": 2, 
9      "total": 389.9,
10  		"identifier": "mI1u293p2nJHn1-Branca"
11    }
12  ]
13})

3.6 InjectButton - Inserting Widget trigger button

The injectButton function is responsible for inserting a button that opens the widget. This method can be used if your implementation of the Start method is not done programmatically or linked to an already existing element.

To implement this function, add a div tag with the id "doris-trigger-wrapper" to your project in a location that does not interfere with a z-index overlap. The button's color will be defined in step 2.

Key	Value (type)	Description
skus (optional)	array	List of product SKUs to be verified by the Verify method. If not provided, the function will always return true. Should be used in conjunction with the key validateSku: true.
selector (required)	string	Selector pointing to the container (div, section, etc.) where the button will be injected. It's important to define width rules directly on this container, as the button will fill up the entire width.
validateSku (required)	boolean	Defines whether the button should appear only if the product informed in the skus key is available in Doris. If false, the button will render without validation. We recommend true when used on product detail pages and false for use on landing or banners.
apiKey (required)	string	Partner's API key. If not provided, the validateSku won't be performed.
backgroundImages (optional)	string	Array of URLs of images that will be displayed within the injected button. Doris provides these images. Note: If you want a customized image from your own catalog, please contact Doris Support to arrange this.
description (optional)	string	String to be displayed next to the button. If not provided, a default text will be shown.
showBadge (optional)	boolean	It defines whether the 'NEW' tag will be displayed in red at the top left corner of the button. Doris recommends enabling the 'NEW' tag to bring more visibility to the Doris Widget.

Implementation example:

1DorisWidget.injectButton({
2    selector: '#doris-trigger-wrapper',
3    skus: ['A-SKU-CODE'],
4    validateSku: true,
5    apiKey: 'MY-API-KEY',
6    backgroundImages: [
7      'https://doris-media-production.s3.sa-east-1.amazonaws.com/mix-static-assets/doris-trigger-default-images/F09.png',
8      'https://doris-media-production.s3.sa-east-1.amazonaws.com/mix-static-assets/doris-trigger-default-images/F13.png',
9      'https://doris-media-production.s3.sa-east-1.amazonaws.com/mix-static-assets/doris-trigger-default-images/M01.png',
10      'https://doris-media-production.s3.sa-east-1.amazonaws.com/mix-static-assets/doris-trigger-default-images/M02.png',
11    ],
12    description: 'This is a custom description',
13    showBadge: true,
14  })

On this page

Introduction VTEX IO VTEX CMS/Legacy

Hello, experience-commece