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

package/src/ga4-properties.ts

@@ -0,0 +1,368 @@
+import { InputField } from '@segment/actions-core/destination-kit/types'
+
+export const formatUserProperties = (userProperties: object | undefined): object | undefined => {
+  if (!userProperties) {
+    return undefined
+  }
+
+  let properties = {}
+
+  Object.entries(userProperties).forEach(([key, value]) => {
+    properties = { ...properties, ...{ [key]: { value: value } } }
+  })
+
+  return { user_properties: properties }
+}
+
+export const user_properties: InputField = {
+  label: 'User Properties',
+  description:
+    '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. ',
+  type: 'object',
+  additionalProperties: true,
+  defaultObjectUI: 'keyvalue'
+}
+
+export const params: InputField = {
+  label: 'Event Parameters',
+  description: 'The event parameters to send to Google Analytics 4.',
+  type: 'object',
+  additionalProperties: true,
+  defaultObjectUI: 'keyvalue'
+}
+export const user_id: InputField = {
+  label: 'User ID',
+  type: 'string',
+  description:
+    "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."
+}
+
+export const promotion_id: InputField = {
+  label: 'Promotion ID',
+  type: 'string',
+  description: 'The ID of the promotion associated with the event.'
+}
+
+export const promotion_name: InputField = {
+  label: 'Promotion Name',
+  type: 'string',
+  description: 'The name of the promotion associated with the event.'
+}
+
+export const creative_slot: InputField = {
+  label: 'Creative Slot',
+  type: 'string',
+  description: 'The name of the promotional creative slot associated with the event.'
+}
+
+export const creative_name: InputField = {
+  label: 'Creative Name',
+  type: 'string',
+  description: 'The name of the promotional creative.'
+}
+
+export const tax: InputField = {
+  label: 'Tax',
+  type: 'number',
+  description: 'Total tax associated with the transaction.',
+  default: {
+    '@path': '$.properties.tax'
+  }
+}
+
+export const shipping: InputField = {
+  label: 'Shipping',
+  type: 'number',
+  description: 'Shipping cost associated with the transaction.',
+  default: {
+    '@path': '$.properties.shipping'
+  }
+}
+
+export const transaction_id: InputField = {
+  label: 'Order Id',
+  type: 'string',
+  description: 'The unique identifier of a transaction.',
+  default: {
+    '@path': '$.properties.order_id'
+  }
+}
+
+export const affiliation: InputField = {
+  label: 'Affiliation',
+  type: 'string',
+  description: 'Store or affiliation from which this transaction occurred (e.g. Google Store).',
+  default: {
+    '@path': '$.properties.affiliation'
+  }
+}
+
+export const client_id: InputField = {
+  label: 'Client ID',
+  description: 'Uniquely identifies a user instance of a web client.',
+  type: 'string',
+  required: true,
+  default: {
+    '@if': {
+      exists: { '@path': '$.userId' },
+      then: { '@path': '$.userId' },
+      else: { '@path': '$.anonymousId' }
+    }
+  }
+}
+
+export const currency: InputField = {
+  label: 'Currency',
+  type: 'string',
+  description: 'Currency of the items associated with the event, in 3-letter ISO 4217 format.',
+  default: { '@path': '$.properties.currency' }
+}
+
+export const value: InputField = {
+  label: 'Value',
+  type: 'number',
+  description: 'The monetary value of the event.',
+  default: {
+    '@path': '$.properties.value'
+  }
+}
+
+export const coupon: InputField = {
+  label: 'Coupon',
+  type: 'string',
+  description: 'Coupon code used for a purchase.'
+}
+
+export const payment_type: InputField = {
+  label: 'Payment Type',
+  type: 'string',
+  description: 'The chosen method of payment.',
+  default: {
+    '@path': '$.properties.payment_method'
+  }
+}
+
+export const method: InputField = {
+  label: 'Method',
+  type: 'string',
+  description: 'The method used to login.',
+  default: {
+    '@path': '$.properties.method'
+  }
+}
+
+export const search_term: InputField = {
+  label: 'Search Term',
+  type: 'string',
+  description: 'The term that was searched for.',
+  default: {
+    '@path': `$.properties.query`
+  }
+}
+
+export const item_list_name: InputField = {
+  label: 'Item List Name',
+  description: 'The name of the list in which the item was presented to the user.',
+  type: 'string',
+  default: {
+    '@path': `$.properties.item_list_name`
+  }
+}
+export const item_list_id: InputField = {
+  label: 'Item List Id',
+  description: 'The ID of the list in which the item was presented to the user.',
+  type: 'string',
+  default: {
+    '@path': `$.properties.item_list_id`
+  }
+}
+export const location_id: InputField = {
+  label: 'Location ID',
+  type: 'string',
+  description: 'The ID of the location.',
+  default: {
+    '@path': '$.properties.position'
+  }
+}
+
+export const minimal_items: InputField = {
+  label: 'Products',
+  description: 'The list of products purchased.',
+  type: 'object',
+  multiple: true,
+  properties: {
+    item_id: {
+      label: 'Product ID',
+      type: 'string',
+      description: 'Identifier for the product being purchased.'
+    },
+    item_name: {
+      label: 'Name',
+      type: 'string',
+      description: 'Name of the product being purchased.'
+    },
+    affiliation: {
+      label: 'Affiliation',
+      type: 'string',
+      description: 'A product affiliation to designate a supplying company or brick and mortar store location.'
+    },
+    coupon: {
+      label: 'Coupon',
+      type: 'string',
+      description: 'Coupon code used for a purchase.'
+    },
+    currency: {
+      label: 'Currency',
+      type: 'string',
+      description: 'Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.'
+    },
+    discount: {
+      label: 'Discount',
+      type: 'number',
+      description: 'Monetary value of discount associated with a purchase.'
+    },
+    index: {
+      label: 'Index',
+      type: 'number',
+      description: 'The index/position of the item in a list.'
+    },
+    item_brand: {
+      label: 'Brand',
+      type: 'string',
+      description: 'Brand associated with the product.'
+    },
+    item_category: {
+      label: 'Category',
+      type: 'string',
+      description: 'Product category.'
+    },
+    item_category2: {
+      label: 'Category 2',
+      type: 'string',
+      description: 'Product category 2.'
+    },
+    item_category3: {
+      label: 'Category 3',
+      type: 'string',
+      description: 'Product category 3.'
+    },
+    item_category4: {
+      label: 'Category 4',
+      type: 'string',
+      description: 'Product category 4.'
+    },
+    item_category5: {
+      label: 'Category 5',
+      type: 'string',
+      description: 'Product category 5.'
+    },
+    item_list_id: {
+      label: 'Item List ID',
+      type: 'string',
+      description: 'The ID of the list in which the item was presented to the user.'
+    },
+    item_list_name: {
+      label: 'Item List Name',
+      type: 'string',
+      description: 'The name of the list in which the item was presented to the user.'
+    },
+    item_variant: {
+      label: 'Variant',
+      type: 'string',
+      description: 'Variant of the product (e.g. Black).'
+    },
+    location_id: {
+      label: 'Location ID',
+      type: 'string',
+      description: 'The location associated with the item.'
+    },
+    price: {
+      label: 'Price',
+      type: 'number',
+      description: 'Price of the product being purchased, in units of the specified currency parameter.'
+    },
+    quantity: {
+      label: 'Quantity',
+      type: 'integer',
+      description: 'Item quantity.'
+    }
+  }
+}
+
+export const items_single_products: InputField = {
+  ...minimal_items,
+  default: {
+    '@arrayPath': [
+      '$.properties.products',
+      {
+        item_id: {
+          '@path': '$.product_id'
+        },
+        item_name: {
+          '@path': '$.name'
+        },
+        affiliation: {
+          '@path': '$.affiliation'
+        },
+        coupon: {
+          '@path': '$.coupon'
+        },
+        item_brand: {
+          '@path': '$.brand'
+        },
+        item_category: {
+          '@path': '$.category'
+        },
+        item_variant: {
+          '@path': '$.variant'
+        },
+        price: {
+          '@path': '$.price'
+        },
+        quantity: {
+          '@path': '$.quantity'
+        }
+      }
+    ]
+  }
+}
+export const items_multi_products: InputField = {
+  ...minimal_items,
+  default: {
+    '@arrayPath': [
+      '$.properties.products',
+      {
+        item_id: {
+          '@path': '$.product_id'
+        },
+        item_name: {
+          '@path': '$.name'
+        },
+        affiliation: {
+          '@path': '$.affiliation'
+        },
+        coupon: {
+          '@path': '$.coupon'
+        },
+        index: {
+          '@path': '$.position'
+        },
+        item_brand: {
+          '@path': '$.brand'
+        },
+        item_category: {
+          '@path': '$.category'
+        },
+        item_variant: {
+          '@path': '$.variant'
+        },
+        price: {
+          '@path': '$.price'
+        },
+        quantity: {
+          '@path': '$.quantity'
+        }
+      }
+    ]
+  }
+}

