feat(braze-web): Upgrade SDK to v6.5.0 with opt-in support

[AnkitSegment]

Summary

Upgrades Braze Web SDK from v6.1 to v6.5.0, made available as an opt-in version selection for customers.

This is a browser-mode destination where customers explicitly select SDK versions from a dropdown. Version 6.5 is now available as a new option while maintaining 6.1 as the safe default for new installations.

JIRA: https://twilio-engineering.atlassian.net/browse/STRATCONN-6776

Changes

Version Management

• Created versioning-info.ts with centralized version constants
• BRAZE_SDK_DEFAULT_VERSION = '6.1' (stable default)
• BRAZE_SDK_CANARY_VERSION = '6.5' (newly available option)
• Added version 6.5 to SDK version choices in settings dropdown
• Default remains at 6.1 for safe rollout
• Constants are named to clearly indicate they refer to the Braze SDK version (not an API contract version)

Testing

• All existing tests pass (25 tests, 6 suites)
• Added test for stable default version
• Added test for explicit canary selection
• Added test verifying canary version is in settings choices
• Test names derive from constants (no hardcoded version strings that could drift)

Breaking Changes

NONE - This is a fully backward-compatible upgrade.

Version-by-Version Changes

v6.2.0 (ENHANCEMENTS)

• Updated platform detection for "Coolita" and "WhaleTV" Smart TV platforms
• Impact: LOW - Better device categorization, no API changes

v6.3.0 (ENHANCEMENTS + BUGFIXES)

• Exposed NotificationSubscriptionTypes in brazeBridge (new optional API)
• Added ChatGPT Atlas browser detection support
• Improved crawler bot detection mechanisms
• Bugfix: Resolved banner impression tracking issue with local storage

v6.3.1 (BUGFIX)

• Bugfix: Fixed impression tracking for banners persisting across sessions

v6.4.0 (ENHANCEMENTS + BUGFIXES)

• Added braze.logBannerImpressions() and braze.logBannerClick() methods (optional)
• Bugfix: Fixed in-app message display issue after user changes (improves user isolation)

v6.5.0 (ENHANCEMENTS)

• Added cookieExpiryInDays initialization option (default: 400 days, backward-compatible)
• Introduced Banner.html property for manual HTML injection (optional)
• Improved request retry timing to use server-configurable values (internal optimization)

Testing Plan

Manual Testing Required

• Verify 6.5 appears in SDK version dropdown in Segment UI
• Test with default version (should use 6.1)
• Test with explicit 6.5 selection
• Verify SDK loads correctly from CDN
• Verify all core functionality works (events, purchases, user attributes)
• Test in-app messaging
• Check console for errors

Settings loading with 6.5:

Braze 6.5 is loading:

track event is successful:

Automated Testing

• Unit tests passing (25 tests, 6 suites)
• Version loading tests (default stable, explicit canary)
• Settings validation test
• All existing functionality tests pass

Rollout Plan

Since this is a browser-mode destination with explicit version selection:

1. Phase 1: Merge PR - version 6.5 becomes available in dropdown
2. Phase 2: Internal testing - Segment team tests with 6.5 selected
3. Phase 3: Customer opt-in - Customers can choose 6.5 from settings
4. Phase 4: Monitor adoption - Watch for issues from early adopters
5. Phase 5: (Future) Update default to 6.5 in a follow-up PR once adoption is validated

Risk Assessment

Risk Level: LOW

Rationale:

1. No Breaking Changes: All v6.5 changes are backward-compatible enhancements
2. Opt-In Model: Customers must explicitly select 6.5; existing configs stay on their chosen version
3. Safe Default: New installations still get 6.1 by default
4. No Server Changes: Browser-mode destination loads SDK from Braze's CDN
5. Instant Rollback: Customers can switch back to 6.1 in settings immediately
6. Comprehensive Tests: All 25 tests pass including new version-specific tests
7. Bug Fixes Included: v6.5 includes important bug fixes for banner tracking and user isolation

Files Changed

1. versioning-info.ts - Centralized SDK version constants (BRAZE_SDK_DEFAULT_VERSION, BRAZE_SDK_CANARY_VERSION)
2. index.ts - Import version constants, add 6.5 to choices dropdown
3. tests/initialization.test.ts - Version tests using constants (no hardcoded version strings)

