@braze/web-sdk 3.4.1 → 3.5.0

package/index.d.ts

@@ -1,7 +1,7 @@
 /*
-* Type definitions for appboy-web-sdk v3.4.1
+* Type definitions for appboy-web-sdk v3.5.0
 * Project: https://github.com/Appboy/appboy-web-sdk
-* (c) Braze, Inc. 2021 - http://braze.com
+* (c) Braze, Inc. 2022 - http://braze.com
 * License available at https://github.com/Appboy/appboy-web-sdk/blob/master/LICENSE
 */
 
@@ -30,6 +30,29 @@ declare namespace appboy {
     static readonly USER_AGENT: string;
   }
 
+  /**
+   * Enum to represent the accepted SDK Metadata tags. See `appboy.addSdkMetadata` for more info.
+   *
+   * @readonly
+   * @enum {string}
+   */
+  class BrazeSdkMetadata {
+    /** Use this tag if you have integrated the Braze Web SDK using Google Tag Manager */
+    static readonly GOOGLE_TAG_MANAGER: string;
+    /** Use this tag if you have integrated the Braze Web SDK using mParticle */
+    static readonly MPARTICLE: string;
+    /** Use this tag if you have integrated the Braze Web SDK using Segment */
+    static readonly SEGMENT: string;
+    /** Use this tag if you have integrated the Braze Web SDK using Tealium */
+    static readonly TEALIUM: string;
+    /** Use this tag if you have imported the Braze Web SDK using npm */
+    static readonly NPM: string;
+    /** Use this tag if you have loaded the Braze Web SDK using Braze's CDN (js.appboycdn.com) */
+    static readonly CDN: string;
+    /** Use this tag if you have integrated or loaded the Braze Web SDK using none of the other methods */
+    static readonly MANUAL: string;
+  }
+
   /**
    * Abstract base for news feed cards. Use subclasses `ClassicCard`, `CaptionedImage`,
    *   `Banner`, and `ControlCard`.
@@ -37,8 +60,10 @@ declare namespace appboy {
   class Card {
     /**
      * Call this method if you wish to programmatically remove the card from the feed and log a dismissal. This method
-     *   is meant to be used with the Braze UI. If you are using your own UI, you should use `appboy.logCardDismissal`
-     *   to log analytics.
+     *   is meant to be used with the Braze UI.
+     *
+     * If you are using your own UI, this method will have no effect. Instead, you should use `logCardDismissal` to
+     *   log analytics and then remove the card from the DOM manually.
      */
     dismissCard(): void;
 