package/src/ga4-types.ts

@@ -0,0 +1,28 @@
+export interface ProductItem {
+  item_id?: string
+  item_name?: string
+  affiliation?: string
+  coupon?: string
+  currency?: string
+  discount?: number
+  index?: number
+  item_brand?: string
+  item_category?: string
+  item_category2?: string
+  item_category3?: string
+  item_category4?: string
+  item_category5?: string
+  item_list_id?: string
+  item_list_name?: string
+  item_variant?: string
+  location_id?: string
+  price?: number
+  quantity?: number
+}
+
+export interface PromotionProductItem extends ProductItem {
+  creative_name?: string
+  creative_slot?: string
+  promotion_id?: string
+  promotion_name?: string
+}

package/src/generateLead/generated-types.ts

@@ -0,0 +1,28 @@
+// 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 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/generateLead/index.ts

@@ -0,0 +1,32 @@
+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, currency, value } from '../ga4-properties'
+import { updateUser } from '../ga4-functions'
+
+const action: BrowserActionDefinition<Settings, Function, Payload> = {
+  title: 'Generate Lead',
+  description:
+    'Log this event when a lead has been generated to understand the efficacy of your re-engagement campaigns.',
+  platform: 'web',
+  defaultSubscription: 'type = "track"',
+  fields: {
+    user_id: user_id,
+    currency: currency,
+    value: value,
+    user_properties: user_properties,
+    params: params
+  },
+  perform: (gtag, { payload }) => {
+    updateUser(payload.user_id, payload.user_properties, gtag)
+
+    gtag('event', 'generate_lead', {
+      currency: payload.currency,
+      value: payload.value,
+      ...payload.params
+    })
+  }
+}
+
+export default action

