@mparticle/web-braze-kit-3 3.1.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 +92 -28
- package/dist/BrazeKit.common.js +1 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,52 +1,116 @@
|
|
|
1
|
-

|
|
1
|
+

|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
# Notice! Opt in is now available for Braze Web SDK V4 - Action Required
|
|
3
|
+
# mParticle Braze Kit — Braze Web SDK V3
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
This kit bundles **Braze Web SDK V3** (`@braze/web-sdk@^3.5.0`) and exposes it on the page as `window.appboy`.
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
---
|
|
9
8
|
|
|
10
|
-
|
|
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 now! You must also select `Version 4` under `Braze Web SDK Version` in the Braze connection settings.
|
|
12
|
-
* Customers who load mParticle via snippet/CDN - Opting in is available via the mParticle UI in your Braze connection settings.
|
|
9
|
+
## ⚠️ We recommend upgrading to Braze Web SDK V6
|
|
13
10
|
|
|
14
|
-
|
|
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 `appboy` 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 V3 to V6
|
|
29
|
+
|
|
30
|
+
The table below is the V3 API you have today mapped to the V6 API you should use. Several of these were deprecated in V3 and then removed.
|
|
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
|
+
| V3 | V6 |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| `appboy` global | `braze` |
|
|
37
|
+
| `appboy.display.*` namespace | Methods moved to the top level: `braze.*` |
|
|
38
|
+
| `appboy.registerAppboyPushMessages()` | `braze.requestPushPermission()` |
|
|
39
|
+
| `appboy.unregisterAppboyPushMessages()` | `braze.unregisterPush()` |
|
|
40
|
+
| `appboy.display.automaticallyShowNewInAppMessages()` | `braze.automaticallyShowInAppMessages()` — must run *before* `openSession()` |
|
|
41
|
+
| `appboy.toggleAppboyLogging()` | `braze.toggleLogging()` |
|
|
42
|
+
| `appboy.isPushGranted()` *(deprecated since 1.6.2)* | `braze.isPushPermissionGranted()` |
|
|
43
|
+
| `appboy.subscribeToNewInAppMessages()` *(deprecated since 2.4.0)* | `braze.subscribeToInAppMessage()` |
|
|
44
|
+
| `appboy.trackLocation()` *(deprecated since 3.3.0)* | Native Geolocation API + `User.setLastKnownLocation()` |
|
|
45
|
+
| `appboy.stopWebTracking()` *(deprecated since 3.5.0)* | `braze.disableSDK()` |
|
|
46
|
+
| `appboy.resumeWebTracking()` *(deprecated since 3.5.0)* | `braze.enableSDK()` |
|
|
47
|
+
| `appboy.logCardClick()` | `braze.logContentCardClick()` |
|
|
48
|
+
| `appboy.logCardImpressions()` | `braze.logContentCardImpressions()` |
|
|
49
|
+
| `appboy.logContentCardsDisplayed()` | Delete it — it was already a no-op |
|
|
50
|
+
| Legacy News Feed: `Feed`, `destroyFeed()`, `getCachedFeed()`, `logFeedDisplayed()`, `requestFeedRefresh()`, `showFeed()`, `subscribeToFeedUpdates()`, `toggleFeed()` | **No drop-in replacement.** Migrate to Content Cards |
|
|
51
|
+
| `devicePropertyWhitelist` init option *(deprecated since 3.1.0)* | `devicePropertyAllowlist` |
|
|
52
|
+
| `enableHtmlInAppMessages` init option *(deprecated since 3.3.0)* | `allowUserSuppliedJavascript` |
|
|
53
|
+
| `language` init option | `localization` |
|
|
54
|
+
| `safariWebsitePushId` param on `registerAppboyPushMessages()` | `safariWebsitePushId` initialization option |
|
|
55
|
+
| `cardId` / `campaignId` on in-app messages | Update your `InAppMessage` subclass constructors |
|
|
56
|
+
| `User.setAvatarImageUrl()` | No replacement; no longer used |
|
|
57
|
+
| `appboy.Banner` card class | `braze.ImageOnly` |
|
|
58
|
+
| `ab-banner` CSS class | `ab-image-only` |
|
|
59
|
+
|
|
60
|
+
If you call Braze directly, 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.
|
|
61
|
+
|
|
62
|
+
For example, the `appboy.display` namespace was removed and its methods moved to `braze`:
|
|
16
63
|
|
|
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
64
|
```javascript
|
|
19
|
-
|
|
65
|
+
// V3
|
|
66
|
+
window.appboy.display.showContentCards();
|
|
67
|
+
|
|
68
|
+
// V6
|
|
69
|
+
window.braze.showContentCards();
|
|
20
70
|
```
|
|
21
71
|
|
|
22
|
-
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## Write version-tolerant code
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
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.
|
|
79
|
+
|
|
80
|
+
The V3 → V6 change that matters most is the global rename, so guard on which global is present:
|
|
81
|
+
|
|
23
82
|
```javascript
|
|
24
|
-
if (window.
|
|
25
|
-
|
|
26
|
-
} else if (window.
|
|
27
|
-
|
|
83
|
+
if (window.braze) {
|
|
84
|
+
window.braze.showContentCards();
|
|
85
|
+
} else if (window.appboy) {
|
|
86
|
+
window.appboy.display.showContentCards();
|
|
28
87
|
}
|
|
29
88
|
```
|
|
30
|
-
Step 3: Opt into Version 4. Simply navigate to your connection settings and selection `Version 4` from the new Braze Web SDK Version drop down.
|
|
31
89
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
window.braze.
|
|
35
|
-
|
|
90
|
+
Search your codebase for every remaining direct `appboy` call and apply the same pattern, using the mapping table above and Braze's changelog to find the V6 equivalent of each one.
|
|
91
|
+
|
|
92
|
+
Once V6 is live and verified, you can delete the `window.appboy` fallbacks and call `window.braze` directly.
|
|
93
|
+
|
|
94
|
+
---
|
|
36
95
|
|
|
37
|
-
|
|
38
|
-
|
|
96
|
+
## Push notifications
|
|
97
|
+
|
|
98
|
+
If you use push notifications, update your `service-worker.js` to import the V6 service worker that mParticle hosts:
|
|
39
99
|
|
|
40
100
|
```javascript
|
|
41
|
-
self.
|
|
101
|
+
self.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker-6.5.0.js');
|
|
42
102
|
```
|
|
43
103
|
|
|
44
|
-
|
|
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.
|
|
104
|
+
mParticle hosts Braze's service worker to avoid unpredictable versioning issues — do not point at Braze's own service worker CDN.
|
|
47
105
|
|
|
106
|
+
---
|
|
48
107
|
|
|
108
|
+
## Reference
|
|
49
109
|
|
|
110
|
+
- [mParticle Braze integration docs](https://docs.mparticle.com/integrations/braze/event/)
|
|
111
|
+
- [Braze Web SDK changelog](https://github.com/braze-inc/braze-web-sdk/blob/master/CHANGELOG.md)
|
|
112
|
+
- [Braze Web SDK upgrade guide](https://github.com/braze-inc/braze-web-sdk/blob/master/UPGRADE_GUIDE.md)
|
|
113
|
+
- [Braze Web SDK API reference](https://js.appboycdn.com/web-sdk/latest/doc/modules/braze.html)
|
|
50
114
|
|
|
51
115
|
# License
|
|
52
116
|
|
|
@@ -62,4 +126,4 @@ Unless required by applicable law or agreed to in writing, software
|
|
|
62
126
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
63
127
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
64
128
|
See the License for the specific language governing permissions and
|
|
65
|
-
limitations under the License.
|
|
129
|
+
limitations under the License.
|
package/dist/BrazeKit.common.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mparticle/web-braze-kit-3",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.2.0",
|
|
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",
|
|
@@ -29,6 +29,7 @@
|
|
|
29
29
|
"rollup": "^1.13.1",
|
|
30
30
|
"rollup-plugin-commonjs": "^10.0.0",
|
|
31
31
|
"rollup-plugin-node-resolve": "^5.0.1",
|
|
32
|
+
"rollup-plugin-replace": "^2.2.0",
|
|
32
33
|
"shelljs": "^0.8.4",
|
|
33
34
|
"should": "^7.1.0",
|
|
34
35
|
"watchify": "^3.11.1"
|