Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nickolas-dimitrakas wants to merge 7 commits into
base: master-v6
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9f60db5
feat: forward Braze recommended eCommerce events (opt-in)
nickolas-dimitrakas Jul 6, 2026
d2d3f4e
test: fix pre-existing stale version and age assertions
nickolas-dimitrakas Jul 6, 2026
ed81622
fix: avoid duplicating promoted keys in eCommerce metadata
nickolas-dimitrakas Jul 6, 2026
4845137
chore: drop generated dist bundle from feature PR
nickolas-dimitrakas Jul 8, 2026
2f6a58b
fix: address review — integer quantity and consistent cart_id fallback
nickolas-dimitrakas Jul 13, 2026
b841863
refactor: address review nits in recommended eCommerce forwarding
nickolas-dimitrakas Jul 14, 2026
2a4ec57
feat: forward tax, shipping, and subtotal_value as recommended attrib…
nickolas-dimitrakas Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.9.0+** introduces [recommended eCommerce events](https://www.braze.com/docs/developer_guide/analytics/logging_ecommerce_events/#web) with the full attribute set (including top-level `tax`, `shipping`, and `subtotal_value`). 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.9.0** (`braze.logEcommerceEvent` with the `tax`/`shipping`/`subtotal_value` attributes). The kit detects support at runtime; if the loaded Braze SDK is older than 6.9.0, commerce events automatically fall back to legacy forwarding.

@rmi22186 rmi22186 Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The kit doesn't actually detect support at runtime. In this case, it is always going to be bundled with 6.9.0, and so there isn't a risk of having an older 6.x version.

@rmi22186 rmi22186 Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose if someone is using v5 or earlier though then it will continue to be true. So I think this phrasing is overall fine.

@nickolas-dimitrakas nickolas-dimitrakas Jul 14, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we indeed plan to support this, we will bump to 6.9.0. Waiting for confirmation from PM

* **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) |

`tax` and `shipping` map to the recognized top-level attributes from mParticle's `TransactionAttributes.tax`/`shipping`. `total_discounts` and `subtotal_value` have no native mParticle field and are sourced from the `total_discounts` / `subtotal_value` commerce custom attributes (`tax`/`shipping`/`subtotal_value` apply to cart_updated/checkout_started/order_placed; `total_discounts` to order_placed/refund). Any remaining attribute without a direct Braze equivalent (`cart_id`, `checkout_id`, `source`, product `brand`/`category`/`coupon_code`/`position`, etc.) is 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

Expand Down
8 changes: 4 additions & 4 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
"watchify": "^3.11.1"
},
"dependencies": {
"@braze/web-sdk": "^6.0.0",
"@braze/web-sdk": "^6.9.0",
"@mparticle/web-sdk": "^2.23.0"
},
"license": "Apache-2.0"
Expand Down
Loading
Loading