@segment/analytics-browser-actions-google-analytics-4 1.0.0

package/src/__tests__/viewCart.test.ts

@@ -0,0 +1,96 @@
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { Analytics, Context } from '@segment/analytics-next'
+import googleAnalytics4Web, { destination } from '../index'
+import { GA } from '../types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'viewCart',
+    name: 'View Cart',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      currency: {
+        '@path': '$.properties.currency'
+      },
+      value: {
+        '@path': '$.properties.value'
+      },
+      items: [
+        {
+          item_name: {
+            '@path': `$.properties.products.0.name`
+          },
+          item_id: {
+            '@path': `$.properties.products.0.product_id`
+          },
+          currency: {
+            '@path': `$.properties.products.0.currency`
+          },
+          price: {
+            '@path': `$.properties.products.0.price`
+          },
+          quantity: {
+            '@path': `$.properties.products.0.quantity`
+          }
+        }
+      ]
+    }
+  }
+]
+
+describe('GoogleAnalytics4Web.viewCart', () => {
+  const settings = {
+    measurementID: 'test123'
+  }
+
+  let mockGA4: GA
+  let viewCartEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [trackEventPlugin] = await googleAnalytics4Web({
+      ...settings,
+      subscriptions
+    })
+    viewCartEvent = trackEventPlugin
+
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockGA4 = {
+        gtag: jest.fn()
+      }
+      return Promise.resolve(mockGA4.gtag)
+    })
+    await trackEventPlugin.load(Context.system(), {} as Analytics)
+  })
+
+  test('GA4 viewCart Event', async () => {
+    const context = new Context({
+      event: 'View Cart',
+      type: 'track',
+      properties: {
+        currency: 'USD',
+        value: 10,
+        products: [
+          {
+            product_id: '12345',
+            name: 'Monopoly: 3rd Edition',
+            currency: 'USD'
+          }
+        ]
+      }
+    })
+
+    await viewCartEvent.track?.(context)
+
+    expect(mockGA4.gtag).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining('view_cart'),
+      expect.objectContaining({
+        currency: 'USD',
+        items: [{ currency: 'USD', item_id: '12345', item_name: 'Monopoly: 3rd Edition' }],
+        value: 10
+      })
+    )
+  })
+})

package/src/__tests__/viewItem.test.ts

@@ -0,0 +1,96 @@
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { Analytics, Context } from '@segment/analytics-next'
+import googleAnalytics4Web, { destination } from '../index'
+import { GA } from '../types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'viewItem',
+    name: 'View Item',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      currency: {
+        '@path': '$.properties.currency'
+      },
+      value: {
+        '@path': '$.properties.value'
+      },
+      items: [
+        {
+          item_name: {
+            '@path': `$.properties.products.0.name`
+          },
+          item_id: {
+            '@path': `$.properties.products.0.product_id`
+          },
+          currency: {
+            '@path': `$.properties.products.0.currency`
+          },
+          price: {
+            '@path': `$.properties.products.0.price`
+          },
+          quantity: {
+            '@path': `$.properties.products.0.quantity`
+          }
+        }
+      ]
+    }
+  }
+]
+
+describe('GoogleAnalytics4Web.viewItem', () => {
+  const settings = {
+    measurementID: 'test123'
+  }
+
+  let mockGA4: GA
+  let viewItemEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [trackEventPlugin] = await googleAnalytics4Web({
+      ...settings,
+      subscriptions
+    })
+    viewItemEvent = trackEventPlugin
+
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockGA4 = {
+        gtag: jest.fn()
+      }
+      return Promise.resolve(mockGA4.gtag)
+    })
+    await trackEventPlugin.load(Context.system(), {} as Analytics)
+  })
+
+  test('GA4 viewItem Event', async () => {
+    const context = new Context({
+      event: 'View Item',
+      type: 'track',
+      properties: {
+        currency: 'USD',
+        value: 10,
+        products: [
+          {
+            product_id: '12345',
+            name: 'Monopoly: 3rd Edition',
+            currency: 'USD'
+          }
+        ]
+      }
+    })
+
+    await viewItemEvent.track?.(context)
+
+    expect(mockGA4.gtag).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining('view_item'),
+      expect.objectContaining({
+        currency: 'USD',
+        items: [{ currency: 'USD', item_id: '12345', item_name: 'Monopoly: 3rd Edition' }],
+        value: 10
+      })
+    )
+  })
+})

