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

package/src/index.ts

@@ -0,0 +1,194 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+
+import addPaymentInfo from './addPaymentInfo'
+import addToCart from './addToCart'
+import addToWishlist from './addToWishlist'
+import beginCheckout from './beginCheckout'
+import customEvent from './customEvent'
+import login from './login'
+import generateLead from './generateLead'
+import purchase from './purchase'
+import refund from './refund'
+import removeFromCart from './removeFromCart'
+import search from './search'
+import selectItem from './selectItem'
+import selectPromotion from './selectPromotion'
+import signUp from './signUp'
+import viewCart from './viewCart'
+import viewItem from './viewItem'
+import viewItemList from './viewItemList'
+import viewPromotion from './viewPromotion'
+import setConfigurationFields from './setConfigurationFields'
+import { defaultValues, DestinationDefinition } from '@segment/actions-core'
+
+declare global {
+  interface Window {
+    gtag: Function
+    dataLayer: any
+  }
+}
+
+const presets: DestinationDefinition['presets'] = [
+  {
+    name: `Set Configuration Fields`,
+    subscribe: 'type = "page" or type = "identify"',
+    partnerAction: 'setConfigurationFields',
+    mapping: defaultValues(setConfigurationFields.fields)
+  }
+]
+
+export const destination: BrowserDestinationDefinition<Settings, Function> = {
+  name: 'Google Analytics 4 Web',
+  slug: 'actions-google-analytics-4-web',
+  mode: 'device',
+
+  settings: {
+    measurementID: {
+      description:
+        'The measurement ID associated with the web stream. Found in the Google Analytics UI under: Admin > Data Streams > Web > Measurement ID.',
+      label: 'Measurement ID',
+      type: 'string',
+      required: true
+    },
+    allowGoogleSignals: {
+      description: 'Set to false to disable all advertising features. Set to true by default.',
+      label: 'Allow Google Signals',
+      type: 'boolean',
+      default: true
+    },
+    allowAdPersonalizationSignals: {
+      description: 'Set to false to disable all advertising features. Set to true by default.',
+      label: 'Allow Ad Personalization Signals',
+      type: 'boolean',
+      default: true
+    },
+    cookieDomain: {
+      description: 'Specifies the domain used to store the analytics cookie. Set to “auto” by default.',
+      label: 'Cookie Domain',
+      type: 'string',
+      default: 'auto'
+    },
+    cookieExpirationInSeconds: {
+      description: `Every time a hit is sent to GA4, the analytics cookie expiration time is updated to be the current time plus the value of this field. The default value is two years (63072000 seconds). Please input the expiration value in seconds. More information in [Google Documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/config#)`,
+      label: 'Cookie Expiration In Seconds',
+      type: 'number',
+      default: 63072000
+    },
+    cookieFlags: {
+      description: `Appends additional flags to the analytics cookie.  See [write a new cookie](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie#write_a_new_cookie) for some examples of flags to set.`,
+      label: 'Cookie Flag',
+      type: 'string',
+      multiple: true
+    },
+    cookiePath: {
+      description: `Specifies the subpath used to store the analytics cookie.`,
+      label: 'Cookie Path',
+      type: 'string',
+      multiple: true
+    },
+    cookiePrefix: {
+      description: `Specifies a prefix to prepend to the analytics cookie name.`,
+      label: 'Cookie Prefix',
+      type: 'string',
+      multiple: true
+    },
+    cookieUpdate: {
+      description: `Set to false to not update  cookies on each page load. This has the effect of cookie expiration being relative to the first time a user visited. Set to true by default so update cookies on each page load.`,
+      label: 'Cookie Update',
+      type: 'boolean',
+      default: true
+    },
+    enableConsentMode: {
+      description: `Set to true to enable Google’s [Consent Mode](https://support.google.com/analytics/answer/9976101?hl=en). Set to false by default.`,
+      label: 'Enable Consent Mode',
+      type: 'boolean',
+      default: false
+    },
+    defaultAdsStorageConsentState: {
+      description:
+        'The default value for ad cookies consent state. This is only used if Enable Consent Mode is on. Set to  “granted” if it is not explicitly set. Consent state can be updated for each user in the Set Configuration Fields action.',
+      label: 'Default Ads Storage Consent State',
+      type: 'string',
+      choices: [
+        { label: 'Granted', value: 'granted' },
+        { label: 'Denied', value: 'denied' }
+      ],
+      default: 'granted'
+    },
+    defaultAnalyticsStorageConsentState: {
+      description:
+        'The default value for analytics cookies consent state. This is only used if Enable Consent Mode is on. Set to  “granted” if it is not explicitly set. Consent state can be updated for each user in the Set Configuration Fields action.',
+      label: 'Default Analytics Storage Consent State',
+      type: 'string',
+      choices: [
+        { label: 'Granted', value: 'granted' },
+        { label: 'Denied', value: 'denied' }
+      ],
+      default: 'granted'
+    },
+    waitTimeToUpdateConsentStage: {
+      description:
+        'If your CMP loads asynchronously, it might not always run before the Google tag. To handle such situations, specify a millisecond value to control how long to wait before the consent state update is sent. Please input the wait_for_update in milliseconds.',
+      label: 'Wait Time to Update Consent State',
+      type: 'number'
+    }
+  },
+
+  initialize: async ({ settings }, deps) => {
+    const config = {
+      send_page_view: false,
+      cookie_update: settings.cookieUpdate,
+      cookie_domain: settings.cookieDomain,
+      cookie_prefix: settings.cookiePrefix,
+      cookie_expires: settings.cookieExpirationInSeconds,
+      cookie_path: settings.cookiePath,
+      allow_ad_personalization_signals: settings.allowAdPersonalizationSignals,
+      allow_google_signals: settings.allowGoogleSignals
+    }
+
+    window.dataLayer = window.dataLayer || []
+    window.gtag = function () {
+      // eslint-disable-next-line prefer-rest-params
+      window.dataLayer.push(arguments)
+    }
+
+    window.gtag('js', new Date())
+    window.gtag('config', settings.measurementID, config)
+    if (settings.enableConsentMode) {
+      window.gtag('consent', 'default', {
+        ad_storage: settings.defaultAdsStorageConsentState,
+        analytics_storage: settings.defaultAnalyticsStorageConsentState,
+        wait_for_update: settings.waitTimeToUpdateConsentStage
+      })
+    }
+    const script = `https://www.googletagmanager.com/gtag/js?id=${settings.measurementID}`
+    await deps.loadScript(script)
+    return window.gtag
+  },
+  presets,
+  actions: {
+    addPaymentInfo,
+    login,
+    signUp,
+    search,
+    addToCart,
+    addToWishlist,
+    removeFromCart,
+    selectItem,
+    selectPromotion,
+    viewItem,
+    viewPromotion,
+    beginCheckout,
+    purchase,
+    refund,
+    viewCart,
+    viewItemList,
+    generateLead,
+    customEvent,
+    setConfigurationFields
+  }
+}
+
+export default browserDestination(destination)