@@ -94,6 +119,8 @@ declare namespace appboy {
 
     /** Whether to pin this card to the top of the view. */
     pinned: boolean;
+
+    static fromContentCardsJson(jsonData: Record<string, unknown>): Card | undefined;
   }
 
   class Banner extends Card {
@@ -111,7 +138,7 @@ declare namespace appboy {
      * @param expiresAt - When this card expires and should stop being shown to the user.
      * @param url - A url to open when this card is clicked.
      * @param linkText - The display text for the url.
-     * @param aspectRatio - The aspect ratio for this card's image.
+     * @param aspectRatio - The aspect ratio for this card's image. This field is meant to serve as a hint before image loading completes. Note that the field may not be supplied in certain circumstances.
      * @param extras - Object of string/string key/value pairs.
      * @param pinned - Whether to pin this card to the top of the view.
      * @param dismissible - Whether to allow the user to dismiss this card, removing it from the view.
@@ -152,7 +179,7 @@ declare namespace appboy {
     /** The display text for the url. */
     linkText?: string;
 
-    /** The aspect ratio for this card's image. */
+    /** The aspect ratio for this card's image. This field is meant to serve as a hint before image loading completes. Note that the field may not be supplied in certain circumstances. */
     aspectRatio: number | null;
 
     /** Whether this card has been dismissed. */
@@ -182,7 +209,7 @@ declare namespace appboy {
      * @param expiresAt - When this card expires and should stop being shown to the user.
      * @param url - A url to open when this card is clicked.
      * @param linkText - The display text for the url.
-     * @param aspectRatio - The aspect ratio for this card's image.
+     * @param aspectRatio - The aspect ratio for this card's image. This field is meant to serve as a hint before image loading completes. Note that the field may not be supplied in certain circumstances.
      * @param extras - Object of string/string key/value pairs.
      * @param pinned - Whether to pin this card to the top of the view.
      * @param dismissible - Whether to allow the user to dismiss this card, removing it from the view.
@@ -231,7 +258,7 @@ declare namespace appboy {
     /** The display text for the url. */
     linkText?: string;
 
-    /** The aspect ratio for this card's image. */
+    /** The aspect ratio for this card's image. This field is meant to serve as a hint before image loading completes. Note that the field may not be supplied in certain circumstances. */
     aspectRatio: number | null;
 
     /** Whether this card has been dismissed. */
@@ -262,7 +289,7 @@ declare namespace appboy {
      * @param expiresAt - When this card expires and should stop being shown to the user.
      * @param url - A url to open when this card is clicked.
      * @param linkText - The display text for the url.
-     * @param aspectRatio - The aspect ratio for this card's image.
+     * @param aspectRatio - The aspect ratio for this card's image. This field is meant to serve as a hint before image loading completes. Note that the field may not be supplied in certain circumstances.
      * @param extras - Object of string/string key/value pairs.
      * @param pinned - Whether to pin this card to the top of the view.
      * @param dismissible - Whether to allow the user to dismiss this card, removing it from the view.
@@ -311,7 +338,7 @@ declare namespace appboy {
     /** The display text for the url. */
     linkText?: string;
 
-    /** The aspect ratio for this card's image. */
+    /** The aspect ratio for this card's image. This field is meant to serve as a hint before image loading completes. Note that the field may not be supplied in certain circumstances. */
     aspectRatio: number | null;
 
     /** Whether this card has been dismissed. */
@@ -1472,8 +1499,8 @@ declare namespace appboy {
 
   /**
    * appboy.display is the public class for the UI portions of Braze's Web SDK. It is only available in
-   *    `https://js.appboycdn.com/web-sdk-develop/3.4/appboy.min.js` and is stripped from the more minimal
-   *    `https://js.appboycdn.com/web-sdk-develop/3.4/appboy.core.min.js`.
+   *    `https://js.appboycdn.com/web-sdk-develop/3.5/appboy.min.js` and is stripped from the more minimal
+   *    `https://js.appboycdn.com/web-sdk-develop/3.5/appboy.core.min.js`.
    */
   namespace display {
     /**
@@ -1629,6 +1656,7 @@ declare namespace appboy {
    *    to target while logged out and switching back to that user ID as part of your app's logout process.
    *
    * @param userId - A unique identifier for this user. Limit 997 bytes.
+   *   These User IDs should be private and not easily guessable (e.g. not a plain email address or username).
    * @param signature - An encrypted signature to be used to authenticate the current user. You can update the signature
    *   using the `setSdkAuthenticationSignature` method. This signature will only have an effect if the `enableSdkAuthentication`
    *   initialization option is set to true.
@@ -1914,7 +1942,7 @@ declare namespace appboy {
    * - Create a `service-worker.js` file with the content below and place it in the root directory of your website:
    *
    * ```
-   * self.importScripts('https://js.appboycdn.com/web-sdk-develop/3.4/service-worker.js');
+   * self.importScripts('https://js.appboycdn.com/web-sdk-develop/3.5/service-worker.js');
    * ```
    *
    * For more details, see [Our Product Documentation](https://www.appboy.com/docs/developer_guide/platform_integration_guides/web/push_notifications/integration).
@@ -1983,11 +2011,21 @@ declare namespace appboy {
   ): void;
 
   /**
-   * Removes the cookie set by `stopWebTracking`, causing subsequent calls to the Braze Web SDK to function. You must
-   *    call `initialize` after calling this method before calling subsequent methods.
+   * @deprecated This method has been deprecated in favor of `enableSDK`, which has the same functionality.
    */
   function resumeWebTracking(): void;
 
+  /**
+   * Removes the cookie set by `disableSDK`, causing subsequent calls to the Braze Web SDK to function. You must
+   *    call `initialize` after calling this method before calling subsequent methods.
+   */
+  function enableSDK(): void;
+
+  /**
+   * Getter method to determine if the SDK is disabled based on whether the cookie set by `stopWebTracking` exists
+   */
+  function isDisabled(): boolean;
+
   /**
    * By default, Braze logs to the browser console. Call this method to set a custom log action and enable debug-level log statements.
    *
@@ -2006,13 +2044,27 @@ declare namespace appboy {
    */
   function setSdkAuthenticationSignature(signature: string): boolean;
 
+  /**
+   * Adds SDK Metadata, which you can use to self-report how you load and integrate the Braze SDK.
+   *
+   * @param sdkMetadata - An array of metadata values from `BrazeSdkMetadata`.
+   *
+   * @returns Whether or not the array of metadata is valid.
+   */
+  function addSdkMetadata(sdkMetadata: string[]): boolean;
+
+  /**
+   * @deprecated This method has been deprecated in favor of `disableSDK`, which has the same functionality.
+   */
+  function stopWebTracking(): void;
+
   /**
    * Sets a cookie that causes all subsequent calls to the Braze Web SDK to be ignored
    * and all subsequent analytics to cease being sent to the Braze backend.
    * If you have multiple subdomains, this method MUST be called from the same subdomain that push was registered from to work properly.
    * This is useful for customer opt-outs. If the customer clears website data, tracking will resume.
    */
-  function stopWebTracking(): void;
+  function disableSDK(): void;
 
   /**
    * Subscribe to content cards updates. The subscriber callback will be called whenever content cards are updated.
@@ -2245,7 +2297,7 @@ declare namespace appboy {
      *   lifecycle of, set this option to true and the Braze SDK will not register or unregister a service worker. If you set this
      *   option to true, in order for push to function correctly you must register the service worker yourself BEFORE calling
      *   `appboy.registerAppboyPushMessages`, and ensure that it contains Braze's service worker code, either with
-     *   `self.importScripts('https://js.appboycdn.com/web-sdk-develop/3.4/service-worker.js');` or by including the content
+     *   `self.importScripts('https://js.appboycdn.com/web-sdk-develop/3.5/service-worker.js');` or by including the content
      *   of that file directly. When this option is true, the `serviceWorkerLocation` option is irrelevant and is ignored.
      */
     manageServiceWorkerExternally?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braze/web-sdk",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Braze SDK for web sites and other JS platforms.",
   "main": "appboy.min.js",
   "scripts": {