@mparticle/web-braze-kit-5 3.1.0 → 3.2.0

package/README.md

@@ -1,46 +1,101 @@
-![Braze Logo](https://github.com/mparticle-integrations/mparticle-javascript-integration-appboy/blob/master/braze-logo.png) 
+![Braze Logo](https://github.com/mparticle-integrations/mparticle-javascript-integration-appboy/blob/master/braze-logo.png)
 
-⚠️⚠️⚠️
-# Notice! Opt in is now available for Braze Web SDK V5 - Action Required
+# mParticle Braze Kit — Braze Web SDK V5
 
-You can now select what version of the Braze SDK you want to use when setting up a Braze connection in the mParticle UI.  Braze occasionally makes breaking changes to their SDK, so if you call `appboy` directly in your code, you will have to update your code to ensure your website performs as expected when updating versions of Braze.
+This kit bundles **Braze Web SDK V5** (`@braze/web-sdk@^5.5.0`) and exposes it on the page as `window.braze`.
 
-Please review the [Braze Changelog](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/changelog#500) and [V5 migration guide](https://github.com/braze-inc/braze-web-sdk/blob/master/UPGRADE_GUIDE.md) to learn about the differences between V4 and V5 and what changes you will need to make in your code. The most significant breaking changes are the removal of the deprecated `enableHtmlInAppMessages` initialization option (replaced by `allowUserSuppliedJavascript`), in addition to the removal and renaming of several APIs.
+---
 
-You can opt into the latest major version of the Braze Web SDK whether you implement mParticle's Web SDK using npm or our snippet/CDN.
-* Customers who self-host mParticle via npm - You should add @mparticle/web-braze-kit version 5.0.0 or greater in your package.json.  You must also select `Version 5` under `Braze Web SDK Version`  in the Braze connection settings.
-* Customers who load mParticle via snippet/CDN - You must  select `Version 5` under `Braze Web SDK Version`  in the Braze connection settings.
+## ⚠️ We recommend upgrading to Braze Web SDK V6
 
-Note that the following is only one example of migrating from V3 to V5.  Everywhere you manually call `appboy` needs to be updated similar to the below. If you are using NPM, you can skip to step 3.  Please be sure to test your site fully in development prior to releasing.
+Braze is now on **V6**, and V6 is the version mParticle recommends for all customers. We recommend updating straight to V6 for latest support of all Braze features.
 
+The `braze` global, initialization options, and the vast majority of the API are unchanged. Two areas break — the **legacy News Feed**, which V6 removes entirely, and **manual card-analytics method names**.
+
+See the [Braze Event Integration](https://docs.mparticle.com/integrations/braze/event/) docs.
+
+### How to upgrade
+
+1. **Audit the code you own.** If you call Braze directly, find every `braze` reference and compare it with the table below and Braze's upgrade documentation.
+2. **Move to the V6 kit.**
+   - Self-hosting via npm with **core Web SDK v3 (latest)**: `npm install @mparticle/web-braze-kit-6`
+   - Self-hosting via npm with **core Web SDK v2 (legacy)**: `npm install @mparticle/web-braze-kit@^6`
+   - Loading mParticle via snippet/CDN: nothing to install; the kit is delivered for you.
+3. **Add defensive code** if you load mParticle via the snippet and call Braze directly. Skip this if you self-host via npm. See [Write version-tolerant code](#write-version-tolerant-code).
+4. **Select `Version 6`** under `Braze Web SDK Version` in your Braze connection settings in the mParticle UI. This step is **required for both npm and snippet/CDN** integrations — installing the package alone does not switch you over.
+5. **Update your push service worker**, if you use push. See [Push notifications](#push-notifications).
+
+---
+
+## What changed from V5 to V6
+
+The table below is the V5 API you have today mapped to the V6 API you should use.
+
+Primary sources: the [Braze Web SDK changelog](https://github.com/braze-inc/braze-web-sdk/blob/master/CHANGELOG.md) and the [Braze upgrade guide](https://github.com/braze-inc/braze-web-sdk/blob/master/UPGRADE_GUIDE.md).
+
+| V5 | V6 |
+| --- | --- |
+| `braze.logCardClick()` | `braze.logContentCardClick()` — already exists in V5, so you can rename before you upgrade |
+| `braze.logCardImpressions()` | `braze.logContentCardImpressions()` — already exists in V5 |
+| Legacy News Feed: `Feed`, `destroyFeed()`, `getCachedFeed()`, `logFeedDisplayed()`, `requestFeedRefresh()`, `showFeed()`, `subscribeToFeedUpdates()`, `toggleFeed()` | **No drop-in replacement.** Migrate to Content Cards |
+| `Card.created`, `Card.categories` | No replacement; these were News Feed fields |
+| `ImageOnly.linkText` | No replacement; unused |
+| Custom banner HTML + `logBannerClick()` / `logBannerImpressions()` | `braze.insertBanner()`, which handles rendering, impressions, and clicks |
+
+If you call Braze directly, search your codebase for **every** `braze` reference and use Braze's changelog and upgrade guide to determine the corresponding V6 change. The table above highlights common changes but is not a substitute for reviewing your implementation.
+
+For example, use the Content Card-specific analytics methods:
 
-* Step 1: Legacy code sample. Find all the places where your code references the `appboy.display` namespace. Braze has removed all instances of the `display` namespace:
 ```javascript
-window.appboy.display.destroyFeed();
+// V5
+window.braze.logCardImpressions([card], true);
+
+// V6
+window.braze.logContentCardImpressions([card]);
 ```
 
-Step 2: Roll out code changes prior to opting in to V5
+---
+
+## Write version-tolerant code
+
+Do this if you load mParticle via the snippet. After you select `Version 6`, cache busting can leave some visitors on the old kit for a while, so if you call Braze directly, ship code that works against both versions first, then flip the setting.
+
+If you self-host via npm, you control when the kit version ships with your own deploy, so you do not need version-tolerant fallbacks — update your Braze calls and deploy them together with the V6 kit.
+
+The `braze` global is the same in V5 and V6, so guard on the method instead. For the card-analytics renames:
+
 ```javascript
-if (window.appboy) {
-	window.appboy.display.destroyFeed();
-} else if (window.braze) {
-	window.braze.destroyFeed();
+if (window.braze.logContentCardImpressions) {
+    window.braze.logContentCardImpressions([card]);
+} else {
+    window.braze.logCardImpressions([card], true);
 }
 ```
-Step 3: Whether you are using the snippet or self hosting, you need to navigate to your Braze connection settings and select `Version 5` from the `Braze Web SDK Version` drop down.
 
-Step 4: After you opt in, you can simplify your code. We recommend testing and waiting at least 24 hours between opting in and removing previous instances of `appboy` and doing thorough testing of your application in a development environment to ensure everything is working:
-```javascript
-window.braze.destroyFeed();
-```
+Search your codebase for every remaining direct `braze` call and apply the same pattern, using the mapping table above and Braze's changelog to find the V6 equivalent of each one.
 
-Step 5: Push Notifications via service-worker.js
-If you use Push Notifications, we have updated the `service-worker.js` file.  In our testing, Braze’s push notifications work as expected regardless of what version of the service-worker is used, but we recommend updating this file to ensure future compatibility.  In your `service-worker.js` file, update the code to reference `https://static.mparticle.com/sdk/js/braze/service-worker-5.5.0.js` instead of `https://static.mparticle.com/sdk/js/braze/service-worker-4.2.0.js`.  Your `service-worker.js` file should now contain:
+Once V6 is live and verified, you can delete the fallbacks and call the V6 methods directly.
+
+---
+
+## Push notifications
+
+If you use push notifications, update your `service-worker.js` to import the V6 service worker that mParticle hosts:
 
 ```javascript
-self.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker-5.5.0.js')
+self.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker-6.5.0.js');
 ```
 
+mParticle hosts Braze's service worker to avoid unpredictable versioning issues — do not point at Braze's own service worker CDN.
+
+---
+
+## Reference
+
+- [mParticle Braze integration docs](https://docs.mparticle.com/integrations/braze/event/)
+- [Braze Web SDK changelog](https://github.com/braze-inc/braze-web-sdk/blob/master/CHANGELOG.md)
+- [Braze Web SDK upgrade guide](https://github.com/braze-inc/braze-web-sdk/blob/master/UPGRADE_GUIDE.md)
+- [Braze Web SDK API reference](https://js.appboycdn.com/web-sdk/latest/doc/modules/braze.html)
 
 # License
 
@@ -56,4 +111,4 @@ Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
-limitations under the License.
+limitations under the License.

package/dist/BrazeKit.common.js

@@ -10021,7 +10021,7 @@ window.braze = require$$0;
 var name = 'Appboy',
     suffix = 'v5',
     moduleId = 28,
-    version = '5.0.3',
+    version = "3.2.0",
     MessageType = {
         PageView: 3,
         PageEvent: 4,

package/dist/BrazeKit.esm.js

@@ -10019,7 +10019,7 @@ window.braze = require$$0;
 var name = 'Appboy',
     suffix = 'v5',
     moduleId = 28,
-    version = '5.0.3',
+    version = "3.2.0",
     MessageType = {
         PageView: 3,
         PageEvent: 4,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mparticle/web-braze-kit-5",
-    "version": "3.1.0",
+    "version": "3.2.0",
     "author": "mParticle Developers <developers@mparticle.com> (https://www.mparticle.com)",
     "description": "mParticle integration sdk for Braze",
     "main": "dist/BrazeKit.common.js",
@@ -25,6 +25,7 @@
     "devDependencies": {
         "@rollup/plugin-commonjs": "22.0.1",
         "@rollup/plugin-node-resolve": "13.3.0",
+        "@rollup/plugin-replace": "^6.0.3",
         "chai": "^4.2.0",
         "karma": "^5.1.0",
         "karma-chai": "^0.1.0",