Bắt đầu nhanh: website bất kỳ

Widget Macgi là một thẻ script, khoảng 15 KB, không phụ thuộc thư viện nào và chạy trong Shadow DOM nên không ảnh hưởng tới giao diện của bạn. Trang này dành cho mọi website bạn chèn được mã HTML. Nếu bạn dùng Haravan, Sapo, WooCommerce hay Shopify, hãy xem hướng dẫn riêng cho nền tảng.

Lấy khoá (key)

Mỗi shop có một khoá công khai dạng pk_live_.... Khoá được cấp khi bạn đăng ký beta (miễn phí 1.000 lượt thử, không cần thẻ thanh toán) và gửi qua email trong 1–2 ngày làm việc.

Khoá chỉ hoạt động trên các tên miền của shop. Khi đăng ký, hãy ghi đủ mọi tên miền khách có thể vào: có và không có www, tên miền phụ của nền tảng (ví dụ ten-shop.myharavan.com) và trang thử nghiệm nếu có. Khoá công khai được phép nằm trong mã trang; đừng chia sẻ khoá bí mật nếu sau này bạn được cấp.

Cách 1: chế độ tự động (khuyên dùng)

Dán thẻ sau ngay trước thẻ </body> trong giao diện, trên mọi trang:

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

Có thuộc tính data-auto, widget tự nhận ra trang sản phẩm và chèn nút “Thử đồ” cạnh nút thêm vào giỏ. Một trang được coi là trang sản phẩm khi có ít nhất một trong các dấu hiệu sau:

• dữ liệu có cấu trúc Product (JSON-LD), thứ hầu hết nền tảng bán hàng đã có sẵn;
• thẻ og:image chứa ảnh sản phẩm;
• biểu mẫu thêm vào giỏ hàng.

Ảnh sản phẩm lấy từ dữ liệu trên trang. Mặc định mọi sản phẩm được thử như áo (top). Để quần, chân váy và váy liền được thử đúng chỗ, thêm quy tắc theo từ khoá trong tên sản phẩm:

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

Với sản phẩm không theo quy tắc chung, đặt thẻ meta riêng trên trang sản phẩm đó. Thẻ này ghi đè quy tắc từ khoá và ảnh tự nhận:

<meta name="macgi:slot" content="bottom">
<meta name="macgi:garment-image" content="https://shop-cua-ban.vn/anh/quan-jean-xanh.jpg">

Các hướng dẫn Haravan và Sapo chỉ cách sinh thẻ này tự động từ tag sản phẩm.

Cách 2: tự đặt nút

Nếu muốn quyết định chính xác vị trí, chữ và kiểu nút, bỏ data-auto khỏi thẻ script và đặt một phần tử có data-macgi-tryon trên trang sản phẩm. Nút có thể là bất kỳ phần tử nào và có thể thêm sau khi trang đã tải (ứng dụng một trang vẫn chạy). Dùng lớp CSS sẵn có của giao diện để nút trông giống các nút khác.

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

<button type="button" data-macgi-tryon
        data-garment-image="https://shop-cua-ban.vn/anh/ao-thun-den.jpg"
        data-garment-slot="top"
        data-garment-description="áo thun cotton màu đen, cổ tròn">
  Thử đồ
</button>

Mô tả (data-garment-description) được dùng khi tạo ảnh nên phải khớp với ảnh, nhất là màu sắc. Tên sản phẩm thường là đủ. Để khách thử cả bộ (tối đa 2 món: một áo và một quần hoặc chân váy), dùng data-garments:

<button type="button" data-macgi-tryon
        data-garments='[
          {"slot":"top","description":"áo sơ mi trắng","imageUrl":"https://shop-cua-ban.vn/anh/so-mi-trang.jpg"},
          {"slot":"bottom","description":"quần âu màu be","imageUrl":"https://shop-cua-ban.vn/anh/quan-au-be.jpg"}
        ]'>
  Thử cả bộ
</button>

Bảng tuỳ chọn

Thuộc tính của thẻ script

