@mparticle/web-braze-kit-4 3.1.0 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +79 -28
  2. package/dist/BrazeKit.common.js +1 -1
  3. package/package.json +2 -1
package/README.md CHANGED
@@ -1,52 +1,103 @@
1
- ![Braze Logo](https://github.com/mparticle-integrations/mparticle-javascript-integration-appboy/blob/master/braze-logo.png)
1
+ ![Braze Logo](https://github.com/mparticle-integrations/mparticle-javascript-integration-appboy/blob/master/braze-logo.png)
2
2
 
3
- ⚠️⚠️⚠️
4
- # Notice! Opt in is now available for Braze Web SDK V4 - Action Required
3
+ # mParticle Braze Kit — Braze Web SDK V4
5
4
 
6
- 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.
5
+ This kit bundles **Braze Web SDK V4** (`@braze/web-sdk@^4.2.1`) and exposes it on the page as `window.braze`.
7
6
 
8
- Please review the [Braze Changelog](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/changelog#400) and [V4 migration guide](https://github.com/braze-inc/braze-web-sdk/blob/master/UPGRADE_GUIDE.md) to learn about the differences between V3 and V4 and what changes you will need to make in your code. The most significant breaking changes are the replacement of the `appboy` class name with `braze`, in addition to the removal and renaming of several APIs.
7
+ ---
9
8
 
10
- 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.
11
- * Customers who self-host mParticle via npm - You should add @mparticle/web-braze-kit version 4.0.0 or greater in your package.json. You must also select `Version 4` under `Braze Web SDK Version` in the Braze connection settings.
12
- * Customers who load mParticle via snippet/CDN - You must select `Version 4` under `Braze Web SDK Version` in the Braze connection settings.
9
+ ## ⚠️ We recommend upgrading to Braze Web SDK V6
13
10
 
14
- Note that the following is only one example. 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.
11
+ 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.
15
12
 
13
+ See the [Braze Event Integration](https://docs.mparticle.com/integrations/braze/event/) docs.
14
+
15
+ ### How to upgrade
16
+
17
+ 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.
18
+ 2. **Move to the V6 kit.**
19
+ - Self-hosting via npm with **core Web SDK v3 (latest)**: `npm install @mparticle/web-braze-kit-6`
20
+ - Self-hosting via npm with **core Web SDK v2 (legacy)**: `npm install @mparticle/web-braze-kit@^6`
21
+ - Loading mParticle via snippet/CDN: nothing to install; the kit is delivered for you.
22
+ 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).
23
+ 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.
24
+ 5. **Update your push service worker**, if you use push. See [Push notifications](#push-notifications).
25
+
26
+ ---
27
+
28
+ ## What changed from V4 to V6
29
+
30
+ The table below is the V4 API you have today mapped to the V6 API you should use.
31
+
32
+ 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).
33
+
34
+ | V4 | V6 |
35
+ | --- | --- |
36
+ | `braze.logCardClick()` | `braze.logContentCardClick()` — already exists in V4, so you can rename before you upgrade |
37
+ | `braze.logCardImpressions()` | `braze.logContentCardImpressions()` — already exists in V4 |
38
+ | `braze.logContentCardsDisplayed()` *(already a no-op)* | Delete it |
39
+ | Legacy News Feed: `Feed`, `destroyFeed()`, `getCachedFeed()`, `logFeedDisplayed()`, `requestFeedRefresh()`, `showFeed()`, `subscribeToFeedUpdates()`, `toggleFeed()` | **No drop-in replacement.** Migrate to Content Cards |
40
+ | `braze.Banner` card class *(deprecated since 4.9.0)* | `braze.ImageOnly` |
41
+ | `ab-banner` CSS class | `ab-image-only` |
42
+ | `enableHtmlInAppMessages` init option *(deprecated since 3.3.0)* | `allowUserSuppliedJavascript` |
43
+ | `getDeviceId(callback)` / `User.getUserId(callback)` *(callback params deprecated since 4.10.0)* | Return values directly: `getDeviceId()`, `getUserId()` |
44
+ | `Card.created`, `Card.categories` | No replacement; these were News Feed fields |
45
+ | `ImageOnly.linkText` | No replacement; unused |
46
+
47
+ 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.
48
+
49
+ For example, use the Content Card-specific analytics methods:
16
50
 
17
- * 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:
18
51
  ```javascript
19
- window.appboy.display.destroyFeed();
52
+ // V4
53
+ window.braze.logCardImpressions([card], true);
54
+
55
+ // V6
56
+ window.braze.logContentCardImpressions([card]);
20
57
  ```
21
58
 
22
- Step 2: Roll out code changes prior to opting in to V4
59
+ ---
60
+
61
+ ## Write version-tolerant code
62
+
63
+ 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.
64
+
65
+ 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.
66
+
67
+ The `braze` global is the same in V4 and V6, so guard on the method instead. For the card-analytics renames:
68
+
23
69
  ```javascript
24
- if (window.appboy) {
25
- window.appboy.display.destroyFeed();
26
- } else if (window.braze) {
27
- window.braze.destroyFeed();
70
+ if (window.braze.logContentCardImpressions) {
71
+ window.braze.logContentCardImpressions([card]);
72
+ } else {
73
+ window.braze.logCardImpressions([card], true);
28
74
  }
29
75
  ```
30
- Step 3: Whether you are using the snippet or self hosting, you need to navigate to your Braze connection settings and select `Version 4` from the `Braze Web SDK Version` drop down.
31
76
 
32
- 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:
33
- ```javascript
34
- window.braze.destroyFeed();
35
- ```
77
+ 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.
78
+
79
+ Once V6 is live and verified, you can delete the fallbacks and call the V6 methods directly.
80
+
81
+ ---
36
82
 
37
- Step 5: Push Notifications via service-worker.js
38
- 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-4.2.0.js` instead of `https://static.mparticle.com/sdk/js/braze/service-worker-3.5.0.js`. Your `service-worker.js` file should now contain:
83
+ ## Push notifications
84
+
85
+ If you use push notifications, update your `service-worker.js` to import the V6 service worker that mParticle hosts:
39
86
 
40
87
  ```javascript
41
- self.imports('https://static.mparticle.com/sdk/js/braze/service-worker-4.2.0.js')
88
+ self.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker-6.5.0.js');
42
89
  ```
43
90
 
44
- ### Transition from @mparticle/web-appboy-kit to @mparticle/web-braze-kit
45
-
46
- The legacy @mparticle/web-appboy-kit from npm includes version 2 of the Braze Web SDK. As part of this update, we've created a new [Braze web kit repo](https://github.com/mparticle-integrations/mparticle-javascript-integration-braze) to replace our deprecated [Appboy web kit repo](https://github.com/mparticle-integrations/mparticle-javascript-integration-appboy). If you are still using `@mparticle/web-appboy-kit`, you will need to consider the breaking changes Braze made between V2 and V3 of the Braze SDK (found [here](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/changelog/#300)) as well as the instructions above to get from V2 to V4 of the Braze SDK.
91
+ mParticle hosts Braze's service worker to avoid unpredictable versioning issues — do not point at Braze's own service worker CDN.
47
92
 
93
+ ---
48
94
 
95
+ ## Reference
49
96
 
97
+ - [mParticle Braze integration docs](https://docs.mparticle.com/integrations/braze/event/)
98
+ - [Braze Web SDK changelog](https://github.com/braze-inc/braze-web-sdk/blob/master/CHANGELOG.md)
99
+ - [Braze Web SDK upgrade guide](https://github.com/braze-inc/braze-web-sdk/blob/master/UPGRADE_GUIDE.md)
100
+ - [Braze Web SDK API reference](https://js.appboycdn.com/web-sdk/latest/doc/modules/braze.html)
50
101
 
51
102
  # License
52
103
 
@@ -62,4 +113,4 @@ Unless required by applicable law or agreed to in writing, software
62
113
  distributed under the License is distributed on an "AS IS" BASIS,
63
114
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
64
115
  See the License for the specific language governing permissions and
65
- limitations under the License.
116
+ limitations under the License.
package/dist/BrazeKit.common.js CHANGED
@@ -9170,7 +9170,7 @@ window.braze = require$$0;
9170
9170
  var name = 'Appboy',
9171
9171
  suffix = 'v4',
9172
9172
  moduleId = 28,
9173
- version = '4.2.2',
9173
+ version = "3.2.1",
9174
9174
  MessageType = {
9175
9175
  PageView: 3,
9176
9176
  PageEvent: 4,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mparticle/web-braze-kit-4",
3
- "version": "3.1.0",
3
+ "version": "3.2.1",
4
4
  "author": "mParticle Developers <developers@mparticle.com> (https://www.mparticle.com)",
5
5
  "description": "mParticle integration sdk for Braze",
6
6
  "main": "dist/BrazeKit.common.js",
@@ -23,6 +23,7 @@
23
23
  "devDependencies": {
24
24
  "@rollup/plugin-commonjs": "22.0.1",
25
25
  "@rollup/plugin-node-resolve": "13.3.0",
26
+ "@rollup/plugin-replace": "^6.0.3",
26
27
  "chai": "^4.2.0",
27
28
  "karma": "^5.1.0",
28
29
  "karma-chai": "^0.1.0",