@segment/analytics-browser-actions-friendbuy 1.0.0

package/src/trackPage/__tests__/index.test.ts

@@ -0,0 +1,63 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import friendbuyDestination from '../../index'
+import trackPageObject, { trackPageDefaultSubscription, trackPageFields } from '../index'
+
+import { loadScript } from '@segment/browser-destination-runtime/load-script'
+jest.mock('@segment/browser-destination-runtime/load-script')
+beforeEach(async () => {
+  // Prevent friendbuy.js and campaigns.js from being loaded.
+  ;(loadScript as jest.Mock).mockResolvedValue(true)
+})
+
+describe('Friendbuy.trackPage', () => {
+  const subscriptions = [
+    {
+      partnerAction: 'trackPage',
+      name: trackPageObject.title,
+      enabled: true,
+      subscribe: trackPageDefaultSubscription,
+      mapping: Object.fromEntries(Object.entries(trackPageFields).map(([name, value]) => [name, value.default]))
+    }
+  ]
+
+  test('all fields', async () => {
+    const merchantId = '1993d0f1-8206-4336-8c88-64e170f2419e'
+    const name = 'Page Name'
+    const category = 'Page Category'
+    const title = 'Page Title'
+
+    const [trackPage] = await friendbuyDestination({
+      merchantId,
+      subscriptions
+    })
+    expect(trackPage).toBeDefined()
+
+    await trackPage.load(Context.system(), {} as Analytics)
+
+    jest.spyOn(window.friendbuyAPI as any, 'push')
+
+    const context = new Context({
+      type: 'page',
+      name,
+      category,
+      properties: {
+        title
+      }
+    })
+    // console.log('context', JSON.stringify(context, null, 2))
+
+    trackPage.page?.(context)
+
+    // console.log('trackSignUp request', JSON.stringify(window.friendbuyAPI.push.mock.calls[0], null, 2))
+    expect(window.friendbuyAPI?.push).toHaveBeenCalledWith([
+      'track',
+      'page',
+      {
+        name,
+        category,
+        title
+      },
+      true
+    ])
+  })
+})

package/src/trackPage/generated-types.ts

@@ -0,0 +1,16 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The page name.
+   */
+  name?: string
+  /**
+   * The page category.
+   */
+  category?: string
+  /**
+   * The page title.
+   */
+  title?: string
+}

package/src/trackPage/index.ts

@@ -0,0 +1,58 @@
+import type { InputField } from '@segment/actions-core'
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+
+import type { FriendbuyAPI } from '../types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { createFriendbuyPayload } from '@segment/actions-shared'
+
+export const trackPageDefaultSubscription = 'type = "page"'
+
+// https://segment.com/docs/connections/spec/page/
+export const trackPageFields: Record<string, InputField> = {
+  name: {
+    label: 'Page Name',
+    description: 'The page name.',
+    type: 'string',
+    required: false,
+    default: { '@path': '$.name' }
+  },
+  category: {
+    label: 'Page Category',
+    description: 'The page category.',
+    type: 'string',
+    required: false,
+    default: { '@path': '$.category' }
+  },
+  title: {
+    label: 'Page Title',
+    description: 'The page title.',
+    type: 'string',
+    required: false,
+    default: { '@path': '$.properties.title' }
+  }
+}
+
+const action: BrowserActionDefinition<Settings, FriendbuyAPI, Payload> = {
+  title: 'Track Page',
+  description:
+    'Record when a customer visits a new page. Allow Friendbuy widget targeting by Page Name instead of URL.',
+  defaultSubscription: trackPageDefaultSubscription,
+  platform: 'web',
+  fields: trackPageFields,
+
+  perform: (friendbuyAPI, data) => {
+    // If the page name is not defined then track the page with the name
+    // "undefined".  This is intended to allow merchants to target their widgets
+    // using page names when not all of their `analytics.page` calls include the
+    // page name.
+    const friendbuyPayload = createFriendbuyPayload([
+      ['name', data.payload.name || 'undefined'],
+      ['category', data.payload.category],
+      ['title', data.payload.title]
+    ])
+    friendbuyAPI.push(['track', 'page', friendbuyPayload, true])
+  }
+}
+
+export default action