Thuộc tính của nút

Thẻ meta theo trang (chế độ tự động)

Sự kiện và JavaScript API

Script tạo đối tượng window.Macgi. Bạn không cần gọi init khi thẻ script đã có data-key.

// Mở widget từ mã của bạn (ví dụ từ nút riêng hoặc ứng dụng một trang)
Macgi.open([
  { slot: 'top', description: 'áo thun đen', imageUrl: 'https://shop-cua-ban.vn/anh/ao-thun-den.jpg' },
]);

Macgi.close();        // đóng widget
Macgi.setLang('en');  // đổi ngôn ngữ: 'vi' hoặc 'en'
Macgi.forgetPhoto();  // xoá ảnh của khách đang giữ trong bộ nhớ

Widget phát các sự kiện trên window, để bạn gửi vào công cụ phân tích hoặc gắn hành động như mở giỏ hàng:

window.addEventListener('macgi:result', (e) => {
  // e.detail = { id, resultUrl, processingMs }
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ event: 'macgi_tryon_result' });
});

window.addEventListener('macgi:error', (e) => {
  console.warn('Macgi:', e.detail.message);
});

Sự kiện không chứa ảnh hay thông tin cá nhân của khách. Đường dẫn kết quả hết hạn sau 24 giờ, đừng lưu nó lâu dài.

Quyền riêng tư

• Trước khi tải ảnh, khách thấy câu xin đồng ý (đổi được bằng data-consent).
• Ảnh được thu nhỏ và xoá toàn bộ thông tin kèm theo (vị trí GPS, máy chụp, thời gian) ngay trên máy khách trước khi gửi.
• Không có thông tin nào về khách được ghi vào cơ sở dữ liệu. Ảnh tạm bị xoá khi lượt thử xong; ảnh kết quả tự xoá sau 24 giờ.
• Ảnh chỉ nằm trong bộ nhớ của trang để khách thử thêm món khác, không lưu vào trình duyệt. Macgi.forgetPhoto() xoá ngay.
• Ảnh của khách và ảnh sản phẩm của bạn không được dùng để huấn luyện AI hay làm quảng cáo.

Bạn nên thêm một câu vào chính sách quyền riêng tư của shop, cho biết tính năng thử đồ do Macgi cung cấp và dẫn tới chính sách của chúng tôi.

Xử lý sự cố

Nút không xuất hiện

• Trang không được nhận là trang sản phẩm. Chế độ tự động cần dữ liệu Product, thẻ og:image hoặc biểu mẫu thêm vào giỏ. Hãy tự đặt nút (cách 2) trên trang đó.
• Không tìm thấy ảnh sản phẩm. Thêm <meta name="macgi:garment-image">, hoặc tự đặt nút với data-garment-image.
• Tên miền chưa được phép dùng khoá. Khoá chỉ chạy trên tên miền đã đăng ký; tên miền mới, bản có www hay tên miền phụ của nền tảng đều phải thêm riêng. Gửi tên miền cho chúng tôi qua Zalo hoặc email để được thêm.
• Script chưa được tải. Mở trang sản phẩm, nhấn F12, chọn Console và gõ window.Macgi. Nếu kết quả là undefined, giao diện chưa được lưu, bạn đang sửa một giao diện chưa xuất bản, hoặc trang còn bộ nhớ đệm cũ.

Nút ở vị trí chưa đẹp

Thêm data-placement với bộ chọn CSS của khối bạn muốn nút nằm cạnh, hoặc tự đặt nút.

Quần hoặc váy bị thử như áo

Thêm từ khoá vào data-slot-rules, đặt <meta name="macgi:slot"> cho sản phẩm đó, hoặc đặt data-garment-slot trên nút.

Kết quả sai màu hoặc sai kiểu

Kiểm tra mô tả có khớp với ảnh không, và dùng ảnh chụp chính diện, thấy toàn bộ món đồ, nền trơn. Ảnh người mẫu tạo dáng nghiêng hoặc ảnh ghép nhiều màu cho kết quả kém hơn.