@segment/analytics-browser-actions-braze 1.0.0

package/src/__tests__/trackEvent.test.ts

@@ -0,0 +1,65 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import brazeDestination, { destination } from '../index'
+const testSdkVersions = ['3.5', '4.1']
+
+testSdkVersions.forEach((sdkVersion) => {
+  describe(`trackEvent (v${sdkVersion})`, () => {
+    test('invokes braze`s logCustomEvent API', async () => {
+      const [trackEvent] = await brazeDestination({
+        api_key: 'b_123',
+        endpoint: 'endpoint',
+        sdkVersion,
+        doNotLoadFontAwesome: true,
+        subscriptions: [
+          {
+            partnerAction: 'trackEvent',
+            name: 'Log Custom Event',
+            enabled: true,
+            subscribe: 'type = "track"',
+            mapping: {
+              eventName: {
+                '@path': '$.event'
+              },
+              eventProperties: {
+                '@path': '$.properties'
+              }
+            }
+          }
+        ]
+      })
+
+      jest.spyOn(destination.actions.trackEvent, 'perform')
+      const initializeSpy = jest.spyOn(destination, 'initialize')
+
+      await trackEvent.load(Context.system(), new Analytics({ writeKey: '123' }))
+
+      // Spy on the braze APIs now that braze has been loaded.
+      const { instance: braze } = await initializeSpy.mock.results[0].value
+      const logCustomEventSpy = jest.spyOn(braze, 'logCustomEvent')
+
+      await trackEvent.track?.(
+        new Context({
+          type: 'track',
+          event: 'UFC',
+          properties: {
+            goat: 'hasbulla'
+          }
+        })
+      )
+
+      expect(destination.actions.trackEvent.perform).toHaveBeenCalledWith(
+        expect.objectContaining({
+          instance: expect.objectContaining({
+            logCustomEvent: expect.any(Function)
+          })
+        }),
+
+        expect.objectContaining({
+          payload: { eventName: 'UFC', eventProperties: { goat: 'hasbulla' } }
+        })
+      )
+
+      expect(logCustomEventSpy).toHaveBeenCalledWith('UFC', { goat: 'hasbulla' })
+    })
+  })
+})

package/src/__tests__/trackPurchase.test.ts

@@ -0,0 +1,65 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import brazeDestination, { destination } from '../index'
+
+const testSdkVersions = ['3.5', '4.1']
+
+testSdkVersions.forEach((sdkVersion) => {
+  test(`reports products when present (v${sdkVersion})`, async () => {
+    const initializeSpy = jest.spyOn(destination, 'initialize')
+
+    const [trackPurchase] = await brazeDestination({
+      api_key: 'b_123',
+      endpoint: 'endpoint',
+      sdkVersion,
+      doNotLoadFontAwesome: true,
+      subscriptions: [
+        {
+          partnerAction: 'trackPurchase',
+          name: 'Log Purchase',
+          enabled: true,
+          subscribe: 'type = "track"',
+          mapping: {
+            purchaseProperties: {
+              '@path': '$.properties'
+            },
+            products: {
+              '@path': '$.properties.products'
+            }
+          }
+        }
+      ]
+    })
+
+    await trackPurchase.load(Context.system(), new Analytics({ writeKey: '123' }))
+
+    // Spy on the braze APIs now that braze has been loaded.
+    const { instance: braze } = await initializeSpy.mock.results[0].value
+    const brazeLogPurchase = jest.spyOn(braze, 'logPurchase').mockReturnValue(true)
+
+    await trackPurchase.track?.(
+      new Context({
+        type: 'track',
+        properties: {
+          banana: 'yellow',
+          products: [
+            {
+              product_id: 'p_123',
+              price: 399,
+              currency: 'BGP',
+              quantity: 2
+            },
+            {
+              product_id: 'p_456',
+              price: 0
+            }
+          ]
+        }
+      })
+    )
+
+    expect(brazeLogPurchase.mock.calls[0]).toMatchSnapshot()
+
+    // applying defaults
+    expect(brazeLogPurchase.mock.calls[1]).toMatchSnapshot()
+  })
+})