package/src/trackPurchase/__tests__/index.test.ts

@@ -0,0 +1,211 @@
+import { Analytics, Context, JSONValue } from '@segment/analytics-next'
+import friendbuyDestination from '../../index'
+import trackPurchaseObject, { browserTrackPurchaseFields, trackPurchaseDefaultSubscription } from '../index'
+
+import { loadScript } from '@segment/browser-destination-runtime/load-script'
+jest.mock('@segment/browser-destination-runtime/load-script')
+beforeEach(async () => {
+  // Prevent friendbuy.js and campaigns.js from being loaded.
+  ;(loadScript as jest.Mock).mockResolvedValue(true)
+})
+
+describe('Friendbuy.trackPurchase', () => {
+  const subscriptions = [
+    {
+      partnerAction: 'trackPurchase',
+      name: trackPurchaseObject.title,
+      enabled: true,
+      subscribe: trackPurchaseDefaultSubscription,
+      mapping: Object.fromEntries(
+        Object.entries(browserTrackPurchaseFields).map(([name, value]) => [name, value.default])
+      )
+    }
+  ]
+
+  test('all fields', async () => {
+    const orderId = 'my order'
+    const products = [
+      { sku: 'sku1', name: 'shorts', price: 19.99, quantity: 2 },
+      { price: 5.99 },
+      {
+        sku: 'sku3',
+        name: 'tshirt',
+        price: 24.99,
+        description: 'Black T-Shirt',
+        category: 'shirts',
+        url: 'https://example.com/sku3',
+        image_url: 'https://example.com/sku3/image.jpg'
+      }
+    ]
+
+    const merchantId = '1993d0f1-8206-4336-8c88-64e170f2419e'
+    const userId = 'john-doe-12345'
+    const anonymousId = 'cbce64f6-a45a-4d9c-a63d-4c7b42773276'
+    const currency = 'USD'
+    const coupon = 'coupon-xyzzy'
+    const attributionId = '878123ed-0439-4a73-b2fe-72c4f09ec64f'
+    const referralCode = 'ref-plugh'
+    const giftCardCodes = ['card-a', 'card-b']
+    const friendbuyAttributes = { promotion: 'fall 2021' }
+    const email = 'john.doe@example.com'
+    const name = 'John Doe'
+
+    const [trackPurchase] = await friendbuyDestination({
+      merchantId,
+      subscriptions
+    })
+    // console.log('trackPurchase', JSON.stringify(trackPurchase, null, 2), trackPurchase)
+    expect(trackPurchase).toBeDefined()
+
+    await trackPurchase.load(Context.system(), {} as Analytics)
+
+    // console.log(window.friendbuyAPI)
+    jest.spyOn(window.friendbuyAPI as any, 'push')
+
+    const expectedProducts = products.map((p) => {
+      p = { sku: 'unknown', name: 'unknown', quantity: 1, ...p }
+      if (p.image_url) {
+        p.imageUrl = p.image_url
+        delete p.image_url
+      }
+      return p
+    })
+    const amount = expectedProducts.reduce((acc, p) => acc + p.price * p.quantity, 0)
+
+    {
+      // all fields
+      const context1 = new Context({
+        type: 'track',
+        event: 'Order Completed',
+        userId,
+        anonymousId,
+        properties: {
+          order_id: orderId,
+          revenue: amount,
+          subtotal: amount + 1,
+          total: amount + 2,
+          currency,
+          coupon,
+          attributionId,
+          referralCode,
+          giftCardCodes,
+          products: products as JSONValue,
+          email,
+          name,
+          friendbuyAttributes
+        }
+      })
+      // console.log('context1', JSON.stringify(context1, null, 2))
+
+      trackPurchase.track?.(context1)
+
+      // console.log('trackPurchase request', JSON.stringify(window.friendbuyAPI.push.mock.calls[0], null, 2))
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(1, [
+        'track',
+        'purchase',
+        {
+          id: orderId,
+          amount: amount + 2, // amount defaults to total
+          currency,
+          couponCode: coupon,
+          attributionId,
+          referralCode,
+          giftCardCodes,
+          customer: { id: userId, anonymousId, email, name },
+          products: expectedProducts,
+          ...friendbuyAttributes
+        },
+        true
+      ])
+      expect(window.friendbuyAPI.push.mock.calls[0][0][2].products[1].quantity).toBe(1)
+      expect(window.friendbuyAPI.push.mock.calls[0][0][2].products[2].imageUrl).toBe(products[2].image_url)
+    }
+
+    {
+      // minimal event
+      const context2 = new Context({
+        type: 'track',
+        event: 'Order Completed',
+        properties: {
+          order_id: orderId,
+          total: amount,
+          currency
+        }
+      })
+
+      trackPurchase.track?.(context2)
+
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(2, [
+        'track',
+        'purchase',
+        {
+          id: orderId,
+          amount,
+          currency
+        },
+        true
+      ])
+    }
+
+    {
+      // customer is dropped if no userId/customerId
+      // giftCardCodes is dropped if list is empty
+      const context3 = new Context({
+        type: 'track',
+        event: 'Order Completed',
+        properties: {
+          order_id: orderId,
+          total: amount,
+          currency,
+          giftCardCodes: [],
+          email,
+          name
+        }
+      })
+
+      trackPurchase.track?.(context3)
+
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(3, [
+        'track',
+        'purchase',
+        {
+          id: orderId,
+          amount,
+          currency
+        },
+        true
+      ])
+    }
+
+    {
+      // enjoined fields are converted
+      const context4 = new Context({
+        type: 'track',
+        event: 'Order Completed',
+        properties: {
+          order_id: 12345,
+          total: '129.50',
+          currency,
+          products: [{ sku: 99999, quantity: '2', price: '64.75' }],
+          customerId: 1138,
+          age: '30'
+        }
+      })
+
+      trackPurchase.track?.(context4)
+
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(4, [
+        'track',
+        'purchase',
+        {
+          id: '12345',
+          amount: 129.5,
+          currency,
+          products: [{ name: 'unknown', sku: '99999', quantity: 2, price: 64.75 }],
+          customer: { id: '1138', age: 30 }
+        },
+        true
+      ])
+    }
+  })
+})