package/src/__tests__/viewItemList.test.ts

@@ -0,0 +1,96 @@
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { Analytics, Context } from '@segment/analytics-next'
+import googleAnalytics4Web, { destination } from '../index'
+import { GA } from '../types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'viewItemList',
+    name: 'View Item List',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      item_list_id: {
+        '@path': '$.properties.item_list_id'
+      },
+      item_list_name: {
+        '@path': '$.properties.item_list_name'
+      },
+      items: [
+        {
+          item_name: {
+            '@path': `$.properties.products.0.name`
+          },
+          item_id: {
+            '@path': `$.properties.products.0.product_id`
+          },
+          currency: {
+            '@path': `$.properties.products.0.currency`
+          },
+          price: {
+            '@path': `$.properties.products.0.price`
+          },
+          quantity: {
+            '@path': `$.properties.products.0.quantity`
+          }
+        }
+      ]
+    }
+  }
+]
+
+describe('GoogleAnalytics4Web.viewItemList', () => {
+  const settings = {
+    measurementID: 'test123'
+  }
+
+  let mockGA4: GA
+  let viewItemListEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [trackEventPlugin] = await googleAnalytics4Web({
+      ...settings,
+      subscriptions
+    })
+    viewItemListEvent = trackEventPlugin
+
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockGA4 = {
+        gtag: jest.fn()
+      }
+      return Promise.resolve(mockGA4.gtag)
+    })
+    await trackEventPlugin.load(Context.system(), {} as Analytics)
+  })
+
+  test('GA4 viewItemList Event', async () => {
+    const context = new Context({
+      event: 'View Item List',
+      type: 'track',
+      properties: {
+        item_list_id: 12321,
+        item_list_name: 'Monopoly: 3rd Edition',
+        products: [
+          {
+            product_id: '12345',
+            name: 'Monopoly: 3rd Edition',
+            currency: 'USD'
+          }
+        ]
+      }
+    })
+
+    await viewItemListEvent.track?.(context)
+
+    expect(mockGA4.gtag).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining('view_item_list'),
+      expect.objectContaining({
+        item_list_id: 12321,
+        item_list_name: 'Monopoly: 3rd Edition',
+        items: [{ currency: 'USD', item_id: '12345', item_name: 'Monopoly: 3rd Edition' }]
+      })
+    )
+  })
+})

package/src/__tests__/viewPromotion.test.ts

@@ -0,0 +1,111 @@
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { Analytics, Context } from '@segment/analytics-next'
+import googleAnalytics4Web, { destination } from '../index'
+import { GA } from '../types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'viewPromotion',
+    name: 'Select Promotion',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      creative_name: {
+        '@path': '$.properties.creative_name'
+      },
+      creative_slot: {
+        '@path': '$.properties.creative_slot'
+      },
+      location_id: {
+        '@path': '$.properties.location_id'
+      },
+      promotion_id: {
+        '@path': '$.properties.promotion_id'
+      },
+      promotion_name: {
+        '@path': '$.properties.promotion_name'
+      },
+      items: [
+        {
+          item_name: {
+            '@path': `$.properties.products.0.name`
+          },
+          item_id: {
+            '@path': `$.properties.products.0.product_id`
+          },
+          currency: {
+            '@path': `$.properties.products.0.currency`
+          },
+          price: {
+            '@path': `$.properties.products.0.price`
+          },
+          quantity: {
+            '@path': `$.properties.products.0.quantity`
+          }
+        }
+      ]
+    }
+  }
+]
+
+describe('GoogleAnalytics4Web.viewPromotion', () => {
+  const settings = {
+    measurementID: 'test123'
+  }
+
+  let mockGA4: GA
+  let viewPromotionEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [trackEventPlugin] = await googleAnalytics4Web({
+      ...settings,
+      subscriptions
+    })
+    viewPromotionEvent = trackEventPlugin
+
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockGA4 = {
+        gtag: jest.fn()
+      }
+      return Promise.resolve(mockGA4.gtag)
+    })
+    await trackEventPlugin.load(Context.system(), {} as Analytics)
+  })
+
+  test('GA4 viewPromotion Event', async () => {
+    const context = new Context({
+      event: 'Select Promotion',
+      type: 'track',
+      properties: {
+        creative_name: 'summer_banner2',
+        creative_slot: 'featured_app_1',
+        location_id: 'ChIJIQBpAG2ahYAR_6128GcTUEo',
+        promotion_id: 'P_12345',
+        promotion_name: 'Summer Sale',
+        products: [
+          {
+            product_id: '12345',
+            name: 'Monopoly: 3rd Edition',
+            currency: 'USD'
+          }
+        ]
+      }
+    })
+
+    await viewPromotionEvent.track?.(context)
+
+    expect(mockGA4.gtag).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.stringContaining('view_promotion'),
+      expect.objectContaining({
+        creative_name: 'summer_banner2',
+        creative_slot: 'featured_app_1',
+        location_id: 'ChIJIQBpAG2ahYAR_6128GcTUEo',
+        promotion_id: 'P_12345',
+        promotion_name: 'Summer Sale',
+        items: [{ currency: 'USD', item_id: '12345', item_name: 'Monopoly: 3rd Edition' }]
+      })
+    )
+  })
+})

