@mparticle/web-braze-kit 3.0.3 → 4.0.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.
Files changed (4) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +45 -26
  3. package/dist/BrazeKit.common.js +537 -369
  4. package/package.json +5 -5
package/CHANGELOG.md CHANGED
@@ -2,6 +2,16 @@
2
2
 
3
3
  --
4
4
 
5
+ ## 4.0.0 - 2022-10-19
6
+
7
+ ⚠️ **Breaking** - The mParticle web Braze kit now supports Braze's Web SDK V4.2.1.
8
+ * Our partner, Braze, has made significant changes to their web SDK. As a result, we are also updating our mParticle Braze web kit to support Braze’s Web SDK version 4.2.1. The updated mParticle Braze Web kit will be available via CDN on Feb 15, 2023 and is currently available on npm at @mparticle/web-braze-kit v4.0.0.
9
+ * There are lots of breaking changes, most notably Braze deprecating the entire `appboy` namespace in favor of `braze`, so please proceed with caution when updating to v4.0.0 via NPM. If you implement mParticle via snippet, you will have to make changes to your codebase before Feb 15, 2023 to be compatible with both version 3 and version 4 of the Braze SDK to ensure your code continues to work.
10
+ * Full details about the changes and recommended code changes can be found on mParticle's [Braze integration docs page](https://docs.mparticle.com/integrations/braze/event).
11
+
12
+ #### 3.0.4 - 2022-09-06
13
+ - fix: Add Transaction Id to Purchase Commerce Events
14
+
5
15
  #### 3.0.3 - 2022-08-24
6
16
  - feat: Add logging for debugging
7
17
 
package/README.md CHANGED
@@ -1,50 +1,69 @@
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
3
  ⚠️⚠️⚠️
