xactsize-webcomponents 1.0.43 → 1.0.45

package/README.md

@@ -107,3 +107,75 @@ To enable this feature, provide the following properties to the `<body-measurer>
   skus='[{"dimensions":{"Size":"M"},"measures":{"height":50,"length":70,"width":40}}]'
 ></body-measurer>
 ```
+
+## Usage and Implementation Guide
+
+The `<body-measurer>` component is highly customizable and accepts various attributes to control its behavior, appearance, and integration with the Xactsize backend.
+
+### Properties (Attributes)
+
+Here is a list of all supported attributes that can be passed to the `<body-measurer>` element:
+
+| Attribute     | Type    | Default     | Description                                                                     |
+| ------------- | ------- | ----------- | ------------------------------------------------------------------------------- |
+| `api-key`     | string  | `""`        | Your Xactsize API key for backend authentication.                               |
+| `tenant-id`   | string  | `"1"`       | Your tenant identifier.                                                         |
+| `product-sku` | string  | `"123456"`  | The unique SKU of the product being sized. This is required for API resolution. |
+| `base-url`    | string  | _default_   | The base URL for the Xactsize service API.                                      |
+| `api-url`     | string  | _default_   | The endpoint for the main sizing API.                                           |
+| `vton`        | boolean | `false`     | Enables the Virtual Try-On (VTON) feature.                                      |
+| `vton-url`    | string  | _default_   | The API endpoint for generating VTON images.                                    |
+| `garment-url` | string  | `""`        | The URL of the garment image used for Virtual Try-On.                           |
+| `brand-name`  | string  | `undefined` | Displays your brand's name in the component (e.g., "Xactsize x YourBrand").     |
+| `button-text` | string  | `""`        | Custom text for the "Find My Size" launch button.                               |
+| `culture`     | string  | `"en"`      | The active locale for the UI. Supported options: `"en"`, `"pt-BR"`, `"es-MX"`.  |
+
+> **Note:** While older integration examples might show `skus` or `product-name` attributes, modern implementations rely on the `product-sku` attribute which the backend uses to resolve product sizing rules.
+
+### Events
+
+The component emits standard DOM custom events that you can listen to in your application logic:
+
+- **`measurementAccepted`**: Fired when the user accepts the recommended size.
+  - `event.detail` contains the sizing result payload (e.g., `{ size: "M" }`).
+- **`measurementCanceled`**: Fired when the user closes the modal or explicitly aborts the process.
+
+### Localization (i18n)
+
+The component fully supports internationalization. To change the language, simply update the `culture` attribute on the element.
+Available cultures:
+
+- `en` (English)
+- `pt-BR` (Portuguese - Brazil)
+- `es-MX` (Spanish - Mexico)
+
+The localization engine will automatically apply the translated strings to all steps in the flow.
+
+### Example Implementation
+
+```html
+<body-measurer
+  api-key="YOUR_API_KEY_HERE"
+  tenant-id="123"
+  product-sku="SHIRT-001"
+  brand-name="My Store"
+  culture="es-MX"
+  button-text="Encontrar mi talla"
+  vton
+  garment-url="https://example.com/shirt-image.jpg"
+>
+</body-measurer>
+
+<script>
+  const measurer = document.querySelector("body-measurer");
+
+  measurer.addEventListener("measurementAccepted", (e) => {
+    console.log("User accepted size:", e.detail.size);
+    // Logic to add the selected size to the shopping cart
+  });
+
+  measurer.addEventListener("measurementCanceled", () => {
+    console.log("User closed the measurer");
+  });
+</script>
+```