Additional Notes

• Braze Web SDK v6.5.0 is available at: https://js.appboycdn.com/web-sdk/6.5/braze.no-module.min.js
• Changelog: https://github.com/braze-inc/braze-web-sdk/blob/master/CHANGELOG.md
• This upgrade maintains compatibility with both SDK v3.x (appboy) and SDK v4+ (braze) patterns
• No changes to authentication, request building, or action perform logic
• The new cookieExpiryInDays parameter could be exposed to customers in a future release if there's demand

---

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds opt-in support for Braze Web SDK v6.5 (while keeping v6.1 as the default) in the Braze browser-mode destination, so customers can select the newer SDK version from settings without changing existing installs.

Changes:

• Introduces versioning-info.ts to centralize stable/canary SDK version constants.
• Updates destination settings to keep default at 6.1 and adds 6.5 to the sdkVersion dropdown choices.
• Extends initialization tests to cover default version behavior, explicit canary selection, and settings choices.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
packages/browser-destinations/destinations/braze/src/versioning-info.ts	Adds stable/canary SDK version constants.
packages/browser-destinations/destinations/braze/src/index.ts	Uses stable constant for default and adds 6.5 as a selectable SDK version.
packages/browser-destinations/destinations/braze/src/tests/initialization.test.ts	Adds tests asserting default version loading, canary loading, and presence of 6.5 in choices.
packages/browser-destinations/destinations/braze/breaking-changes-analysis.md	Adds analysis document for the 6.1 → 6.5.0 SDK change.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 31.86%. Comparing base (139ddfe) to head (1a3ad04).
⚠️ Report is 2 commits behind head on main.