4
- # Notice! Timeline for Breaking Changes for mParticle Web Braze Kit- 3/28/2022 - 6/14/2022
5
- This repository renames and replaces our [mParticle Appboy Web Kit](https://github.com/mparticle-integrations/mparticle-javascript-integration-appboy), which will be archived in the future.
4
+ # Notice! Timeline for Breaking Changes for mParticle Web Braze Kit- 10/15/2022 - 2/15/2023
5
+ Customers who use mParticle and Braze on their websites may require some code changes due to an update we are making to the mParticle Braze web kit. The web kit, which previously used v3.5.0 of the Braze web SDK, will use Braze SDK 4.2.1 starting on 2/15/2023 on our CDN.
6
6
 
7
- Braze has breaking changes between version 2.5.2 and 3.5.0 of their SDK. As a result, we too are updating our [mParticle Braze web kit](https://github.com/mparticle-integrations/mparticle-javascript-integration-appboy) to support Braze’s Web SDK version 3.5.0. The updated mParticle Braze Web kit will be available via CDN on June 14, 2022 and is currently available on NPM as [@mparticle/web-braze-kit](https://www.npmjs.com/package/@mparticle/web-braze-kit) v3.0.1.
7
+ * <b>The Braze web SDK has several breaking changes and if you load mParticle via snippet/CDN, you should <a href="#update-to-braze-sdk-version-4-from-version-3---10152022---2152023">follow these instructions to ensure your code continues to work when our changes go live to the CDN on 2/15/2023</a>. If you self-host mParticle and the Braze Web Kit via npm, you can update sooner. Follow the instructions below whether you self-host or load mParticle via snippet/CDN.</b>.
8
+ * <b>Note that if you are here looking at source code, the `master` branch will continue to contain Braze Web Kit version 3.X until 2/15/2023. The `braze-v4-npm-master` branch currently contains the source code for v4.X, and this will be merged to `master` on 2/15/2023 to be available via CDN. </b>
9
+ * If you are using version 2 of the @mparticle/web-appboy-kit, you will need to <a href="#transition-from-mparticleweb-appboy-kit-to-mparticleweb-braze-kit">transition to @mparticle/web-braze-kit per the instructions here</a> before following the below instructions as well.
8
10
 
9
- **How do you know if your code is affected?**
11
+ ## Braze Web Kit Citical Updates and Timelines
10
12
 
11
- You may notice errors on your site if you load mParticle [via snippet](https://docs.mparticle.com/developers/sdk/web/getting-started/#add-the-sdk-snippet) (as most of our clients do), and you reference any deprecated Braze APIs starting 6/14/2022.
13
+ Braze occasionally makes breaking changes to their SDK, so if you call Braze directly in your code, you may have to update your code to ensure your website performs as expected after mParticle updates to the latest Braze SDKs. This section communicates migration steps for customers to make to their codebase to ensure compatibility.
12
14
 
13
- We highly recommend that you review the changes between version 2 and 3 of the Braze Web SDK to understand these changes, which can be found [here](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/changelog/#300). To summarize:
14
- * The `appboy.ab` namespace has been removed and everything lives under the `appboy` namespace now.
15
- * `InAppMessage.Button` has been renamed to `InAppMessageButton`
15
+ Customers who implement mParticle via NPM and self-host our SDK can choose when they want to update their code and [@mParticle/web-braze-kit version](https://www.npmjs.com/package/@mparticle/web-braze-kit), but customers who implement mParticle via our snippet/CDN must pay close attention to the following timelines and instructions.
16
16
 
17
- If you reference any of the above deprecations, you will have to makes changes to your codebase before June 14, 2022 to be compatible with both version 2 and version 3 of the Braze SDK to ensure your code continues to work. We recommend a 3 step approach. Here are some code samples of what this code could look like today (step 1), preparing for the update (step 2) and after the change is live (step 3).
17
+ | mParticle Braze Web Kit Version | Braze SDK Version Supported | Deadline/Date of CDN Release | Link to Description |
18
+ | ---|---|---|---|
19
+ | v4.0.0 | v4.2.1 | 2/15/2023 | [Link](#update-to-braze-sdk-version-4-from-version-3---10152022---2152023) |
20
+ | v3.0.4 | v3.5.0 | NA | [Link](#transition-from-mparticleweb-appboy-kit-to-mparticleweb-braze-kit) |
18
21
 
19
- The below recommendations apply only to customers who load mParticle [via snippet](https://docs.mparticle.com/developers/sdk/web/getting-started/#add-the-sdk-snippet). Customers who [self host via NPM](https://docs.mparticle.com/developers/sdk/web/self-hosting/) can ignore step 1 and jump straight to step 3 after updating their mParticle Braze kit to v3.0.1.
22
+ ### Update to Braze SDK Version 4 from Version 3 - 10/15/2022 - 2/15/2023
20
23
 
21
- Step 1: Legacy code sample. If your code references the `ab` namespace (like below) or `InAppMessage.Button`, you should change it following Step 2’s example:
24
+ Please review [Braze’s Changelog notes](https://www.braze.com/docs/developer_guide/platform_integration_guides/web/changelog#400) as well as Braze’s [migration guide](https://github.com/braze-inc/braze-web-sdk/blob/master/UPGRADE_GUIDE.md) between version 3 and 4 to understand these changes and what code updates are needed from your side. The largest change is the move from class name `appboy` to `braze`. Braze also removed and renamed some APIs. As a result, we are also updating our mParticle Braze web kit from 3.0.X to 4.0.X in order to support Braze’s Web SDK version 4.2.1.
25
+
26
+ We plan to release the updated mParticle Braze Kit on two different time frames depending on how you load mParticle:
27
+ * Customers who self-host mParticle via npm - You will be able to update manually from npm on 10/15/2022
28
+ * Customers who load mParticle via snippet/CDN - We will push an update to the CDN on 2/15/2023 to make it automatically available.
29
+
30
+ We want to allow our customers to take advantage of the latest from Braze, so we are releasing the kit update via npm earlier. However, due to the sensitive nature of the breaking changes in Braze’s latest version, we want to give ample notice to all of our customers who are on the CDN since these customers will get the update automatically. We want to respect the end-of-year code freezes that a lot of our customers have and allow plenty of time to make the required code changes. Striking this balance is important for us, so if you are on the CDN but need the update sooner, you can [switch to self-hosting on npm](https://docs.mparticle.com/developers/sdk/web/self-hosting/).
31
+
32
+ If you load mParticle via snippet/CDN, you will have to make changes to your codebase before February 15, 2023 to be compatible with both version 3 and version 4 of the Braze SDK to ensure your code continues to work. We recommend a three-step approach. Here are some code samples of what this code could look like today (step 1), preparing for the update (step 2) and after the change is live (step 3).
33
+
34
+ The following recommendations apply only to customers who load mParticle via snippet. Customers who self-host via npm can ignore step 1 and jump straight to step 3 after updating their mParticle Braze kit. Note that this is only one example. Everywhere you manually call `appboy` needs to be updated similar to the below, and please refer to the Braze Changelog and migration guide as referenced earlier:
35
+
36
+ * 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:
22
37
  ```javascript
23
- let banner = new appboy.ab.Banner(‘test’);
38
+ window.appboy.display.destroyFeed();
24
39
  ```
25
40
 
26
- Step 2: Rollout code sample to be used before June 14, 2022:
41
+ Step 2: Roll out code changes to be used before February 15, 2023:
27
42
  ```javascript
28
- let banner;
29
- if (appboy.hasOwnProperty(‘ab’)) {
30
- banner = new appboy.ab.Banner(‘test’);
31
- } else {
32
- banner = new appboy.Banner(‘test’);
43
+ if (window.appboy) {
44
+ window.appboy.display.destroyFeed();
45
+ } else if (window.braze) {
46
+ window.braze.destroyFeed();
33
47
  }
34
48
  ```
35
- Step 3: After June 14, 2022, you can simplify your code to the following once the mParticle Braze Web kit has been released to our CDN:
49
+ Step 3: After February 1, 2023, you can simplify your code after the mParticle Braze Web kit, which includes Braze SDK V4, has been released to our CDN:
36
50
  ```javascript
37
- let banner = new appboy.Banner(‘test’);
51
+ window.braze.destroyFeed();
38
52
  ```
39
53
 
40
- **Push Notifications via service-worker.js**
41
-
42
- Additionally, if you are using 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 to ensure future compatibility. In your `service-worker.js` file, update the code to reference `https://static.mparticle.com/sdk/js/braze/service-worker-3.5.0.js` instead of `https://static.mparticle.com/sdk/js/braze/service-worker.js`, ie:
54
+ Step 4: Push Notifications via service-worker.js
55
+ 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:
43
56
 
44
57
  ```javascript
45
- self.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker-3.5.0.js');
58
+ self.imports('https://static.mparticle.com/sdk/js/braze/service-worker-4.2.0.js')
46
59
  ```
47
60
 
61
+ ### Transition from @mparticle/web-appboy-kit to @mparticle/web-braze-kit
62
+
63
+ 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.
64
+
65
+
66
+
48
67
  # License
49
68
 
50
69
  Copyright 2022 mParticle, Inc.
@@ -59,4 +78,4 @@ Unless required by applicable law or agreed to in writing, software
59
78
  distributed under the License is distributed on an "AS IS" BASIS,
60
79
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
61
80
  See the License for the specific language governing permissions and
62
- limitations under the License.
81
+ limitations under the License.