Skip to main content

Ecommerce Events

EventFactory helper method#

EventFactory has a method to create all recommended ecommerce events - createEcommerceEvents.

The method creates these events:

  • add_payment_info
  • add_shipping_info
  • add_to_cart
  • add_to_wishlist
  • begin_checkout
  • generate_lead
  • purchase
  • refund
  • remove_from_cart
  • view_cart
  • view_item
  • view_item_list

You could use it like this:

// Define your configconst eventConfig = {  dataset: "analytics_XXXXXX",  incrementalTableName: "events_XXXXXX",};// Create all recommended eventslet events = ef.createEcommerceEvents();// Publish eventsevents.forEach((event) => event.publish());

Ecommerce events value parameter#

The small note about the purchase event's value parameter. It always should be float value and you could query it from value.float_value. But if the value is integer, GA4 could export it as value.int_value. So you should check both values float_value and int_value, that's why in the event configuration file includes/recommended-events.js the type for value parameter is coalesce_float.

And the helper method getSqlUnnestParam tries to COALESCE float_value, int_value and double_value and return value as float:

if (paramType.toLowerCase() === "coalesce_float") {  return `(SELECT COALESCE(ep.value.float_value, SAFE_CAST(ep.value.int_value AS FLOAT64), ep.value.double_value) FROM UNNEST(${unnestColumnName}) ep WHERE ep.key = '${paramName}' LIMIT 1) ${alias}`;}

Items#

According to Google documentation for all ecommerce events the items parameter should be added. It means that in the final you will get items columns with all child columns:

  • item_name
  • item_brand
  • item_variant
  • item_category
  • item_category2
  • item_category3
  • item_category4
  • item_category5
  • price_in_usd
  • price
  • quantity
  • item_revenue_in_usd
  • item_revenue
  • item_refund_in_usd
  • item_refund
  • coupon
  • affiliation
  • location_id
  • item_list_id
  • item_list_name
  • item_list_index
  • promotion_id
  • promotion_name
  • creative_name
  • creative_slot
  • item_params

If you don't need all these columns you could specify needed, like this:

purchase.addItemColumns([  { name: "item_id" },  { name: "item_name" },  { name: "price" },  { name: "quantity" },]);

Item-scoped custom dimensions#

warning

Item-scoped custom dimensions, were added to the BigQuery export late October 2023. And you can't use addItemParams for events before that date.

If you provide item-scoped custom dimensions, GA4 exported them in items.item_params, with following structure:

[  {    "key": <dimension_name>,    "value": {      "string_value": <string_value>,      "int_value": <int_value>,      "float_value": <float_value>,      "double_value": <double_value>,    }  }]

I you want to unnest items.item_params and keep dimensions inside items column you could use addItemParams method:

purchase.addItemParams([{ name: "color", columnName: "item_color" }]);

You could also specify value type for the dimension: 'string', 'int', 'double', 'float', 'coalesce', 'coalesce_float'. 'string' is default value type.