Requirements

An API Key
Products imported and approved by the Doris team
A div with id #doris-trigger-wrapper in yout product page, where the Doris button will be injected

Installation and initialization

To include the Doris Widget SDK directly in your HTML, use the following method:

1<script defer>
2  (function () {
3    const API_KEY = "<YOUR API KEY>";
4  
5    function handleBuyButton(skus) {
6      yourPlatformAddToCartFunction(...skus);
7    }
8  
9    function injectDorisButton() {
10      // initializes the Doris SDK
11      window.DorisWidget.init({
12        apiKey: API_KEY,
13        theme: { colors: { primary: "#000000" } },
14        position: { x: "left" },
15        splashImage: "https://example.com/your-splash-image.jpg",
16        language: "en",
17        handleBuyButton,
18      });
19  
20      // it is necessary that the element where the button will be injected exists
21      // like this: <div id="doris-trigger-wrapper"></div>
22      if (!document.querySelector("#doris-trigger-wrapper")) return;
23  
24      window.DorisWidget.injectButton({
25        apiKey: API_KEY,
26        selector: "#doris-trigger-wrapper",
27        skus: ["<PRODUCT IDENTIFIER>"],
28        validateSku: true,
29      });
30    }
31  
32    function handleScriptLoaded() {
33      injectDorisButton();
34    }
35  
36    function injectDorisSDK() {
37      const script = document.createElement("script");
38      script.type = "text/javascript";
39      script.async = true;
40      script.onload = handleScriptLoaded;
41      script.src = "https://mix.doris.mobi/doris-widget.js";
42      document.head.appendChild(script);
43  
44      const dorisWidget = document.createElement("div");
45      dorisWidget.id = "doris-widget";
46      document.body.appendChild(dorisWidget);
47    }
48  
49    injectDorisSDK();
50  })();
51</script>

SDK API Methods

Before executing any of the following methods, ensure that the widget's SDK has been fully downloaded. In the example above, we added a callback that triggers the init method during the onload event of the SDK script configuration.

DorisWidget.init(options)

Parameters:

options (Object): A configuration object with the following properties:
- apiKey (String, required): The API key provided.
- theme (Object, optional): A theme configuration object. Currently, you can configure only the primary color with the following properties:
  - { color: primary: '#000000' }
- position (Object, optional): An object for configuring the horizontal position of the widget on the page:
  - { x: ‘left' }the x property could be left or right,default value is right.
- splashImage (String, optional): URL of the image displayed in the SplashScreen. It must be served over HTTPS. If not provided, the Widget will use a default Doris image. Click here to download the .psd file template for constructing the splash image.
- language (String, optional): Should be one of en, pt, or es. If not provided, the Widget will use the language attribute from the HTML document. If the document language is not supported, the default language will be English.

DorisWidget.injectButton(options)

The injectButton function is responsible for inserting a button that opens the widget.

It requires the init method to be executed first.

Parameters:

options (Object):A configuration object with the following properties:
- apiKey (String, required): The API key provided.
- selector (String, required): A selector pointing to the container (div, section, etc.) where the button will be injected.
- skus (Array of Strings, optional): A list of product SKUs. If the values are valid, the Widget will perform a try-on with the products when opened.
- validateSku (Boolean, optional): Determines whether the button should appear only if the products specified in the skus key are available in Doris. If set to false, the button will render without validation. We recommend setting this to true for product detail pages and falsefor landing pages or banners.
- backgroundImages (String, optional): An array of URLs of images to be displayed within the injected button. These images are provided by Doris, but if you wish to use a customized image from your catalog, please contact Doris Support.
- description (String, optional): A string to be displayed next to the button. If not provided, default text will be shown.
- showBadge (Boolean, optional): Determines whether a 'NEW' tag will be displayed in red at the top left corner of the button. Doris recommends enabling the 'NEW' tag for increased visibility of the widget.
- useNewTrigger(Boolean, optional): Determines the layout of the button. Enable this option If you want to use DORIS layout,. If you prefer to use your own layout, do not enable this option. Customization is not allowed in DORIS layout.

Implementation example:

1// this needs a element with 'doris-trigger-wrapper' id in the page.
2// like this: <div id="doris-trigger-wrapper"></div>
3
4window.DorisWidget.injectButton({
5    apiKey: 'YOUR API KEY',
6    selector: '#doris-trigger-wrapper',
7    skus: ['101010'],
8    validateSku: true,
9    backgroundImages: [
10      'https://doris-media-production.s3.sa-east-1.amazonaws.com/mix-static-assets/doris-trigger-default-images/F09.png',
11      'https://doris-media-production.s3.sa-east-1.amazonaws.com/mix-static-assets/doris-trigger-default-images/F13.png',
12      'https://doris-media-production.s3.sa-east-1.amazonaws.com/mix-static-assets/doris-trigger-default-images/M01.png',
13      'https://doris-media-production.s3.sa-east-1.amazonaws.com/mix-static-assets/doris-trigger-default-images/M02.png',
14    ],
15    description: 'This is a custom description',
16    showBadge: true,
17})
18

In the above implementation, the button will be injected into the element specified in the selector property. You need to create this element wherever you want the Doris button to appear on your page. We recommend placing this element between the selection of product options (color and size) and the buy button on the product page.

DorisWidget.order(options)

The order method is responsible for generating a tracking tag for the products that have been purchased. It should be executed by the partner after payment confirmation for an order, passing a list of SKUs for all the products purchased by the user.This step is crucial and mandatory for the approval of your installation. The data collected through this tracking will be used as outlined in our contract, privacy policy, and terms of use.

It requires the init method to be executed first.

Parameters:

options (Object): A configuration object with the following properties:
- id(Number, required): The order number
- products (Array of Objects, required): An array of product objects, each containing:
  - sku (String, required): The product SKU
  - identifier (String, optional): The product identifier
  - quantity (Number, required): The quantity of ordered products
  - total (Number, required): The total value of the items (unit price * quantity)
- value (Number, required): The total value of the order
- currency(String, required): The currency used (in standard ISO 4217 format). The default value is BRL (Brazilian Real).

Implementation example:

1window.DorisWidget.order({
2  id: 1243,
3  value: 389.9,
4  currency: "BRL",
5  products: [
6    {
7      sku: "101011",
8      quantity: 2,
9      total: 779.8,
10      identifier: "101010",
11    },
12  ],
13});
14