package/src/__tests__/updateUserProfile.test.ts

@@ -0,0 +1,145 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import brazeDestination, { destination } from '../index'
+
+describe('updateUserProfile', () => {
+  const subscriptions = [
+    {
+      partnerAction: 'updateUserProfile',
+      name: 'Update User Profile',
+      enabled: true,
+      subscribe: 'type = "identify"',
+      mapping: {
+        country: { '@path': '$.traits.country' },
+        current_location: { '@path': '$.traits.current_location' },
+        custom_attributes: { '@path': '$.traits.custom_attributes' },
+        dob: { '@path': '$.traits.dob' },
+        email: { '@path': '$.traits.email' },
+        email_subscribe: { '@path': '$.traits.email_subscribe' },
+        first_name: { '@path': '$.traits.first_name' },
+        gender: { '@path': '$.traits.gender' },
+        home_city: { '@path': '$.traits.home_city' },
+        image_url: { '@path': '$.traits.image_url' },
+        language: { '@path': '$.traits.language' },
+        last_name: { '@path': '$.traits.last_name' },
+        phone: { '@path': '$.traits.phone' },
+        push_subscribe: { '@path': '$.traits.push_subscribe' }
+      }
+    }
+  ]
+
+  beforeEach(async () => {
+    destination.actions.updateUserProfile.perform = jest.fn()
+    jest.spyOn(destination.actions.trackEvent, 'perform')
+    jest.spyOn(destination, 'initialize')
+  })
+
+  test('changes the external_id when present', async () => {
+    const [event] = await brazeDestination({
+      api_key: 'b_123',
+      endpoint: 'endpoint',
+      sdkVersion: '3.5',
+      doNotLoadFontAwesome: true,
+      subscriptions: [
+        {
+          partnerAction: 'updateUserProfile',
+          name: 'Log User',
+          enabled: true,
+          subscribe: 'type = "identify"',
+          mapping: {
+            external_id: {
+              '@path': '$.traits.external_id'
+            }
+          }
+        }
+      ]
+    })
+
+    await event.load(Context.system(), new Analytics({ writeKey: '123' }))
+    await event.identify?.(
+      new Context({
+        type: 'identify',
+        traits: {
+          external_id: 'xt_123'
+        }
+      })
+    )
+
+    expect(destination.actions.updateUserProfile.perform).toHaveBeenCalledWith(
+      expect.objectContaining({
+        instance: expect.objectContaining({
+          changeUser: expect.any(Function)
+        })
+      }),
+
+      expect.objectContaining({
+        payload: { external_id: 'xt_123' }
+      })
+    )
+  })
+
+  test('can change user traits', async () => {
+    const [event] = await brazeDestination({
+      api_key: 'b_123',
+      endpoint: 'endpoint',
+      sdkVersion: '3.5',
+      doNotLoadFontAwesome: true,
+      subscriptions
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+    await event.identify?.(
+      new Context({
+        type: 'identify',
+        traits: {
+          external_id: 'xt_123',
+          country: 'BRA',
+          current_location: {
+            latitude: -23.54,
+            longitude: -46.65
+          },
+          custom_attributes: {
+            greeting: 'oi'
+          },
+          dob: '01/01/2000',
+          email: 'foo@example.org',
+          email_subscribe: true,
+          first_name: 'Foo',
+          gender: 'M',
+          home_city: 'Miami',
+          image_url: 'img_url',
+          language: 'english',
+          last_name: 'Bar',
+          phone: '555 5555',
+          push_subscribe: true
+        }
+      })
+    )
+
+    expect(destination.actions.updateUserProfile.perform).toHaveBeenCalledWith(
+      expect.objectContaining({
+        instance: expect.objectContaining({
+          changeUser: expect.any(Function)
+        })
+      }),
+
+      expect.objectContaining({
+        payload: {
+          country: 'BRA',
+          current_location: { latitude: -23.54, longitude: -46.65 },
+          custom_attributes: { greeting: 'oi' },
+          dob: '01/01/2000',
+          email: 'foo@example.org',
+          email_subscribe: true,
+          first_name: 'Foo',
+          gender: 'M',
+          home_city: 'Miami',
+          image_url: 'img_url',
+          language: 'english',
+          last_name: 'Bar',
+          phone: '555 5555',
+          push_subscribe: true
+        }
+      })
+    )
+  })
+})

package/src/braze-types.ts

@@ -0,0 +1,9 @@
+import type braze from '@braze/web-sdk'
+import type appboy from '@braze/web-sdk-v3'
+
+export type BrazeType = typeof braze | typeof appboy
+
+export type BrazeDestinationClient = {
+  instance: BrazeType
+  ready: () => boolean
+}

package/src/debounce/generated-types.ts

@@ -0,0 +1,3 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {}

package/src/debounce/index.ts

@@ -0,0 +1,67 @@
+import { BrazeDestinationClient } from '../braze-types'
+import type { ID, SegmentEvent, User } from '@segment/analytics-next'
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+
+type CachedUser = {
+  id: ID
+  anonymousId: ID
+  traits: ReturnType<User['traits']> | null
+}
+
+let cachedUser: CachedUser = {
+  id: undefined,
+  anonymousId: undefined,
+  traits: null
+}
+
+export function resetUserCache() {
+  cachedUser = {
+    id: undefined,
+    anonymousId: undefined,
+    traits: null
+  }
+}
+
+function shouldSendToBraze(event: SegmentEvent) {
+  if (event.userId && event.userId !== cachedUser.id) {
+    return true
+  }
+
+  if (event.anonymousId && event.anonymousId !== cachedUser.anonymousId) {
+    return true
+  }
+
+  const traits = event.traits ?? {}
+  return JSON.stringify(cachedUser.traits) !== JSON.stringify(traits)
+}
+
+const action: BrowserActionDefinition<Settings, BrazeDestinationClient, Payload> = {
+  title: 'Debounce Middleware',
+  description:
+    'When enabled, it ensures that only events where at least one changed trait value are sent to Braze, and events with duplicate traits are not sent. Debounce functionality requires a frontend client to work. Therefore, it cannot be used with server-side libraries or with Engage.',
+  platform: 'web',
+  defaultSubscription: 'type = "identify" or type = "group"',
+  fields: {},
+  lifecycleHook: 'before',
+  perform: (_client, data) => {
+    const event = data.context.event
+    const analyticsUser = data.analytics.user()
+    const ctx = data.context
+
+    // Only send the event to Braze if a trait has changed
+    // Target all possible Braze integration names
+    const shouldSend = shouldSendToBraze(event)
+    ctx.updateEvent('integrations.Braze Web Mode (Actions)', shouldSend)
+    ctx.updateEvent('integrations.Braze Cloud Mode (Actions)', shouldSend)
+    ctx.updateEvent('integrations.Appboy', shouldSend)
+
+    // Ensure analytics.user is defined
+    cachedUser.id = analyticsUser.id()
+    cachedUser.anonymousId = analyticsUser.anonymousId()
+    cachedUser.traits = analyticsUser.traits()
+  }
+}
+
+export default action

package/src/generated-types.ts

@@ -0,0 +1,104 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * The version of the Braze SDK to use
+   */
+  sdkVersion: string
+  /**
+   * Found in the Braze Dashboard under Manage Settings → Apps → Web
+   */
+  api_key: string
+  /**
+   * Your Braze SDK endpoint. [See more details](https://www.braze.com/docs/user_guide/administrative/access_braze/sdk_endpoints/)
+   */
+  endpoint: string
+  /**
+   * Allow Braze to log activity from crawlers. [See more details](https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)
+   */
+  allowCrawlerActivity?: boolean
+  /**
+   * To indicate that you trust the Braze dashboard users to write non-malicious Javascript click actions, set this property to true. If enableHtmlInAppMessages is true, this option will also be set to true. [See more details](https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)
+   */
+  allowUserSuppliedJavascript?: boolean
+  /**
+   * If enabled, this setting delays initialization of the Braze SDK until the user has been identified. When enabled, events for anonymous users will no longer be sent to Braze.
+   */
+  deferUntilIdentified?: boolean
+  /**
+   * Version to which user events sent to Braze will be associated with. [See more details](https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)
+   */
+  appVersion?: string
+  /**
+   * Allows Braze to add the nonce to any <script> and <style> elements created by the SDK. [See more details](https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)
+   */
+  contentSecurityNonce?: string
+  /**
+   * By default, the Braze SDK automatically detects and collects all device properties in DeviceProperties. To override this behavior, provide an array of DeviceProperties. [See more details](https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)
+   */
+  devicePropertyAllowlist?: string[]
+  /**
+   * By default, users who have already granted web push permission will sync their push token with the Braze backend automatically on new session to ensure deliverability. To disable this behavior, set this option to true
+   */
+  disablePushTokenMaintenance?: boolean
+  /**
+   * Braze automatically loads FontAwesome 4.7.0 from the FontAwesome CDN. To disable this behavior set this option to true.
+   */
+  doNotLoadFontAwesome?: boolean
+  /**
+   * Set to true to enable logging by default
+   */
+  enableLogging?: boolean
+  /**
+   * Set to true to enable the SDK Authentication feature.
+   */
+  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.
+   */
+  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 ISO 639-1 Language Code.
+   */
+  localization?: string
+  /**
+   * When this is enabled, all In-App Messages that a user is eligible for are automatically delivered to the user. If you'd like to register your own display subscribers or send soft push notifications to your users, make sure to disable this option.
+   */
+  automaticallyDisplayMessages?: boolean
+  /**
+   * If you have your own service worker that you register and control the lifecycle of, set this option to true and the Braze SDK will not register or unregister a service worker. [See more details](https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)
+   */
+  manageServiceWorkerExternally?: boolean
+  /**
+   * Provide a value to override the default interval between trigger actions with a value of your own. [See more details](https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)
+   */
+  minimumIntervalBetweenTriggerActionsInSeconds?: number
+  /**
+   * By default, the Braze SDK will store small amounts of data (user ids, session ids), in cookies. Pass true for this option to disable cookie storage and rely entirely on HTML 5 localStorage to identify users and sessions. [See more details](https://js.appboycdn.com/web-sdk/latest/doc/modules/appboy.html#initializationoptions)
+   */
+  noCookies?: boolean
+  /**
+   * By default, links from Card objects load in the current tab or window. Set this option to true to make links from cards open in a new tab or window.
+   */
+  openCardsInNewTab?: boolean
+  /**
+   * By default, links from in-app message clicks load in the current tab or a new tab as specified in the dashboard on a message-by-message basis. Set this option to true to force all links from in-app message clicks open in a new tab or window.
+   */
+  openInAppMessagesInNewTab?: boolean
+  /**
+   * By default, when an in-app message is showing, pressing the escape button or a click on the greyed-out background of the page will dismiss the message. Set this option to true to prevent this behavior and require an explicit button click to dismiss messages.
+   */
+  requireExplicitInAppMessageDismissal?: boolean
+  /**
+   * If you support Safari push, you must specify this option with the website push ID that you provided to Apple when creating your Safari push certificate (starts with "web", e.g. "web.com.example.domain").
+   */
+  safariWebsitePushId?: string
+  /**
+   * By default, when registering users for web push notifications Braze will look for the required service worker file in the root directory of your web server at /service-worker.js. If you want to host your service worker at a different path on that server, provide a value for this option that is the absolute path to the file, e.g. /mycustompath/my-worker.js. VERY IMPORTANT: setting a value here limits the scope of push notifications on your site. For instance, in the above example, because the service  ,worker file is located within the /mycustompath/ directory, appboy.registerAppboyPushMessages MAY ONLY BE CALLED from web pages that start with http://yoursite.com/mycustompath/.
+   */
+  serviceWorkerLocation?: string
+  /**
+   * By default, sessions time out after 30 minutes of inactivity. Provide a value for this configuration option to override that default with a value of your own.
+   */
+  sessionTimeoutInSeconds?: number
+}