package/src/addPaymentInfo/generated-types.ts

@@ -0,0 +1,117 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * A unique identifier for a user. See Google's [User-ID for cross-platform analysis](https://support.google.com/analytics/answer/9213390) and [Reporting: deduplicate user counts](https://support.google.com/analytics/answer/9355949?hl=en) documentation for more information on this identifier.
+   */
+  user_id?: string
+  /**
+   * Currency of the items associated with the event, in 3-letter ISO 4217 format.
+   */
+  currency?: string
+  /**
+   * The monetary value of the event.
+   */
+  value?: number
+  /**
+   * Coupon code used for a purchase.
+   */
+  coupon?: string
+  /**
+   * The chosen method of payment.
+   */
+  payment_type?: string
+  /**
+   * The list of products purchased.
+   */
+  items: {
+    /**
+     * Identifier for the product being purchased.
+     */
+    item_id?: string
+    /**
+     * Name of the product being purchased.
+     */
+    item_name?: string
+    /**
+     * A product affiliation to designate a supplying company or brick and mortar store location.
+     */
+    affiliation?: string
+    /**
+     * Coupon code used for a purchase.
+     */
+    coupon?: string
+    /**
+     * Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
+     */
+    currency?: string
+    /**
+     * Monetary value of discount associated with a purchase.
+     */
+    discount?: number
+    /**
+     * The index/position of the item in a list.
+     */
+    index?: number
+    /**
+     * Brand associated with the product.
+     */
+    item_brand?: string
+    /**
+     * Product category.
+     */
+    item_category?: string
+    /**
+     * Product category 2.
+     */
+    item_category2?: string
+    /**
+     * Product category 3.
+     */
+    item_category3?: string
+    /**
+     * Product category 4.
+     */
+    item_category4?: string
+    /**
+     * Product category 5.
+     */
+    item_category5?: string
+    /**
+     * The ID of the list in which the item was presented to the user.
+     */
+    item_list_id?: string
+    /**
+     * The name of the list in which the item was presented to the user.
+     */
+    item_list_name?: string
+    /**
+     * Variant of the product (e.g. Black).
+     */
+    item_variant?: string
+    /**
+     * The location associated with the item.
+     */
+    location_id?: string
+    /**
+     * Price of the product being purchased, in units of the specified currency parameter.
+     */
+    price?: number
+    /**
+     * Item quantity.
+     */
+    quantity?: number
+  }[]
+  /**
+   * The user properties to send to Google Analytics 4. You must create user-scoped dimensions to ensure custom properties are picked up by Google. See Google’s [Custom user properties](https://support.google.com/analytics/answer/9269570) to learn how to set and register user properties.
+   */
+  user_properties?: {
+    [k: string]: unknown
+  }
+  /**
+   * The event parameters to send to Google Analytics 4.
+   */
+  params?: {
+    [k: string]: unknown
+  }
+}

package/src/addPaymentInfo/index.ts