package/src/login/generated-types.ts

@@ -0,0 +1,24 @@
+// 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
+  /**
+   * The method used to login.
+   */
+  method?: 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/login/index.ts

@@ -0,0 +1,31 @@
+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, user_id, method } from '../ga4-properties'
+import { updateUser } from '../ga4-functions'
+
+// Change from unknown to the partner SDK types
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Login',
+  description: 'Send event when a user logs in',
+  platform: 'web',
+  defaultSubscription: 'type = "track" and event = "Signed In"',
+  fields: {
+    user_id: user_id,
+    method: method,
+    user_properties: user_properties,
+    params: params
+  },
+
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+
+    gtag('event', 'login', {
+      method: payload.method,
+      ...payload.params
+    })
+  }
+}
+
+export default action

package/src/purchase/generated-types.ts

@@ -0,0 +1,125 @@
+// 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 unique identifier of a transaction.
+   */
+  transaction_id: string
+  /**
+   * Shipping cost associated with the transaction.
+   */
+  shipping?: number
+  /**
+   * Total tax associated with the transaction.
+   */
+  tax?: 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/purchase/index.ts

@@ -0,0 +1,54 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import {
+  coupon,
+  currency,
+  transaction_id,
+  value,
+  user_id,
+  shipping,
+  tax,
+  items_multi_products,
+  params,
+  user_properties
+} from '../ga4-properties'
+import { updateUser } from '../ga4-functions'
+
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Purchase',
+  description: 'This event signifies when one or more items is purchased by a user.',
+  defaultSubscription: 'type = "track" and event = "Order Completed"',
+  platform: 'web',
+  fields: {
+    user_id: user_id,
+    coupon: { ...coupon, default: { '@path': '$.properties.coupon' } },
+    currency: { ...currency, required: true },
+    items: {
+      ...items_multi_products,
+      required: true
+    },
+    transaction_id: { ...transaction_id, required: true },
+    shipping: shipping,
+    tax: tax,
+    value: { ...value, default: { '@path': '$.properties.total' } },
+    user_properties: user_properties,
+    params: params
+  },
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+
+    gtag('event', 'purchase', {
+      currency: payload.currency,
+      transaction_id: payload.transaction_id,
+      value: payload.value,
+      coupon: payload.coupon,
+      tax: payload.tax,
+      shipping: payload.shipping,
+      items: payload.items,
+      ...payload.params
+    })
+  }
+}
+
+export default action

package/src/refund/generated-types.ts

@@ -0,0 +1,129 @@
+// 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 unique identifier of a transaction.
+   */
+  transaction_id: string
+  /**
+   * The monetary value of the event.
+   */
+  value?: number
+  /**
+   * Store or affiliation from which this transaction occurred (e.g. Google Store).
+   */
+  affiliation?: string
+  /**
+   * Coupon code used for a purchase.
+   */
+  coupon?: string
+  /**
+   * Shipping cost associated with the transaction.
+   */
+  shipping?: number
+  /**
+   * Total tax associated with the transaction.
+   */
+  tax?: 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/refund/index.ts

@@ -0,0 +1,57 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+
+import {
+  coupon,
+  transaction_id,
+  user_id,
+  currency,
+  value,
+  affiliation,
+  shipping,
+  items_multi_products,
+  params,
+  user_properties,
+  tax
+} from '../ga4-properties'
+import { updateUser } from '../ga4-functions'
+
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Refund',
+  description: 'This event signifies when one or more items is refunded to a user.',
+  defaultSubscription: 'type = "track" and event = "Order Refunded"',
+  platform: 'web',
+  fields: {
+    user_id: user_id,
+    currency: currency,
+    transaction_id: { ...transaction_id, required: true },
+    value: { ...value, default: { '@path': '$.properties.total' } },
+    affiliation: affiliation,
+    coupon: coupon,
+    shipping: shipping,
+    tax: tax,
+    items: {
+      ...items_multi_products
+    },
+    user_properties: user_properties,
+    params: params
+  },
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+
+    gtag('event', 'refund', {
+      currency: payload.currency,
+      transaction_id: payload.transaction_id, // Transaction ID. Required for purchases and refunds.
+      value: payload.value,
+      affiliation: payload.affiliation,
+      coupon: payload.coupon,
+      shipping: payload.shipping,
+      tax: payload.tax,
+      items: payload.items,
+      ...payload.params
+    })
+  }
+}
+
+export default action