package/src/trackPurchase/generated-types.ts

@@ -0,0 +1,91 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The order ID.
+   */
+  orderId: string
+  /**
+   * Purchase amount to be considered when evaluating reward rules.
+   */
+  amount: number
+  /**
+   * The currency of the purchase amount.
+   */
+  currency: string
+  /**
+   * The coupon code of any coupon redeemed with the order.
+   */
+  coupon?: string
+  /**
+   * Friendbuy attribution ID that associates the purchase with the advocate who referred the purchaser.
+   */
+  attributionId?: string
+  /**
+   * Friendbuy referral code that associates the purchase with the advocate who referred the purchaser.
+   */
+  referralCode?: string
+  /**
+   * An array of gift card codes applied to the order.
+   */
+  giftCardCodes?: string[]
+  /**
+   * Products purchased.
+   */
+  products?: {
+    sku?: string
+    name?: string
+    quantity?: number
+    price: number
+    description?: string
+    category?: string
+    url?: string
+    image_url?: string
+  }[]
+  /**
+   * The user's customer ID.
+   */
+  customerId?: string
+  /**
+   * The user's anonymous ID.
+   */
+  anonymousId?: string
+  /**
+   * The user's email address.
+   */
+  email?: string
+  /**
+   * Flag to indicate whether the user is a new customer.
+   */
+  isNewCustomer?: boolean
+  /**
+   * The status of the user in your loyalty program. Valid values are "in", "out", or "blocked".
+   */
+  loyaltyStatus?: string
+  /**
+   * The user's given name.
+   */
+  firstName?: string
+  /**
+   * The user's surname.
+   */
+  lastName?: string
+  /**
+   * The user's full name.
+   */
+  name?: string
+  /**
+   * The user's age.
+   */
+  age?: number
+  /**
+   * The user's birthday in the format "YYYY-MM-DD", or "0000-MM-DD" to omit the year.
+   */
+  birthday?: string
+  /**
+   * Custom attributes to send to Friendbuy. You should pass an object whose keys are the names of the custom attributes and whose values are strings. Non-string-valued attributes will be dropped.
+   */
+  friendbuyAttributes?: {
+    [k: string]: unknown
+  }
+}