package/src/generated-types.ts

@@ -0,0 +1,56 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * The measurement ID associated with the web stream. Found in the Google Analytics UI under: Admin > Data Streams > Web > Measurement ID.
+   */
+  measurementID: string
+  /**
+   * Set to false to disable all advertising features. Set to true by default.
+   */
+  allowGoogleSignals?: boolean
+  /**
+   * Set to false to disable all advertising features. Set to true by default.
+   */
+  allowAdPersonalizationSignals?: boolean
+  /**
+   * Specifies the domain used to store the analytics cookie. Set to “auto” by default.
+   */
+  cookieDomain?: string
+  /**
+   * 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#)
+   */
+  cookieExpirationInSeconds?: number
+  /**
+   * 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.
+   */
+  cookieFlags?: string[]
+  /**
+   * Specifies the subpath used to store the analytics cookie.
+   */
+  cookiePath?: string[]
+  /**
+   * Specifies a prefix to prepend to the analytics cookie name.
+   */
+  cookiePrefix?: string[]
+  /**
+   * 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.
+   */
+  cookieUpdate?: boolean
+  /**
+   * Set to true to enable Google’s [Consent Mode](https://support.google.com/analytics/answer/9976101?hl=en). Set to false by default.
+   */
+  enableConsentMode?: boolean
+  /**
+   * 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.
+   */
+  defaultAdsStorageConsentState?: string
+  /**
+   * 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.
+   */
+  defaultAnalyticsStorageConsentState?: string
+  /**
+   * 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.
+   */
+  waitTimeToUpdateConsentStage?: number
+}