feat: Forward Braze recommended eCommerce events (opt-in)#66
Open
nickolas-dimitrakas wants to merge 7 commits into
Open
feat: Forward Braze recommended eCommerce events (opt-in)#66nickolas-dimitrakas wants to merge 7 commits into
nickolas-dimitrakas wants to merge 7 commits into
Conversation
Add an opt-in `useEcommerceRecommendedEvents` setting that forwards the six supported mParticle commerce actions using Braze's recommended eCommerce event schema (cart_updated, checkout_started, product_viewed, order_placed, and order_refunded via logCustomEvent). Requires Braze Web SDK 6.8.0+ (braze.logEcommerceEvent); support is detected at runtime, so older host SDKs and unsupported actions fall back to legacy forwarding. Bumps the @braze/web-sdk dependency to ^6.8.0. Attributes without a direct Braze field are nested in event/product metadata per Braze's strict schema; source is reported as "web". Includes Mocha tests for each mapped event and the fallback paths, and regenerates the dist bundles. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Three specs were failing on master-v6 independent of the eCommerce change:
- the suffix and forwarder-registration tests still asserted the v5 values
('v5' / 'Appboy-v5') after the kit moved to v6, and
- the reserved-attributes test hard-coded the expected birth year (2015),
which drifts every calendar year.
Update the version assertions to v6 and derive the expected birth year
dynamically (current year - age) so the suite is green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
buildRecommendedEventMetadata copied every commerce custom attribute into the event metadata object, including cart_id, checkout_id, and total_discounts, which are also promoted to typed recommended-event fields — so they appeared twice on the outbound event. Exclude the promoted keys from metadata; genuinely custom attributes are unaffected. Adds assertions covering the dedup and regenerates the dist bundles. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The dist/ bundle is a build artifact; CI regenerates it (npm run build) before tests, so it is not needed here. Per repo convention it is tracked in a separate "Generate latest bundle" PR. This restores dist/ to the master-v6 baseline so the feature PR contains only source, tests, and docs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
BrandonStalnaker
requested changes
Jul 13, 2026
- cart_id now falls back to the mParticle session id and then a generated id (matching the Android/iOS kits) instead of being omitted, and is always set on cart_updated/checkout_started/order_placed. - Product quantity is coerced to an integer >= 1 (mirrors Android's toLong().coerceAtLeast(1)) rather than a float. Adds tests for the cart_id fallback and integer-quantity behavior. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
BrandonStalnaker
approved these changes
Jul 13, 2026
rmi22186
reviewed
Jul 13, 2026
rmi22186
reviewed
Jul 13, 2026
- Extract all recommended event names into constants (matching the existing RECOMMENDED_ORDER_REFUNDED_EVENT_NAME) instead of inline string literals. - In the product_viewed branch, assign reportEvent from logEcommerceEvent directly (OR-accumulated across products) to match the style of the other branches. No behavioral change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…utes Braze Web SDK 6.9.0 added tax, shipping, and subtotal_value as recognized top-level attributes on cart_updated/checkout_started/order_placed. Bump @braze/web-sdk to ^6.9.0 and send them top-level instead of nesting tax/ shipping in metadata: - tax/shipping map from mParticle TransactionAttributes tax/shipping amounts. - subtotal_value has no native mParticle field, so it is sourced from a `subtotal_value` commerce custom attribute (like cart_id/total_discounts) and excluded from metadata to avoid duplication. Updates the minimum documented Braze Web SDK version to 6.9.0 and adds test coverage for the new top-level attributes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
rmi22186
reviewed
Jul 14, 2026
rmi22186
left a comment
rmi22186
left a comment
Collaborator
There was a problem hiding this comment.
makes sense that you pushed tax/shipping/subtotal_value was top level attributes for the respective ecommerce types, but now these are lost in metadata for the other ecommerce types you didn't add applyRecommendedMonetaryAttributes to, specifically refund and productviewed, which means the data is lost. Is that expected or should these remain in metadata?
rmi22186
reviewed
Jul 14, 2026
| 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 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. |
Collaborator
There was a problem hiding this comment.
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.
Collaborator
There was a problem hiding this comment.
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.
Author
There was a problem hiding this comment.
If we indeed plan to support this, we will bump to 6.9.0. Waiting for confirmation from PM
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Background
Braze Web SDK 6.8.0+ introduces recommended eCommerce events via
braze.logEcommerceEvent, which unlock calculated profile fields, eCommerce reporting, and out-of-the-box Canvas templates. This mirrors the iOS work in mparticle-apple-sdk#793 and the Androidbraze-42track.What changed
New opt-in
useEcommerceRecommendedEventsconnection setting. When enabled, the six supported mParticle commerce actions map to Braze's recommended events:ecommerce.cart_updated(action add/remove)ecommerce.checkout_startedecommerce.product_viewed(one per product)ecommerce.order_placedecommerce.order_refunded(custom event; no typed Braze API)Bumps
@braze/web-sdkto^6.8.0.Runtime capability guard:
braze.logEcommerceEventsupport is detected at call time (typeof braze.logEcommerceEvent === 'function'). When the setting is off (default), the host Braze SDK is older than 6.8.0, or the action is unsupported / has no products, the kit falls back to the existing legacy forwarding — no breaking change.Attributes without a direct Braze field (
cart_id,checkout_id,source,tax,shipping, productbrand/category/coupon_code/position, etc.) are nested in event/productmetadataper Braze's strict schema.sourceis"web".cart_id/checkout_idfall back to the mParticle session id.Regenerated
dist/bundles.Testing
npm test(Karma/Mocha) — all 9 new recommended-eCommerce tests pass (each mapped event + toggle-off, unsupported-action, and older-SDK fallbacks). The only failing specs are pre-existing onmaster-v6(stalev5suffix assertions and a date-based age test), unrelated to this change.🤖 Generated with Claude Code