package/src/trackPurchase/index.ts

@@ -0,0 +1,85 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+
+import type { FriendbuyAPI } from '../types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { AnalyticsPayload, ConvertFun, EventMap } from '@segment/actions-shared'
+
+import { COPY, ROOT, mapEvent } from '@segment/actions-shared'
+import { trackPurchaseFields } from '@segment/actions-shared'
+import {
+  addName,
+  enjoinInteger,
+  enjoinNumber,
+  enjoinString,
+  parseDate,
+  removeCustomerIfNoId
+} from '@segment/actions-shared'
+
+export const browserTrackPurchaseFields = trackPurchaseFields({})
+
+// see https://segment.com/docs/config-api/fql/
+export const trackPurchaseDefaultSubscription = 'event = "Order Completed"'
+
+const trackPurchasePub: EventMap = {
+  fields: {
+    orderId: { name: 'id', convert: enjoinString as ConvertFun },
+    amount: { convert: enjoinNumber as ConvertFun },
+    currency: COPY,
+    coupon: { name: 'couponCode' },
+    attributionId: COPY,
+    referralCode: COPY,
+    giftCardCodes: {
+      type: 'array'
+    },
+
+    products: {
+      type: 'array',
+      defaultObject: { sku: 'unknown', name: 'unknown', quantity: 1 },
+      fields: {
+        sku: { convert: enjoinString as ConvertFun },
+        name: COPY,
+        quantity: { convert: enjoinInteger as ConvertFun },
+        price: { convert: enjoinNumber as ConvertFun },
+        description: COPY,
+        category: COPY,
+        url: COPY,
+        image_url: { name: 'imageUrl' }
+      }
+    },
+
+    // CUSTOMER FIELDS
+    customerId: { name: ['customer', 'id'], convert: enjoinString as ConvertFun },
+    anonymousId: { name: ['customer', 'anonymousId'] },
+    email: { name: ['customer', 'email'] },
+    isNewCustomer: { name: ['customer', 'isNewCustomer'] },
+    loyaltyStatus: { name: ['customer', 'loyaltyStatus'] },
+    firstName: { name: ['customer', 'firstName'] },
+    lastName: { name: ['customer', 'lastName'] },
+    name: { name: ['customer', 'name'] },
+    age: { name: ['customer', 'age'], convert: enjoinInteger as ConvertFun },
+    // fbt-merchant-api complains about birthday being an object but passes it anyway.
+    birthday: { name: ['customer', 'birthday'], convert: parseDate as ConvertFun }
+  },
+  unmappedFieldObject: ROOT,
+  // Documentation of 2021-12-03 claims that both customer.id and
+  // customer.email are required, but experimentation shows only customer.id
+  // is required by pub trackPurchase.
+  finalize: removeCustomerIfNoId
+}
+
+const action: BrowserActionDefinition<Settings, FriendbuyAPI, Payload> = {
+  title: 'Track Purchase',
+  description: 'Record when a customer makes a purchase.',
+  defaultSubscription: trackPurchaseDefaultSubscription,
+  platform: 'web',
+  fields: browserTrackPurchaseFields,
+
+  perform: (friendbuyAPI, { payload }) => {
+    addName(payload)
+    const friendbuyPayload = mapEvent(trackPurchasePub, payload as unknown as AnalyticsPayload)
+    friendbuyAPI.push(['track', 'purchase', friendbuyPayload, true])
+  }
+}
+
+export default action

package/src/trackSignUp/__tests__/index.test.ts

