Add virtual try-on to a Sapo Web store

There is no Macgi app for Sapo Web yet, but the widget works well as a script tag in your theme. Sapo themes use .bwt files with Liquid syntax. You edit one file; placing your own button and tagging products are optional. Menu names are given as they appear in Sapo’s Vietnamese admin.

Before you start

• Your pk_live_... key from the beta email. No key yet? Join the beta.
• A Sapo account that can edit the website theme.
• When you sign up, list every domain of your store (with and without www, and the Sapo-provided one) so the key works on all of them.
• Back up the theme (or work on an unpublished copy) before editing code.

Step 1: add the script to theme.bwt

1. In the Sapo admin, go to Website → Giao diện (Themes).
2. On your live theme, click Thao tác → Chỉnh sửa HTML/CSS (Actions → Edit HTML/CSS).
3. In the Layouts folder, open theme.bwt.

4. Find the </body> tag (usually at the end, below the {% block "ContentPlaceHolder" %} line) and paste this just above it:

   layouts/theme.bwtCopy

   <script src="https://cdn.macgi.app/widget.js"
           data-key="pk_live_..."
           data-auto
           data-slot-rules='{"quần":"bottom","chân váy":"bottom","váy liền":"one_piece","đầm":"one_piece"}'
           defer></script>
   </body>

   The data-slot-rules line makes trousers (“quần”), skirts (“chân váy”) and dresses (“váy liền”, “đầm”) try on correctly based on words in the product name. Adjust the keywords, or remove the line if you only sell tops.

5. Click Lưu (Save).

Step 2: check a product page

Open a product page (reload it if it is already open). The “Thử đồ” (Try it on) button appears next to the add-to-cart button. Try it once with a full-body photo. If the button does not show, open the Console (F12), type window.Macgi and see troubleshooting.

Tag bottoms and dresses

When a product name has no clear keyword, tag the product on its edit page:

• macgi-bottom for trousers and skirts;
• macgi-one-piece for dresses and jumpsuits.

Then, in Chỉnh sửa HTML/CSS, open product.bwt (the product page template) and paste this at the top. The macgi:slot tag takes priority over the keyword rules:

{% if product.tags contains 'macgi-bottom' %}
  <meta name="macgi:slot" content="bottom">
{% elsif product.tags contains 'macgi-one-piece' %}
  <meta name="macgi:slot" content="one_piece">
{% endif %}

Optional: place your own button in the template

1. In theme.bwt, remove data-auto (and data-slot-rules) so the page does not show two buttons:

   layouts/theme.bwtCopy

   <script src="https://cdn.macgi.app/widget.js" data-key="pk_live_..." defer></script>
   </body>

2. Open product.bwt and find the add-to-cart form (search for /cart/add). If your theme moves it into the Snippets folder, search the files there.

3. Paste the button right after the add-to-cart button:

   product.bwtCopy

   <button type="button" class="btn" data-macgi-tryon
           data-garment-image="{{ product.featured_image | img_url: '1024x1024' }}"
           data-garment-slot="{% if product.tags contains 'macgi-bottom' %}bottom{% elsif product.tags contains 'macgi-one-piece' %}one_piece{% else %}top{% endif %}"
           data-garment-description="{{ product.name | escape }}">
     Thử đồ
   </button>

   Sapo uses product.name for the product name (not product.title). The img_url filter takes sizes such as 'grande' (600 px), '1024x1024' or 'master' and returns a URL like //bizweb.dktcdn.net/...; the widget understands it, so there is no need to add https:. Change class="btn" to your theme’s button class.

4. Click Lưu (Save) and check a product page again.

Notes and troubleshooting

• No button on one of your domains: that domain is not allowed for your key yet. Message us and we add it.
• Switching themes: paste the script into the new theme before you publish it.
• Which photo is used: the featured image should be a front-facing shot of the whole item. If not, use the macgi:garment-image tag (see options).
• More common issues are in the Quick start.