@mparticle/web-braze-kit-6 3.0.0 → 3.2.0

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.
package/README.md CHANGED
@@ -1,52 +1,217 @@
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 V6
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 V6** (`@braze/web-sdk@^6.0.0`) 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
+ ## ✅ This is the version we recommend
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
+ **V6 is the current major version of the Braze Web SDK and the version mParticle recommends for all customers.** Braze ships fixes and new features only on the V6 line, so if you are already here, you are on the right kit and there is nothing to upgrade.
15
12
 
13
+ If you are still on the V3, V4, or V5 kit, we recommend updating straight to V6 for latest support of all Braze features. Jump to the section for your current version:
14
+
15
+ - [Upgrading from V3 to V6](#upgrading-from-v3-to-v6) — the `appboy` global goes away
16
+ - [Upgrading from V4 to V6](#upgrading-from-v4-to-v6) — deprecated API cleanup plus News Feed removal
17
+ - [Upgrading from V5 to V6](#upgrading-from-v5-to-v6) — News Feed removal and card-analytics renames
18
+ - [Write version-tolerant code](#write-version-tolerant-code) — snippet/CDN only; ship code that works before and after you select Version 6
19
+
20
+ See the [Braze Event Integration](https://docs.mparticle.com/integrations/braze/event/) docs.
21
+
22
+ ---
23
+
24
+ ## Installing and enabling V6
25
+
26
+ Regardless of which version you are coming from, the mechanics are the same:
27
+
28
+ 1. **Install the kit** (only if you self-host mParticle via npm — snippet/CDN users have it delivered automatically):
29
+ - Self-hosting via npm with **core Web SDK v3 (latest)**: `npm install @mparticle/web-braze-kit-6`
30
+ - Self-hosting via npm with **core Web SDK v2 (legacy)**: `npm install @mparticle/web-braze-kit@^6`
31
+ 2. **Select `Version 6`** under `Braze Web SDK Version` in your Braze connection settings in the mParticle UI. **This is required for both npm and snippet/CDN integrations** — installing the package alone does not switch you over.
32
+ 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) and use the example for the version you are coming from.
33
+ 4. **Update your push service worker**, if you use push. See [Push notifications](#push-notifications).
34
+
35
+ If you never call Braze directly from your own code, or you self-host via npm, skip step 3. The code samples below only matter if you reference `window.appboy` or `window.braze` yourself.
36
+
37
+ We recommend shipping your code changes **before** flipping the version setting wherever possible, so that the code change and the version change remain two separately revertible steps.
38
+
39
+ ---
40
+
41
+ ## Upgrading from V3 to V6
42
+
43
+ We recommend updating straight to V6 for latest support of all Braze features.
44
+
45
+ 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).
46
+
47
+ | V3 | V6 |
48
+ | --- | --- |
49
+ | `appboy` global | `braze` |
50
+ | `appboy.display.*` namespace | Methods moved to the top level: `braze.*` |
51
+ | `appboy.registerAppboyPushMessages()` | `braze.requestPushPermission()` |
52
+ | `appboy.unregisterAppboyPushMessages()` | `braze.unregisterPush()` |
53
+ | `appboy.display.automaticallyShowNewInAppMessages()` | `braze.automaticallyShowInAppMessages()` — must run *before* `openSession()` |
54
+ | `appboy.toggleAppboyLogging()` | `braze.toggleLogging()` |
55
+ | `appboy.isPushGranted()` *(deprecated since 1.6.2)* | `braze.isPushPermissionGranted()` |
56
+ | `appboy.subscribeToNewInAppMessages()` *(deprecated since 2.4.0)* | `braze.subscribeToInAppMessage()` |
57
+ | `appboy.trackLocation()` *(deprecated since 3.3.0)* | Native Geolocation API + `User.setLastKnownLocation()` |
58
+ | `appboy.stopWebTracking()` *(deprecated since 3.5.0)* | `braze.disableSDK()` |
59
+ | `appboy.resumeWebTracking()` *(deprecated since 3.5.0)* | `braze.enableSDK()` |
60
+ | `appboy.logCardClick()` | `braze.logContentCardClick()` |
61
+ | `appboy.logCardImpressions()` | `braze.logContentCardImpressions()` |
62
+ | `appboy.logContentCardsDisplayed()` | Delete it — it was already a no-op |
63
+ | Legacy News Feed APIs | **No drop-in replacement.** Migrate to Content Cards |
64
+ | `devicePropertyWhitelist` init option | `devicePropertyAllowlist` |
65
+ | `enableHtmlInAppMessages` init option | `allowUserSuppliedJavascript` |
66
+ | `language` init option | `localization` |
67
+ | `safariWebsitePushId` param on `registerAppboyPushMessages()` | `safariWebsitePushId` initialization option |
68
+ | `User.setAvatarImageUrl()` | No replacement |
69
+ | `appboy.Banner` card class | `braze.ImageOnly` |
70
+ | `ab-banner` CSS class | `ab-image-only` |
71
+
72
+ Search your codebase for **every** `appboy` 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.
73
+
74
+ For example, the `appboy.display` namespace was removed and its methods moved to `braze`:
16
75
 
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
76
  ```javascript
19
- window.appboy.display.destroyFeed();
77
+ // V3
78
+ window.appboy.display.showContentCards();
79
+
80
+ // V6
81
+ window.braze.showContentCards();
20
82
  ```
21
83
 
22
- Step 2: Roll out code changes prior to opting in to V4
84
+ ---
85
+
86
+ ## Upgrading from V4 to V6
87
+
88
+ We recommend updating straight to V6 for latest support of all Braze features.
89
+
90
+ | V4 | V6 |
91
+ | --- | --- |
92
+ | `braze.logCardClick()` | `braze.logContentCardClick()` — already exists in V4 |
93
+ | `braze.logCardImpressions()` | `braze.logContentCardImpressions()` — already exists in V4 |
94
+ | `braze.logContentCardsDisplayed()` *(already a no-op)* | Delete it |
95
+ | Legacy News Feed APIs | **No drop-in replacement.** Migrate to Content Cards |
96
+ | `braze.Banner` card class *(deprecated since 4.9.0)* | `braze.ImageOnly` |
97
+ | `ab-banner` CSS class | `ab-image-only` |
98
+ | `enableHtmlInAppMessages` init option | `allowUserSuppliedJavascript` |
99
+ | `getDeviceId(callback)` / `User.getUserId(callback)` | Return values directly |
100
+ | `Card.created`, `Card.categories` | No replacement; these were News Feed fields |
101
+
102
+ Search your codebase for **every** direct `braze` call 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.
103
+
104
+ For example, use the Content Card-specific analytics methods:
105
+
23
106
  ```javascript
24
- if (window.appboy) {
25
- window.appboy.display.destroyFeed();
26
- } else if (window.braze) {
27
- window.braze.destroyFeed();
107
+ // V4
108
+ window.braze.logCardImpressions([card], true);
109
+
110
+ // V6
111
+ window.braze.logContentCardImpressions([card]);
112
+ ```
113
+
114
+ ---
115
+
116
+ ## Upgrading from V5 to V6
117
+
118
+ We recommend updating straight to V6 for latest support of all Braze features. The `braze` global, initialization options, and nearly the whole API are unchanged.
119
+
120
+ | V5 | V6 |
121
+ | --- | --- |
122
+ | `braze.logCardClick()` | `braze.logContentCardClick()` — already exists in V5 |
123
+ | `braze.logCardImpressions()` | `braze.logContentCardImpressions()` — already exists in V5 |
124
+ | Legacy News Feed APIs | **No drop-in replacement.** Migrate to Content Cards |
125
+ | `Card.created`, `Card.categories` | No replacement; these were News Feed fields |
126
+ | `ImageOnly.linkText` | No replacement |
127
+ | Custom banner HTML + `logBannerClick()` / `logBannerImpressions()` | `braze.insertBanner()` |
128
+
129
+ Search your codebase for **every** direct `braze` call 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.
130
+
131
+ For example, use the Content Card-specific analytics methods:
132
+
133
+ ```javascript
134
+ // V5
135
+ window.braze.logCardImpressions([card], true);
136
+
137
+ // V6
138
+ window.braze.logContentCardImpressions([card]);
139
+ ```
140
+
141
+ ---
142
+
143
+ ## Write version-tolerant code
144
+
145
+ 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.
146
+
147
+ 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.
148
+
149
+ Use the example that matches the version you are coming from. Search your codebase for every remaining direct `appboy` or `braze` call and apply the same pattern, using the mapping table for your starting version and Braze's changelog to find the V6 equivalent of each one.
150
+
151
+ Once V6 is live and verified, you can delete the fallbacks and call the V6 methods directly.
152
+
153
+ ### From V3
154
+
155
+ The V3 → V6 change that matters most is the global rename, so guard on which global is present:
156
+
157
+ ```javascript
158
+ if (window.braze) {
159
+ window.braze.showContentCards();
160
+ } else if (window.appboy) {
161
+ window.appboy.display.showContentCards();
162
+ }
163
+ ```
164
+
165
+ ### From V4
166
+
167
+ The `braze` global is the same in V4 and V6, so guard on the method instead. For the card-analytics renames:
168
+
169
+ ```javascript
170
+ if (window.braze.logContentCardImpressions) {
171
+ window.braze.logContentCardImpressions([card]);
172
+ } else {
173
+ window.braze.logCardImpressions([card], true);
28
174
  }
29
175
  ```
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
176
 
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:
177
+ ### From V5
178
+
179
+ The `braze` global is the same in V5 and V6, so guard on the method instead. For the card-analytics renames:
180
+
33
181
  ```javascript
34
- window.braze.destroyFeed();
182
+ if (window.braze.logContentCardImpressions) {
183
+ window.braze.logContentCardImpressions([card]);
184
+ } else {
185
+ window.braze.logCardImpressions([card], true);
186
+ }
35
187
  ```
36
188
 
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:
189
+ ---
190
+
191
+ ## Push notifications
192
+
193
+ If you use push notifications, your `service-worker.js` should import the V6 service worker that mParticle hosts:
39
194
 
40
195
  ```javascript
41
- self.imports('https://static.mparticle.com/sdk/js/braze/service-worker-4.2.0.js')
196
+ self.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker-6.5.0.js');
42
197
  ```
43
198
 
44
- ### Transition from @mparticle/web-appboy-kit to @mparticle/web-braze-kit
199
+ mParticle hosts Braze's service worker to avoid unpredictable versioning issues — do not point at Braze's own service worker CDN.
200
+
201
+ ---
202
+
203
+ ## eCommerce Recommended Events
45
204
 
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.
205
+ If you enable the `Enable eCommerce Recommended Events` connection setting, mParticle maps commerce events to Braze's eCommerce Recommended Events schema. Client-side forwarding of these events requires **web Braze kit version 6.1.0 or later**. On earlier versions, mParticle falls back to forwarding commerce events as legacy custom and purchase events. See the [connection settings reference](https://docs.mparticle.com/integrations/braze/event/) for the full event and attribute mapping.
47
206
 
207
+ ---
48
208
 
209
+ ## Reference
49
210
 
211
+ - [mParticle Braze integration docs](https://docs.mparticle.com/integrations/braze/event/)
212
+ - [Braze Web SDK changelog](https://github.com/braze-inc/braze-web-sdk/blob/master/CHANGELOG.md)
213
+ - [Braze Web SDK upgrade guide](https://github.com/braze-inc/braze-web-sdk/blob/master/UPGRADE_GUIDE.md)
214
+ - [Braze Web SDK API reference](https://js.appboycdn.com/web-sdk/latest/doc/modules/braze.html)
50
215
 
51
216
  # License
52
217
 
@@ -62,4 +227,4 @@ Unless required by applicable law or agreed to in writing, software
62
227
  distributed under the License is distributed on an "AS IS" BASIS,
63
228
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
64
229
  See the License for the specific language governing permissions and
65
- limitations under the License.
230
+ limitations under the License.