❌ Your project check has failed because the head coverage (31.86%) is below the target coverage (70.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #3770       +/-   ##
===========================================
- Coverage   80.84%   31.86%   -48.99%     
===========================================
  Files        1377       15     -1362     
  Lines       26417      747    -25670     
  Branches     5581      125     -5456     
===========================================
- Hits        21357      238    -21119     
+ Misses       4097      509     -3588     
+ Partials      963        0      -963     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

[itsarijitray]

Breaking Changes Analysis: Braze Web SDK v6.1 → v6.5.0

Summary

The upgrade from Braze Web SDK v6.1 to v6.5.0 introduces NO BREAKING CHANGES. All updates are backward-compatible enhancements focusing on platform detection improvements, banner functionality extensions, and initialization flexibility.

Version-by-Version Changes

v6.2.0

Type: ENHANCEMENT

• Change: Updated platform detection for "Coolita" and "WhaleTV" Smart TV platforms
• Impact: LOW - Improved device categorization, no API changes
• Required Action: None
• Risk Level: LOW

v6.3.0

Type: ENHANCEMENT

• Change: Exposed NotificationSubscriptionTypes in brazeBridge
• Impact: LOW - New API surface, existing functionality unchanged
• Required Action: None (optional feature)
• Risk Level: LOW

Type: ENHANCEMENT

• Change: Added ChatGPT Atlas browser detection support
• Impact: LOW - Improved bot detection
• Required Action: None
• Risk Level: LOW

Type: ENHANCEMENT

• Change: Improved crawler bot detection mechanisms
• Impact: LOW - Better filtering of non-human traffic
• Required Action: None
• Risk Level: LOW

Type: BUGFIX

• Change: Resolved banner impression tracking issue with local storage
• Impact: LOW - Fixes existing bug, no API changes
• Required Action: None
• Risk Level: LOW

v6.3.1

Type: BUGFIX

• Change: Fixed impression tracking for banners persisting across sessions
• Impact: LOW - Bug fix, no API changes
• Required Action: None
• Risk Level: LOW

v6.4.0

Type: ENHANCEMENT

• Change: Added braze.logBannerImpressions() and braze.logBannerClick() methods
• Impact: LOW - New optional methods for manual banner event logging
• Required Action: None (optional feature, not used in current integration)
• Risk Level: LOW

Type: BUGFIX

• Change: Fixed in-app message display issue after user changes
• Impact: MEDIUM - Improves user isolation, no API changes
• Required Action: None
• Risk Level: LOW

v6.5.0

Type: ENHANCEMENT

• Change: Added cookieExpiryInDays initialization option
• Impact: LOW - New optional configuration parameter (default: 400 days)
• Required Action: None (optional configuration, default behavior unchanged)
• Risk Level: LOW

Why: This is a new optional parameter that allows customization of cookie lifetime. Since it has a sensible default (400 days), existing integrations continue to work without modification.

How to apply: No changes required for this upgrade. If customers need custom cookie expiry, they can add this setting in future releases.

Type: ENHANCEMENT

• Change: Introduced Banner.html property for manual HTML injection
• Impact: LOW - New property for advanced banner use cases
• Required Action: None (optional feature, not used in current integration)
• Risk Level: LOW

Type: ENHANCEMENT

• Change: Improved request retry timing to use server-configurable values
• Impact: LOW - Internal optimization for consistency across SDKs
• Required Action: None
• Risk Level: LOW

Critical Breaking Changes

NONE - This is a fully backward-compatible upgrade.

Non-Breaking Changes

1. Platform Detection Improvements (v6.2.0, v6.3.0)

   • Better Smart TV platform categorization
   • Enhanced bot and crawler detection
   • Improved browser detection for ChatGPT Atlas

2. Banner Functionality Extensions (v6.4.0, v6.5.0)

   • New manual logging methods: logBannerImpressions() and logBannerClick()
   • New Banner.html property for custom HTML injection
   • These are additive features that don't affect existing banner usage

3. Initialization Flexibility (v6.5.0)

   • New optional cookieExpiryInDays parameter
   • Default behavior unchanged (400 days)

4. Bug Fixes

   • Banner impression tracking persistence (v6.3.0, v6.3.1)
   • In-app message user isolation (v6.4.0)

Deprecation Warnings

NONE - No features have been deprecated in this version range.

Testing Requirements

Core Functionality Tests

• SDK initialization (verify v6.5.0 loads successfully)
• Session management (openSession())
• User identification (changeUser())
• Event tracking (logCustomEvent())
• Purchase tracking (logPurchase())
• User attributes (setCustomUserAttribute())
• In-app messaging (automatic display)
• SDK metadata injection (addSdkMetadata())

Edge Cases

• SDK version selection (verify CDN URL construction)
• v3.x compatibility (ensure old SDK path still works)
• Deferred initialization (Only Track Known Users setting)
• Custom configuration options (allowCrawlerActivity, noCookies, etc.)

Regression Tests

• Existing test suite passes with v6.5.0
• No changes to API method signatures
• Configuration options remain compatible

Integration Impact Assessment

Current Integration Points

Our Braze web destination uses the following SDK features:

1. Dynamic SDK Loading (initialize method)

   • Loads SDK from CDN: https://js.appboycdn.com/web-sdk/${version}/braze.no-module.min.js
   • ✅ No changes required

2. SDK Initialization (braze.initialize())

   • Configuration options: baseUrl, allowCrawlerActivity, noCookies, sessionTimeout, etc.
   • ✅ All existing options remain compatible
   • ✅ New optional parameter (cookieExpiryInDays) doesn't affect existing code

3. Session Management (braze.openSession())

   • ✅ No changes

4. SDK Metadata (braze.addSdkMetadata())

   • ✅ No changes

5. In-App Messaging (braze.automaticallyShowInAppMessages() or braze.display.automaticallyShowNewInAppMessages())

   • ✅ No changes

6. Action Perform Methods

   • trackEvent: Uses logCustomEvent()
   • trackPurchase: Uses logPurchase()
   • updateUserProfile: Uses changeUser(), setEmail(), setCustomUserAttribute(), etc.
   • ✅ No API changes to any of these methods

Files Requiring Updates

1. index.ts

   • Keep defaultVersion as '6.1'
   • Add '6.5' to the sdkVersion choices list as an opt-in version
   • No other index.ts changes required

2. Tests

   • Update tests to verify v6.5.0 loads correctly
   • Add feature flag tests (stable vs canary)
   • Verify all existing tests pass

3. package.json (if needed)

   • Current: "@braze/web-sdk": "npm:@braze/web-sdk@^5"
   • May need to update to ^6 for TypeScript types
   • Check if @braze/web-sdk v6 types are available

Risk Assessment

Overall Risk Level: LOW

Rationale

1. No Breaking Changes: All changes are backward-compatible enhancements
2. No API Changes: Core methods remain unchanged
3. No Configuration Requirements: All new features are optional
4. Bug Fixes: Several bug fixes improve stability
5. Proven Pattern: Browser-mode destinations load SDK from CDN, making version upgrades straightforward

Mitigation Strategy

1. Opt-In Model: Version 6.5 is available as an explicit customer choice in the settings dropdown
2. Safe Default: New installations default to 6.1 (stable)
3. Comprehensive Testing: All existing tests must pass
4. Instant Rollback: Customers can switch back to 6.1 in settings at any time
5. Low Impact: Browser-mode destination changes don't affect server infrastructure

Recommendations

1. Proceed with Upgrade: No blocking issues identified
2. Add v6.5 to Version Choices: Update UI to include v6.5.0 option
3. Keep Default at 6.1: Maintain 6.1 as the safe default; consider updating to 6.5 in a follow-up PR once adoption is validated
4. Monitor Rollout: Watch for any unexpected behavior from customers who opt in to 6.5
5. Consider Future Enhancement: The new cookieExpiryInDays parameter could be exposed to customers in a future release if there's demand

Additional Notes

• The Braze Web SDK v6.5.0 is available on their CDN at: https://js.appboycdn.com/web-sdk/6.5/braze.no-module.min.js
• TypeScript types may need verification if using @braze/web-sdk package
• This upgrade maintains compatibility with both SDK v3.x (appboy) and SDK v4+ (braze) patterns used in our code
• No changes required to authentication, request building, or action perform logic

Changelog Source

• GitHub: https://github.com/braze-inc/braze-web-sdk/blob/master/CHANGELOG.md
• Versions analyzed: 6.2.0, 6.3.0, 6.3.1, 6.4.0, 6.5.0
• Analysis date: 2026-04-30

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

[arnav777dev]

New findings from this review pass:

Missing test matrix coverage for v6.5 (medium)

trackEvent.test.ts:3 and trackPurchase.test.ts:4 both define testSdkVersions = ['3.5', '4.1'] and iterate tests across those versions. Version 6.5 is not included, so the new SDK version is never exercised through the action-level tests. Since the 6.x code path uses braze.no-module.min.js (vs appboy.no-amd.min.js for 3.x), adding '6.1' or '6.5' to those matrices would verify the correct SDK path is exercised for track and purchase events.

index.ts:21 — defaultVersion local const shadows the imported constant (low)

const defaultVersion = DESTINATION_API_VERSION is a pass-through alias. It means defaultVersion and DESTINATION_API_VERSION are two separate names for the same value, with defaultVersion used for the runtime fallback (sdkVersion ?? defaultVersion) and DESTINATION_API_VERSION used in the choices array. If someone bumps DESTINATION_API_VERSION in versioning-info.ts but forgets to re-check index.ts, the choices entry updates but the runtime fallback stays on whatever defaultVersion was last set to. Consider using DESTINATION_API_VERSION directly and removing the alias.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[itsarijitray]

New findings from this review pass:

Missing test matrix coverage for v6.5 (medium)

trackEvent.test.ts:3 and trackPurchase.test.ts:4 both define testSdkVersions = ['3.5', '4.1'] and iterate tests across those versions. Version 6.5 is not included, so the new SDK version is never exercised through the action-level tests. Since the 6.x code path uses braze.no-module.min.js (vs appboy.no-amd.min.js for 3.x), adding '6.1' or '6.5' to those matrices would verify the correct SDK path is exercised for track and purchase events.

index.ts:21 — defaultVersion local const shadows the imported constant (low)

const defaultVersion = DESTINATION_API_VERSION is a pass-through alias. It means defaultVersion and DESTINATION_API_VERSION are two separate names for the same value, with defaultVersion used for the runtime fallback (sdkVersion ?? defaultVersion) and DESTINATION_API_VERSION used in the choices array. If someone bumps DESTINATION_API_VERSION in versioning-info.ts but forgets to re-check index.ts, the choices entry updates but the runtime fallback stays on whatever defaultVersion was last set to. Consider using DESTINATION_API_VERSION directly and removing the alias.

done @arnav777dev