@braze/web-sdk 3.2.0 → 3.5.0

package/index.d.ts

@@ -1,7 +1,7 @@
 /*
-* Type definitions for appboy-web-sdk v3.2.0
+* 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,12 +30,41 @@ 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`.
    */
   class Card {
-    /** Call this method if you wish to dismiss this card programmatically. */
+    /**
+     * 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, 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;
 
     /** Remove all event subscriptions from this message. */
@@ -90,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 {
@@ -107,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.
@@ -123,7 +154,7 @@ declare namespace appboy {
       expiresAt?: Date,
       url?: string,
       linkText?: string,
-      aspectRatio?: string,
+      aspectRatio?: number,
       extras?: Record<string, any>,
       pinned?: boolean,
       dismissible?: boolean,
@@ -148,8 +179,11 @@ declare namespace appboy {
     /** The display text for the url. */
     linkText?: string;
 
-    /** The aspect ratio for this card's image. */
-    aspectRatio: string | null;
+    /** 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. */
+    dismissed: boolean;
 
     /** Whether to allow the user to dismiss this card, removing it from the view. */
     dismissible: boolean;
@@ -175,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.
@@ -193,7 +227,7 @@ declare namespace appboy {
       expiresAt?: Date,
       url?: string,
       linkText?: string,
-      aspectRatio?: string,
+      aspectRatio?: number,
       extras?: Record<string, any>,
       pinned?: boolean,
       dismissible?: boolean,
@@ -224,8 +258,11 @@ declare namespace appboy {
     /** The display text for the url. */
     linkText?: string;
 
-    /** The aspect ratio for this card's image. */
-    aspectRatio: string | null;
+    /** 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. */
+    dismissed: boolean;
 
     /** Whether to allow the user to dismiss this card, removing it from the view. */
     dismissible: boolean;
@@ -252,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.
@@ -270,7 +307,7 @@ declare namespace appboy {
       expiresAt?: Date,
       url?: string,
       linkText?: string,
-      aspectRatio?: string,
+      aspectRatio?: number,
       extras?: Record<string, any>,
       pinned?: boolean,
       dismissible?: boolean,
@@ -301,8 +338,11 @@ declare namespace appboy {
     /** The display text for the url. */
     linkText?: string;
 
-    /** The aspect ratio for this card's image. */
-    aspectRatio: string | null;
+    /** 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. */
+    dismissed: boolean;
 
     /** Whether to allow the user to dismiss this card, removing it from the view. */
     dismissible: boolean;
@@ -359,6 +399,7 @@ declare namespace appboy {
 
     /**
      * Get the current unviewed card count. This is useful for powering badges on your control for showing the content cards.
+     *    `ControlCard` cards do not count towards the unviewed count.
      */
     getUnviewedCardCount(): number;
   }
@@ -391,7 +432,8 @@ declare namespace appboy {
     /**
      * Get the current unread card count. This is useful for powering badges on your control for showing the news feed.
      *    Note that Braze will not refresh news feed cards on new page loads (and so this function will return 0) until you
-     *    call `display.showFeed` or `appboy.requestFeedRefresh`.
+     *    call `display.showFeed` or `appboy.requestFeedRefresh`. `ControlCard` cards do not count towards the
+     *    unread count.
      */
     getUnreadCardCount(): number;
   }
@@ -434,7 +476,7 @@ declare namespace appboy {
 
   /**
    *  Abstract base for in-app messages. Use subclasses `SlideUpMessage`,
-   *    `ModalMessage` and `FullScreenMessage`.
+   *    `ModalMessage`, `FullScreenMessage`, and `HtmlMessage`.
    */
   class InAppMessage {
     static SlideFrom: {
@@ -526,7 +568,10 @@ declare namespace appboy {
      */
     css?: string;
 
-    /** Call this method if you wish to dismiss this in-app message programmatically. */
+    /**
+     * Call this method if you wish to programmatically remove the message from the DOM. This method will only
+     *   work with the Braze UI.
+     */
     closeMessage(): void;
 
     /** Remove all event subscriptions from this message. */
@@ -563,6 +608,8 @@ declare namespace appboy {
      *    to cancel the subscription.
      */
     subscribeToDismissedEvent(subscriber: () => void): string;
+
+    static fromJson(jsonData: Record<string, unknown>): InAppMessage | undefined;
   }
 
   class FullScreenMessage extends InAppMessage {
@@ -1119,6 +1166,15 @@ declare namespace appboy {
      */
     addToCustomAttributeArray(key: string, value: string): boolean;
 
+    /**
+     * Adds a user to an email or SMS subscription group.
+     *
+     * @param subscriptionGroupId - The unique identifier of the subscription group.
+     *
+     * @returns Whether the update was successfully enqueued.
+     */
+    addToSubscriptionGroup(subscriptionGroupId: string): boolean;
+
     /**
      * Asynchronously retrieves the current user's id, or null if the user is anonymous / has not been identified.
      * For example:
@@ -1160,6 +1216,15 @@ declare namespace appboy {
      */
     removeFromCustomAttributeArray(key: string, value: string): boolean;
 
+    /**
+     * Removes a user from an email or SMS subscription group.
+     *
+     * @param subscriptionGroupId - The unique identifier of the subscription group.
+     *
+     * @returns Whether the update was successfully enqueued.
+     */
+     removeFromSubscriptionGroup(subscriptionGroupId: string): boolean;
+
     /**
      * Sets the url for the avatar image for the user, which will be displayed on the user profile
      * and throughout the Braze dashboard.
@@ -1177,7 +1242,7 @@ declare namespace appboy {
      *
      * @returns Whether the update was successfully enqueued.
      */
-    setCountry(country: string): boolean;
+    setCountry(country: string | null): boolean;
 
     /**
      * Sets a custom user location attribute.
@@ -1434,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.2/appboy.min.js` and is stripped from the more minimal
-   *    `https://js.appboycdn.com/web-sdk-develop/3.2/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 {
     /**
@@ -1591,8 +1656,12 @@ 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.
    */
-  function changeUser(userId: string): void;
+  function changeUser(userId: string, signature?: string): void;
 
   /**
    * Destroys this appboy instance, destroying all subscription callbacks and releasing member variables which
@@ -1728,7 +1797,7 @@ declare namespace appboy {
    * @returns Whether or not the event was successfully logged (to be flushed later).
    */
   function logCardImpressions(
-    card: appboy.Card[],
+    cards: appboy.Card[],
     forContentCards?: boolean
   ): boolean;
 
@@ -1746,9 +1815,10 @@ declare namespace appboy {
    *      useful for segmenting, instead of specific user actions (i.e. track watched_sports_video instead of
    *      watched_video_adrian_peterson_td_mnf). Value is limited to 255 characters in length, cannot begin with a $,
    *      and can only contain alphanumeric characters and punctuation.
-   * @param eventProperties - Hash of properties for this event. Keys are limited to 255
-   *      characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation.
-   *      Values can be numeric, boolean, Date objects, or strings 255 characters or shorter.
+   * @param eventProperties - Hash of properties for this event. Keys are limited to 255 characters in length, cannot begin
+   *      with a $, and can only contain alphanumeric characters and punctuation. Values can be numeric, boolean, Date objects,
+   *      strings 255 characters or shorter, or nested objects whose values can be numeric, boolean, Date objects, arrays, strings,
+   *      or null. Total size of event properties cannot exceed 50KB.
    *
    * @returns Whether or not the event was successfully logged (to be flushed later).
    */
@@ -1840,7 +1910,8 @@ declare namespace appboy {
    *      and at most 100.
    * @param purchaseProperties - Hash of properties for this purchase. Keys are limited to 255
    *      characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation.
-   *      Values can be numeric, boolean, Date objects, or strings 255 characters or shorter.
+   *      Values can be numeric, boolean, Date objects, strings 255 characters or shorter, or nested objects whose values
+   *      can be numeric, boolean, Date objects, arrays, strings, or null. Total size of purchase properties cannot exceed 50KB.
    *
    * @returns Whether or not the purchase was successfully attached to the session (to be flushed later).
    */
@@ -1871,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.2/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).
@@ -1908,8 +1979,13 @@ declare namespace appboy {
    * Requests an immediate refresh of content cards from Appboy servers. By default, content cards are refreshed when
    *    a new session opens (see  'openSession` for more details), and when the user refreshes content cards manually via
    *    the refresh button. If you want to refresh content cards from the server at another time you must call this function.
+   *
+   * @param successCallback - Callback that is invoked when the content cards refresh request has been successfully completed.
+   *   You should use `subscribeToContentCardsUpdates` to be notified of new cards. This callback is useful for determining when
+   *   a request has completed regardless of whether new cards were returned.
+   * @param errorCallback - Callback that is invoked when an error occurs during the refresh.
    */
-  function requestContentCardsRefresh(): void;
+  function requestContentCardsRefresh(successCallback?: () => void, errorCallback?: () => void): void;
 
   /**
    * Requests an immediate refresh of the news feed from Braze servers. By default, the news feed is refreshed on
@@ -1935,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.
    *
@@ -1948,22 +2034,46 @@ declare namespace appboy {
    */
   function setLogger(loggerFunction: (message: string) => void): void;
 
+  /**
+   * Sets the signature to be used to authenticate the current user. You can also set the signature when calling `changeUser`.
+   * This signature will only have an effect if the `enableSdkAuthentication` initialization option is set to true.
+   *
+   * @param signature - The signature to add to network requests to authenticate the current user.
+   *
+   * @returns Whether or not the signature is valid.
+   */
+  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.
    *
-   * @param subscriber - The callback function to handle new cards. This function will be
-   *    called with an `ContentCards` object which includes all currently available `Card` objects.
+   * @param subscriber - The callback function to handle new cards. This function will be called with a `ContentCards`
+   *   object which includes all currently available `Card` objects. If you want to be notified when a refresh has completed
+   *   regardless of whether new cards are available, you should use the `successCallback` of `requestContentCardsRefresh`.
    *
-   * @returns The identifier of the subscription created. This can be passed to
-   *    `removeSubscription` to cancel the subscription.
+   * @returns The identifier of the subscription created. This can be passed to `removeSubscription` to cancel the subscription.
    */
   function subscribeToContentCardsUpdates(
     subscriber: (cards: appboy.ContentCards) => void
@@ -2031,6 +2141,27 @@ declare namespace appboy {
     ) => void
   ): string;
 
+  /**
+   * Subscribe to be notified of network request failures that occured due to an SDK Authentication error. This
+   * method can be used to determine when to call `setSdkAuthenticationSignature` to provide the SDK with a new signature.
+   * If you do not have SDK Authentication enabled on the Braze dashboard, this subscription will never be invoked.
+   *
+   * @param subscriber - The subscriber function that is invoked whenever an SDK Authentication error occurs. It is
+   *   invoked with an object containing the `errorCode`, `reason` for the error, the `userId` of the request (if the
+   *   user is not anonymous), and the authentication `signature` that caused the error.
+   *
+   * @returns The identifier of the subscription created. This can be passed to
+   *    'removeSubscription` to cancel the subscription.
+   */
+  function subscribeToSdkAuthenticationFailures(subscriber: (
+    error: {
+      errorCode: string,
+      reason?: string,
+      userId?: string,
+      signature?: string
+    }
+  ) => void): string;
+
   /**
    * By default, Braze silences its logging to prevent spamming production js consoles. Call this method to
    *    toggle logging.
@@ -2041,6 +2172,9 @@ declare namespace appboy {
    * Causes the Braze Web SDK to begin continuously collecting the user's location while your website is visible in
    *    the foreground of their browser, for the duration of this page load. This will cause the browser to request
    *    permission from the user if they have not already granted or denied it.
+   *
+   * @deprecated This method has been deprecated in favor of using the native [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API)
+   *   and passing the location data to `User.setLastKnownLocation`.
    */
   function trackLocation(): void;
 
@@ -2128,6 +2262,8 @@ declare namespace appboy {
      * By default, the Braze Web SDK does not enable HTML in-app messages, as they allow Braze dashboard users to run Javascript
      *   on your site. To indicate that you trust the Braze dashboard users to write non-malicious HTML in-app messages, set this
      *   property to true. If `allowUserSuppliedJavascript` is set to true, this option will also be set to true.
+     *
+     * @deprecated This initialization option is deprecated in favor of `allowUserSuppliedJavascript`.
      */
     enableHtmlInAppMessages?: boolean;
     /**
@@ -2136,6 +2272,17 @@ declare namespace appboy {
      *   your page to production.
      */
     enableLogging?: boolean;
+    /**
+     * Set to true to enable the SDK Authentication feature. For more information about SDK Authentication, see our
+     * [Product Documentation](https://www.braze.com/docs/developer_guide/platform_wide/sdk_authentication/).
+     */
+    enableSdkAuthentication?: boolean
+    /**
+     * By default, the Braze SDK will show In-App Messages with a z-index of 1040 for the screen overlay, 1050 for the actual in-app message,
+     *   and 1060 for the message's close button. Provide a value for this option to override these default z-indexes. The value provided
+     *   will be used for the backdrop, `value + 1` will be used for the in-app message, and `value + 2` will be used for the close button.
+     */
+    inAppMessageZIndex?: number
     /**
      * By default, any SDK-generated user-visible messages will be displayed in the user's browser language. Provide a value for this
      *   option to override that behavior and force a specific language. The value for this option should be a
@@ -2150,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.2/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.2.0",
+  "version": "3.5.0",
   "description": "Braze SDK for web sites and other JS platforms.",
   "main": "appboy.min.js",
   "scripts": {