# Vtryon

Contributors: Vtryon
Tags: woocommerce, virtual try-on, fashion, ai, e-commerce
Requires at least: 5.8
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect WooCommerce with Vtryon for a seamless virtual try-on experience. Handles product mapping, image validation, and real-time status polling. This file is also rendered under **WooCommerce → Vtryon → Help guide** in wp-admin.

## 🚀 Key Features

- **API Token Authentication**: Uses your Vtryon API token server-side (x-api-key header on every API request).
- **Garment syncing**: **Sync** / **Sync with Vtryon** opens a picker with all product gallery images so you can choose which image to send to Vtryon, or upload a different file from your computer (product edit/add screen and Products list). **Sync All** only uses each product’s **featured image** and shows a confirmation before batch-syncing products that still need a Garment ID.
- **Download control**: Under settings, you can show or hide the **Download result** button after a try-on completes; the result image and “Try another photo” remain available when download is hidden.
- **Image Validation**: Mandatory multi-step flow ensures user-uploaded photos meet AI quality standards before processing.
- **Granular Control**:
  - **Storewide master switch**: Enable or disable virtual try-on for the entire site (when off, the button is hidden everywhere regardless of product or category).
  - Optional **logged-in-only** visibility (guests do not see try-on).
  - Enable/Disable try-on per product category.
  - Enable/Disable try-on per individual product.
- **Product page placement**: Choose where the try-on block appears on the single product page (for example before or after add to cart, below the summary, or at the bottom of the page). Shortcodes remain available for custom layouts.
- **Polished UI**: Modern, non-blocking notifications powered by SweetAlert2 (Swal).
- **Efficient Polling**: Smart recursive polling prevents unnecessary server load and background process pile-up.
- **Developer Friendly**: Extensive hooks and filters for frontend customization and behavior modification.

## ✨ Coming Soon

The following features are planned for upcoming releases of this plugin:

- **Ready-to-use Catalog SKU Image Generation**
- **Pose Generation for the Same SKU**
- **Expanded AI fashion workflow support inside WooCommerce**

For now, if you want to generate **catalog-ready SKU images** or **additional poses**, please use the **Vtryon website or app**.

## 🛠 Installation

1. Install from the Plugins screen.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Ensure WooCommerce is installed and active.

## ⚙️ Configuration

1. Navigate to **WooCommerce → Vtryon**.
2. If you do not have an account yet, sign up at **https://vtryon.legresca.ai/app** using **Create Account**.
3. Generate an **API token** in your Vtryon dashboard — see **https://vtryon.legresca.ai/guide/api-integration**.
4. Paste the token into **API token** on the Settings tab.
5. Under **Storewide try-on**, leave **Enable virtual try-on for the entire site** checked unless you want to hide try-on everywhere (product and category toggles only apply when this is on).
6. Under **Product page placement**, pick where the try-on block should appear on single product pages (default: after add to cart). Exact order can vary slightly by theme.
7. (Optional) Under **Visibility**, check **Show the try-on button only for logged-in users** to limit try-on to logged-in customers.
8. Under **Download result button**, leave **Show the “Download result” button after a try-on completes** checked unless you want to hide the download control on the storefront (customers can still see the result image).
9. Click **Save Changes**. The plugin will automatically test the connection and show a status alert.

## 👕 How to Sync Products

1. Go to your **Products** list in WordPress.
2. Locate the **Garment ID** column.
3. Click **Sync** for a product. A dialog loads the product’s gallery: select an image or use **upload from device**, then confirm. The returned Garment ID is saved. (Same flow from the product edit screen via **Sync with Vtryon**.)
4. To sync many products at once that still have no Garment ID, click **Sync All** in the toolbar. You’ll be asked to confirm that each product will sync using its **main (featured) image** only. Progress shows as **completed / total**. Products that already have a Garment ID are skipped. Very large catalogs may run in batches (see filter `vtryon_bulk_sync_max_products`, default 2000)—run **Sync All** again if needed.
5. On **Products → Categories**, edit a category: under **Garment sync**, use **Sync All** for products in that category only (same featured-image behavior and confirmation).
6. Add gallery images on the product and save before opening the picker if you need more than the featured image to choose from.

## 🖥 Frontend Flow

Once a product has a **Garment ID**, try-on is **enabled** at the site and product/category level, and the customer passes any **logged-in-only** rule, the Try-On UI appears on the product detail page at the **placement** you chose in settings (or wherever you put the `[vtryon]` shortcode).

1. **User Upload**: Customer clicks **Upload Photo** and selects their portrait.
2. **Validation**: The plugin sends the photo for quality validation.
3. **Processing**: Once validated, the Try-On task is created automatically.
4. **Result**: After polling is complete, the final generated image is displayed to the user.
5. **Download**: If enabled in **WooCommerce → Vtryon → Settings** (**Download result button**), users can download the generated result directly.

## 🪝 Developer Hooks

### Filters
- `vtryon_upload_person_payload`: Modify data sent during person image upload.
- `vtryon_create_task_payload`: Customize the final task creation JSON.
- `vtryon_max_upload_size`: Change the maximum file size (default 5MB).
- `vtryon_default_garment_type`: Change the garment type (default `stitched`).
- `vtryon_display_preset_definitions`: Add or change **Product page placement** presets (each preset: `hook`, `priority`, `label`).
- `vtryon_display_position`: Override the resolved WooCommerce **hook**, **priority**, and **preset** slug used to output the try-on block on single product pages.
- `vtryon_bulk_sync_max_products`: Maximum number of products loaded per **Sync All** run (default `2000`).

### Actions
- `vtryon_before_upload_person`: Fires before a person image is sent.
- `vtryon_after_create_task`: Fires after a task is successfully initiated.
- `vtryon_before_download`: Fires before a user downloads the result.
- `vtryon_after_download`: Fires after a user downloads the result.

## 📋 Requirements

- WooCommerce 5.0+
- PHP 7.4+
- A valid Vtryon account

**Service provider**

Vtryon

**Privacy Policy:** https://vtryon.legresca.ai/privacy-policy

## Changelog

- **1.0.2** — API token authentication (`x-api-key`); API base URL `https://api.vtryon.legresca.ai/api/v2`; garment sync image picker and **Sync All** featured-image confirmation; WordPress.org readme updates.
- **1.0.1** — Improved photo guidelines and consent modal UX.
- **1.0.0** — Initial release.

---

*Built for professional WooCommerce integrations.*