@@ -0,0 +1,92 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import friendbuyDestination from '../../index'
+import trackSignUpObject, { browserTrackSignUpFields, trackSignUpDefaultSubscription } from '../index'
+
+import { loadScript } from '@segment/browser-destination-runtime/load-script'
+jest.mock('@segment/browser-destination-runtime/load-script')
+beforeEach(async () => {
+  // Prevent friendbuy.js and campaigns.js from being loaded.
+  ;(loadScript as jest.Mock).mockResolvedValue(true)
+})
+
+describe('Friendbuy.trackSignUp', () => {
+  const subscriptions = [
+    {
+      partnerAction: 'trackSignUp',
+      name: trackSignUpObject.title,
+      enabled: true,
+      subscribe: trackSignUpDefaultSubscription,
+      mapping: Object.fromEntries(
+        Object.entries(browserTrackSignUpFields).map(([name, value]) => [name, value.default])
+      )
+    }
+  ]
+
+  test('all fields', async () => {
+    const merchantId = '1993d0f1-8206-4336-8c88-64e170f2419e'
+    const userId = 'john-doe-12345'
+    const anonymousId = '6afc2ff2-cf54-414f-9a99-b3adb054ae31'
+    const email = 'john.doe@example.com'
+    const isNewCustomer = false
+    const loyaltyStatus = 'in'
+    const firstName = 'John'
+    const lastName = 'Doe'
+    const name = `${firstName} ${lastName}`
+    const age = 42
+    const birthday = '0000-12-31'
+    const friendbuyAttributes = { custom1: 'custom1', custom2: 'custom2' }
+
+    const [trackSignUp] = await friendbuyDestination({
+      merchantId,
+      subscriptions
+    })
+    // console.log('trackSignUp', JSON.stringify(trackSignUp, null, 2), trackSignUp)
+    expect(trackSignUp).toBeDefined()
+
+    await trackSignUp.load(Context.system(), {} as Analytics)
+
+    // console.log(window.friendbuyAPI)
+    jest.spyOn(window.friendbuyAPI as any, 'push')
+
+    const context = new Context({
+      type: 'track',
+      event: 'Signed Up',
+      userId,
+      anonymousId,
+      properties: {
+        email,
+        isNewCustomer,
+        loyaltyStatus,
+        firstName,
+        lastName,
+        name,
+        age,
+        birthday,
+        friendbuyAttributes
+      }
+    })
+    // console.log('context', JSON.stringify(context, null, 2))
+
+    trackSignUp.track?.(context)
+
+    // console.log('trackSignUp request', JSON.stringify(window.friendbuyAPI.push.mock.calls[0], null, 2))
+    expect(window.friendbuyAPI?.push).toHaveBeenCalledWith([
+      'track',
+      'sign_up',
+      {
+        id: userId,
+        email,
+        isNewCustomer,
+        loyaltyStatus,
+        firstName,
+        lastName,
+        name,
+        age,
+        anonymousId,
+        birthday: { month: 12, day: 31 },
+        ...friendbuyAttributes
+      },
+      true
+    ])
+  })
+})

package/src/trackSignUp/generated-types.ts

@@ -0,0 +1,62 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The user's customer ID.
+   */
+  customerId: string
+  /**
+   * The user's anonymous ID.
+   */
+  anonymousId?: string
+  /**
+   * The user's email address.
+   */
+  email: string
+  /**
+   * Flag to indicate whether the user is a new customer.
+   */
+  isNewCustomer?: boolean
+  /**
+   * The status of the user in your loyalty program. Valid values are "in", "out", or "blocked".
+   */
+  loyaltyStatus?: string
+  /**
+   * The user's given name.
+   */
+  firstName?: string
+  /**
+   * The user's surname.
+   */
+  lastName?: string
+  /**
+   * The user's full name.
+   */
+  name?: string
+  /**
+   * The user's age.
+   */
+  age?: number
+  /**
+   * The user's birthday in the format "YYYY-MM-DD", or "0000-MM-DD" to omit the year.
+   */
+  birthday?: string
+  /**
+   * Coupon code that customer supplied when they signed up.
+   */
+  coupon?: string
+  /**
+   * Friendbuy attribution ID that associates the customer who is signing up with the advocate who referred them.
+   */
+  attributionId?: string
+  /**
+   * Friendbuy referral code that associates the customer who is signing up with the advocate who referred them.
+   */
+  referralCode?: string
+  /**
+   * Custom attributes to send to Friendbuy. You should pass an object whose keys are the names of the custom attributes and whose values are strings. Non-string-valued attributes will be dropped.
+   */
+  friendbuyAttributes?: {
+    [k: string]: unknown
+  }
+}