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

package/src/addToWishlist/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 monetary value of the event.
+   */
+  value?: number
+  /**
+   * 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/addToWishlist/index.ts

@@ -0,0 +1,38 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+
+import { user_properties, params, value, currency, items_single_products, user_id } from '../ga4-properties'
+import { updateUser } from '../ga4-functions'
+
+// Change from unknown to the partner SDK types
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Add to Wishlist',
+  description:
+    'The event signifies that an item was added to a wishlist. Use this event to identify popular gift items in your app.',
+  platform: 'web',
+  defaultSubscription: 'type = "track" and event = "Product Added to Wishlist"',
+  fields: {
+    user_id: user_id,
+    currency: currency,
+    value: value,
+    items: {
+      ...items_single_products,
+      required: true
+    },
+    user_properties: user_properties,
+    params: params
+  },
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+
+    gtag('event', 'add_to_wishlist', {
+      currency: payload.currency,
+      value: payload.value,
+      items: payload.items,
+      ...payload.params
+    })
+  }
+}
+
+export default action

package/src/beginCheckout/generated-types.ts

@@ -0,0 +1,113 @@
+// 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
+  /**
+   * Coupon code used for a purchase.
+   */
+  coupon?: 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 event parameters to send to Google Analytics 4.
+   */
+  params?: {
+    [k: string]: unknown
+  }
+  /**
+   * 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
+  }
+}

package/src/beginCheckout/index.ts

@@ -0,0 +1,38 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+
+import { params, coupon, currency, value, items_multi_products, user_id, user_properties } from '../ga4-properties'
+import { updateUser } from '../ga4-functions'
+
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Begin Checkout',
+  description: 'This event signifies that a user has begun a checkout.',
+  defaultSubscription: 'type = "track" and event = "Checkout Started"',
+  platform: 'web',
+  fields: {
+    user_id: user_id,
+    coupon: { ...coupon, default: { '@path': '$.properties.coupon' } },
+    currency: currency,
+    items: {
+      ...items_multi_products,
+      required: true
+    },
+    value: value,
+    params: params,
+    user_properties: user_properties
+  },
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+
+    gtag('event', 'begin_checkout', {
+      currency: payload.currency,
+      value: payload.value,
+      coupon: payload.coupon,
+      items: payload.items,
+      ...payload.params
+    })
+  }
+}
+
+export default action

package/src/customEvent/generated-types.ts

@@ -0,0 +1,28 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The unique name of the custom event created in GA4. GA4 does not accept spaces in event names so Segment will replace any spaces with underscores. More information about GA4 event name rules is available in [their docs](https://support.google.com/analytics/answer/10085872?hl=en&ref_topic=9756175#event-name-rules&zippy=%2Cin-this-article.%2Cin-this-article).
+   */
+  name: string
+  /**
+   * If true, the event name will be converted to lowercase before sending to Google. Event names are case sensitive in GA4 so enable this setting to avoid distinct events for casing differences. More information about GA4 event name rules is available in [their docs](https://support.google.com/analytics/answer/10085872?hl=en&ref_topic=9756175#event-name-rules&zippy=%2Cin-this-article.%2Cin-this-article).
+   */
+  lowercase?: boolean
+  /**
+   * 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
+  /**
+   * 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/customEvent/index.ts

@@ -0,0 +1,52 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { user_id, user_properties, params } from '../ga4-properties'
+import { updateUser } from '../ga4-functions'
+
+const normalizeEventName = (name: string, lowercase: boolean | undefined): string => {
+  name = name.trim()
+  name = name.replace(/\s/g, '_')
+
+  if (lowercase) {
+    name = name.toLowerCase()
+  }
+  return name
+}
+
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Custom Event',
+  description: 'Send any custom event',
+  defaultSubscription: 'type = "track"',
+  platform: 'web',
+  fields: {
+    name: {
+      label: 'Event Name',
+      description:
+        'The unique name of the custom event created in GA4. GA4 does not accept spaces in event names so Segment will replace any spaces with underscores. More information about GA4 event name rules is available in [their docs](https://support.google.com/analytics/answer/10085872?hl=en&ref_topic=9756175#event-name-rules&zippy=%2Cin-this-article.%2Cin-this-article).',
+      type: 'string',
+      required: true,
+      default: {
+        '@path': '$.event'
+      }
+    },
+    lowercase: {
+      label: 'Lowercase Event Name',
+      description:
+        'If true, the event name will be converted to lowercase before sending to Google. Event names are case sensitive in GA4 so enable this setting to avoid distinct events for casing differences. More information about GA4 event name rules is available in [their docs](https://support.google.com/analytics/answer/10085872?hl=en&ref_topic=9756175#event-name-rules&zippy=%2Cin-this-article.%2Cin-this-article).',
+      type: 'boolean',
+      default: false
+    },
+    user_id: { ...user_id },
+    user_properties: user_properties,
+    params: params
+  },
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+    const event_name = normalizeEventName(payload.name, payload.lowercase)
+
+    gtag('event', event_name, payload.params)
+  }
+}
+
+export default action

package/src/ga4-functions.ts

@@ -0,0 +1,8 @@
+export function updateUser(userID: string | undefined, userProps: object | undefined, gtag: Function): void {
+  if (userID) {
+    gtag('set', { user_id: userID })
+  }
+  if (userProps) {
+    gtag('set', { user_properties: userProps })
+  }
+}