@@ -0,0 +1,48 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { updateUser } from '../ga4-functions'
+import {
+  user_id,
+  user_properties,
+  currency,
+  value,
+  coupon,
+  payment_type,
+  items_multi_products,
+  params
+} from '../ga4-properties'
+
+// Change from unknown to the partner SDK types
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Add Payment Info',
+  description: 'Send event when a user submits their payment information',
+  defaultSubscription: 'type = "track" and event = "Payment Info Entered"',
+  platform: 'web',
+  fields: {
+    user_id: { ...user_id },
+    currency: { ...currency },
+    value: { ...value },
+    coupon: { ...coupon },
+    payment_type: { ...payment_type },
+    items: {
+      ...items_multi_products,
+      required: true
+    },
+    user_properties: user_properties,
+    params: params
+  },
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+    gtag('event', 'add_payment_info', {
+      currency: payload.currency,
+      value: payload.value,
+      coupon: payload.coupon,
+      payment_type: payload.payment_type,
+      items: payload.items,
+      ...payload.params
+    })
+  }
+}
+
+export default action

package/src/addToCart/generated-types.ts

@@ -0,0 +1,109 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * A unique identifier for a user. See Google's [User-ID for cross-platform analysis](https://support.google.com/analytics/answer/9213390) and [Reporting: deduplicate user counts](https://support.google.com/analytics/answer/9355949?hl=en) documentation for more information on this identifier.
+   */
+  user_id?: string
+  /**
+   * Currency of the items associated with the event, in 3-letter ISO 4217 format.
+   */
+  currency?: string
+  /**
+   * The list of products purchased.
+   */
+  items: {
+    /**
+     * Identifier for the product being purchased.
+     */
+    item_id?: string
+    /**
+     * Name of the product being purchased.
+     */
+    item_name?: string
+    /**
+     * A product affiliation to designate a supplying company or brick and mortar store location.
+     */
+    affiliation?: string
+    /**
+     * Coupon code used for a purchase.
+     */
+    coupon?: string
+    /**
+     * Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
+     */
+    currency?: string
+    /**
+     * Monetary value of discount associated with a purchase.
+     */
+    discount?: number
+    /**
+     * The index/position of the item in a list.
+     */
+    index?: number
+    /**
+     * Brand associated with the product.
+     */
+    item_brand?: string
+    /**
+     * Product category.
+     */
+    item_category?: string
+    /**
+     * Product category 2.
+     */
+    item_category2?: string
+    /**
+     * Product category 3.
+     */
+    item_category3?: string
+    /**
+     * Product category 4.
+     */
+    item_category4?: string
+    /**
+     * Product category 5.
+     */
+    item_category5?: string
+    /**
+     * The ID of the list in which the item was presented to the user.
+     */
+    item_list_id?: string
+    /**
+     * The name of the list in which the item was presented to the user.
+     */
+    item_list_name?: string
+    /**
+     * Variant of the product (e.g. Black).
+     */
+    item_variant?: string
+    /**
+     * The location associated with the item.
+     */
+    location_id?: string
+    /**
+     * Price of the product being purchased, in units of the specified currency parameter.
+     */
+    price?: number
+    /**
+     * Item quantity.
+     */
+    quantity?: number
+  }[]
+  /**
+   * The monetary value of the event.
+   */
+  value?: number
+  /**
+   * The user properties to send to Google Analytics 4. You must create user-scoped dimensions to ensure custom properties are picked up by Google. See Google’s [Custom user properties](https://support.google.com/analytics/answer/9269570) to learn how to set and register user properties.
+   */
+  user_properties?: {
+    [k: string]: unknown
+  }
+  /**
+   * The event parameters to send to Google Analytics 4.
+   */
+  params?: {
+    [k: string]: unknown
+  }
+}

package/src/addToCart/index.ts

@@ -0,0 +1,36 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { updateUser } from '../ga4-functions'
+
+import { user_properties, params, value, currency, items_single_products, user_id } from '../ga4-properties'
+
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Add to Cart',
+  description: 'This event signifies that an item was added to a cart for purchase.',
+  defaultSubscription: 'type = "track" and event = "Product Added"',
+  platform: 'web',
+  fields: {
+    user_id: user_id,
+    currency: currency,
+    items: {
+      ...items_single_products,
+      required: true
+    },
+    value: value,
+    user_properties: user_properties,
+    params: params
+  },
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+
+    gtag('event', 'add_to_cart', {
+      currency: payload.currency,
+      value: payload.value,
+      items: payload.items,
+      ...payload.params
+    })
+  }
+}
+
+export default action