feat: Forward Braze recommended eCommerce events (opt-in)

README.md

@@ -22,6 +22,27 @@ If you use Push Notifications, your `service-worker.js` file should be updated t
 self.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker-6.5.0.js')
 ```
 
+# Recommended eCommerce Events (opt-in)
+
+Braze Web SDK **6.8.0+** introduces [recommended eCommerce events](https://www.braze.com/docs/developer_guide/analytics/logging_ecommerce_events/#web). When the **`useEcommerceRecommendedEvents`** setting is enabled on the Braze connection, this kit forwards supported mParticle commerce events using that schema. When the setting is off (the default), commerce forwarding is unchanged and fully backward compatible.
+
+Requirements:
+
+* **Minimum Braze Web SDK version: 6.8.0** (`braze.logEcommerceEvent`). The kit detects support at runtime; if the loaded Braze SDK is older than 6.8.0, commerce events automatically fall back to legacy forwarding.
+* **Minimum mParticle Braze kit version:** the first release that includes this feature (`@mparticle/web-braze-kit`).
+
+When enabled, mParticle commerce actions map to Braze recommended events:
+
+| mParticle commerce action | Braze recommended event |
+| :--- | :--- |
+| `add_to_cart` | `ecommerce.cart_updated` (action `add`) |
+| `remove_from_cart` | `ecommerce.cart_updated` (action `remove`) |
+| `checkout` | `ecommerce.checkout_started` |
+| `view_detail` | `ecommerce.product_viewed` (one per product) |
+| `purchase` | `ecommerce.order_placed` |
+| `refund` | `ecommerce.order_refunded` (custom event; no typed Braze API) |
+
+Attributes without a direct Braze equivalent (`cart_id`, `checkout_id`, `source`, product `brand`/`category`/`coupon_code`/`position`, `tax`, `shipping`, etc.) are placed inside the event- or product-level `metadata` object, per Braze's strict recommended-event schema. `source` is reported as `"web"`. Any commerce action not listed above continues to use legacy forwarding.
 
 # License