电子商务事件兼容性和转换参考 (gtag.js)

本文档介绍了 Universal Analytics (UA) 与 Google Analytics(分析)4 (GA4) 之间的电子商务事件兼容性和转换。

背景

GA4 电子商务事件在发送到 UA 媒体资源时会自动转换为等效的 UA 事件。在将 UA 电子商务事件发送到 GA4 媒体资源时,也会发生这种转换。本文档介绍了转换的运作方式、事件的兼容性,以及您在使用自动转换时可能需要做出的任何权衡取舍。

目的

UA 电子商务事件与 GA4 电子商务事件之间的转换可为您提供以下几个方面的帮助:

  • 易于实现:只需使用现有的 UA 实现方式并对配置稍作更新,即可采用 GA4 电子商务。
  • 无需进行双重代码植入:您可以向 UA 媒体资源和 GA4 媒体资源发送相同的电子商务事件。这提供了一个选项,让您可以在转换为 GA4 的同时保留 UA 电子商务实现方式,无需维护双重代码植入配置。

权衡因素

兼容性可让您灵活地选择最合适的 GA4 迁移路径,从而满足您在保留 UA 实现方式方面的短期和长期要求。

大多数 GA4 电子商务事件/参数都与 UA 兼容,反之亦然。在存在不兼容的少数情况下,UA 或 GA4 电子商务报告中填充的数据可能并不完整,具体取决于您做出的迁移选择。

如需详细了解兼容性和所需配置,请务必查看各个迁移选项

转换的运作方式

  • GA4 电子商务事件发送到 UA 媒体资源时会转换为等效的 UA (gtag.js) 电子商务事件。
    • 系统会以类似的 GA4 参数中的值填充 UA 事件参数。如果系统无法用 GA4 事件(即没有类似参数)填充 UA 参数,则会在将事件发送到 UA 媒体资源时忽略该参数。
  • UA (gtag.js) 电子商务事件发送到 GA4 媒体资源时会转换为等效的 GA4 电子商务事件。
    • 系统会以类似的 UA 参数中的值填充 GA4 事件参数。如果系统无法用 UA 事件(即没有等效参数)填充 GA4 参数,则会在将事件发送到 GA4 媒体资源时忽略该参数。在某些情况下,如果 UA 参数没有类似的 GA4 参数,则将以自定义参数的形式随 GA4 事件一起发送。
  • 从 GA4 到 UA 以及从 UA 到 GA4 的所有转换都将在客户端执行。
  • 事件/参数转换默认处于启用状态,无需进行任何用户配置,也无法停用。

UA 和 GA4 的类似参数

下表显示了 Universal Analytics 和 Google Analytics(分析)4 的类似电子商务参数。

Universal Analytics 参数名称 Google Analytics(分析)4 参数名称 备注
affiliation affiliation
checkout_step
checkout_option
content_type
coupon coupon
currency currency 在将 UA 事件发送到 GA4 媒体资源时,此货币值将用于 GA4 items[].currency 参数。
location_id
payment_type
shipping shipping
shipping_tier
tax tax
transaction_id transaction_id
value value
items[] items[]
items[].name items[].item_name
items[].id items[].item_id
items[].affiliation
items[].brand items[].item_brand
items[].category
items[].item_category
items[].item_category2
items[].item_category3
items[].item_category4
items[].item_category5
商品所属类别。可指定最多 5 个层级。

如需详细了解如何处理 UA 事件与 GA4 事件之间的类别转换,请参阅类别参数转换
items[].currency
items[].coupon items[].coupon
items[].discount
items[].list_name items[].item_list_name
items[].list_position items[].index
items[].location_id
items[].price items[].price
items[].quantity items[].quantity
items[].variant items[].item_variant
promotions[] 对于 GA4,items[] 与促销专属参数(例如 items[].promotion_id)搭配使用。
promotions[].id items[].promotion_id 在将 UA 事件发送到 GA4 或将 GA4 事件发送到 UA 时,这些参数不会进行转换。
promotions[].name items[].promotion_name 在将 UA 事件发送到 GA4 或将 GA4 事件发送到 UA 时,这些参数不会进行转换。
promotions[].creative_name
promotions[].creative_slot items[].creative_slot 在将 UA 事件发送到 GA4 或将 GA4 事件发送到 UA 时,这些参数不会进行转换。

类别参数转换

在将 GA4 事件发送到 UA 或将 UA 事件发送到 GA4 时,类别参数的转换将作为特殊情况进行处理。

对于 Universal Analytics,在设置 items[].category 参数时,您可以使用 / 作为分隔符来指定最多五个层级。在 Google Analytics(分析)4 中,您可以使用枚举的类别参数指定最多五个层级:items[].item_categoryitems[].item_category2items[].item_category3items[].item_category4items[].item_category5

类别转换行为如下所示:

  • 对于转换为 UA 事件的 GA4 事件,枚举类别将合并到一个 category 参数,每个类别用 / 分隔。
  • 对于转换为 GA4 事件的 UA 事件,系统会对类别参数的值进行拆分,以填充相应的 GA4 枚举类别。
  • 如果您打算将 GA4 事件发送到 UA,建议您不要在类别值中使用 / 字符,因为在转换为 UA 事件时,该字符会被解释为类别分隔符。
  • 无论定义了多少个类别层级,系统都将仅使用前 5 个类别层级。

类别转换示例

以下示例展示了转换为 GA4 类别参数的 UA 类别参数。在将 GA4 事件转换为 UA 事件时,这一原则同样适用。

具有定义了 5 个层级的类别的 UA 事件:

gtag("event", "add_to_cart", {
  items: [{
    ...
    category: "Apparel/Adult/Shirts/Crew/Short sleeve",
    ...
  }]
});

已转换为 GA4 事件的 UA 事件(具有枚举类别):

gtag("event", "add_to_cart", {
  items: [{
    ...
    item_category: "Apparel",
    item_category2: "Adult",
    item_category3: "Shirts",
    item_category4: "Crew",
    item_category5: "Short sleeve",
    ...
  }]
});

UA 事件与 GA4 事件之间的兼容性

下表显示了 Universal Analytics 和 Google Analytics(分析)4 的类似电子商务事件以及将 UA 事件发送到 GA4 和将 GA4 事件发送到 UA 时的转换行为。

对于表格中的每一行,每一列都会提供以下信息:

  • UA 事件GA4 事件列根据要衡量的指标显示类似事件。
  • 参数列列出了在相应的 UA 事件和 GA4 事件之间没有等效项的参数。“仅限 GA4”列出了仅用于 GA4 事件的参数,“仅限 UA”列出了仅用于 UA 事件的参数。
  • 转换行为(将 UA 事件发送到 GA4)列描述了在将 UA 事件发送到 GA4 媒体资源时的转换行为。备注详细说明了发送的数据、与 GA4 事件的差异以及对 GA4 报告造成的任何显著影响。
  • 转换行为(将 GA4 事件发送到 UA)列描述了在将 UA 事件发送到 GA4 媒体资源时的转换行为。备注详细说明了发送的数据、与 UA 事件的差异以及对 UA 报告造成的任何显著影响。
UA 事件 GA4 事件 参数 转换行为
(将 UA 事件发送到 GA4)
转换行为
(将 GA4 事件发送到 UA)
view_item_list 仅限 GA4:
item_list_id
item_list_name
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id
兼容

所有 UA 参数都会转换为等效的 GA4 参数并发送。

如果 GA4 报告需要任何“仅限 GA4”参数,则报告将是不完整的。
兼容

系统会转换并发送具有等效的 UA 参数的 GA4 参数。不会发送“仅限 GA4”参数。 系统会忽略事件级 item_list_name 参数,仅发送商品级 item_list_name

填充了来自 GA4 事件的数据的 UA 报告将是完整的/保持不变。
select_content (items) 仅限 GA4:
item_list_id
item_list_name
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id

仅限 UA:
content_type
不兼容

系统会发送 select_content 自定义事件和 content_type 自定义参数。不会发送任何 items 数据。
不兼容

系统会发送 UA 事件命中,其中 event_categorygeneralevent_actionselect_item。不会发送任何 items 数据。
select_content (promotions) 仅限 GA4:
creative_name
creative_slot
location_id
promotion_id
promotion_name
items

仅限 UA:
content_type
promotions
不兼容

系统会发送 select_content 自定义事件,其中 content_typepromotions 作为自定义参数。promotions 自定义参数不包含任何实用数据。
不兼容

系统会发送 UA 事件命中,其中 event_categorygeneralevent_actionselect_promotion。不会发送任何 promotions 数据。
view_item 仅限 GA4:
currency
value
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id
兼容

所有 UA 参数都会转换为等效的 GA4 参数并发送。

如果 GA4 报告需要任何“仅限 GA4”参数,则报告将是不完整的。
兼容

系统会转换并发送具有等效的 UA 参数的 GA4 参数。但 item_list_name 除外,系统不会发送该参数。在“仅限 GA4”参数中,currencyvalue(分别作为货币交易收入)随命中一起发送。event_value 也会设置为 value 参数(以整数表示)。 请注意,从 GA4 转换到 UA 包括 event_value,但通常不会针对 UA 命中设置此参数。

填充了来自 GA4 的数据的 UA 报告大体上是完整的/保持不变。商品列表名称将会缺失。
add_to_wishlist*

*UA 不支持 items 数据。
仅限 GA4:
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id
兼容

所有 UA 参数都会转换为等效的 GA4 参数并发送。

如果 GA4 报告需要任何“仅限 GA4”参数,则报告将是不完整的。
兼容

系统会发送等效的事件命中,其中 event_categoryecommerceevent_actionadd_to_wishlist,且 event_valuevalue 参数。

填充了来自 GA4 事件的数据的 UA 报告将是完整的/保持不变。由于此事件在 UA 电子商务报告中一般不受支持,因此不会造成任何显著的影响。
add_to_cart 仅限 GA4:
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id
兼容

所有 UA 参数都会转换为等效的 GA4 参数并发送。

如果 GA4 报告需要任何“仅限 GA4”参数,则报告将是不完整的。
兼容

系统会转换并发送具有等效的 UA 参数的 GA4 参数。*不会发送“仅限 GA4”参数。

*系统不会发送 item_list_name,但此行为与 gtag.js (UA) 一致,后者不会发送 list_name

填充了来自 GA4 事件的数据的 UA 报告将是完整的/保持不变。
remove_from_cart 仅限 GA4:
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id
兼容

所有 UA 参数都会转换为等效的 GA4 参数并发送。

如果 GA4 报告需要任何“仅限 GA4”参数,则报告将是不完整的。
兼容

系统会转换并发送具有等效的 UA 参数的 GA4 参数。*不会发送“仅限 GA4”参数。

*系统不会发送 item_list_name,但此行为与 gtag.js (UA) 一致,后者不会发送 list_name

填充了来自 GA4 事件的数据的 UA 报告将是完整的/保持不变。
不适用 仅针对 GA4 推荐此事件。
不兼容*

*您的 UA 实现不太可能发送此事件,因为它不是推荐事件。为确保 GA4 报告全面完整,您可以采用 GA4 格式针对 UA 实现此事件。

如果您针对 UA 实现 GA4 事件,该事件将显示为不含 items 数据(这些数据可能不是很有用)的事件。这不会对 UA 电子商务报告造成任何影响。
不兼容

系统会发送事件命中,其中 event_categorygeneralevent_actionview_cart,且 event_valuevalue 参数。 不会发送 items 数据。

由于此事件在 UA 电子商务报告中一般不受支持,因此不会造成任何显著的影响。
begin_checkout 仅限 GA4:
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id
兼容

所有 UA 参数都会转换为等效的 GA4 参数并发送。

如果 GA4 报告需要任何“仅限 GA4”参数,则报告将是不完整的。
兼容

系统会转换并发送具有等效的 UA 参数的 GA4 参数。*不会发送“仅限 GA4”参数。

*系统不会发送 item_list_name,但此行为与 gtag.js (UA) 一致,后者不会发送 list_name

begin_checkout 实际上等效于发送 checkout_progress 事件并将 checkout_step 设置为 1

填充了来自 GA4 事件的数据的 UA 报告将是完整的/保持不变。
add_payment_info 仅限 GA4:
currency
value
coupon
payment_type
items

UA:
不适用:参数不受支持。
不兼容*

*由于 UA 不支持此事件的参数,因此系统不会发送任何参数。您可以发送这些参数,但可能不是很有用。

如果 GA4 报告需要该事件的任何参数,则报告将是不完整的。
兼容

系统会发送等效的事件命中,其中 event_categoryecommerceevent_actionadd_to_wishlist,且 event_valuevalue 参数(已转换为整数)。请注意,从 GA4 转换到 UA 包括 event_value,但通常不会针对 UA 命中设置此参数。

填充了来自 GA4 事件的数据的 UA 报告将是完整的/保持不变。由于此事件在 UA 电子商务报告中一般不受支持,因此不会造成任何显著的影响。
不适用 仅针对 GA4 推荐此事件。
不兼容*

*您的 UA 实现不太可能发送此事件,因为它不是推荐事件。为确保 GA4 报告全面完整,您可以采用 GA4 格式针对 UA 实现此事件。

如果您针对 UA 实现 GA4 事件,该事件将显示为不含 items 数据(这些数据可能不是很有用)的事件。这不会对 UA 电子商务报告造成任何影响。
不兼容*

系统会发送事件命中,其中 event_categorygeneralevent_actionadd_shipping_info,且 event_valuevalue 参数(已转换为整数)。GA4 currency 参数作为币种随命中一起发送。

由于此事件在 UA 电子商务报告中一般不受支持,因此不会造成任何显著的影响。
checkout_progress
set_checkout_option
不适用 仅针对 UA 推荐这些事件。
事件将被视为自定义事件。系统仅会发送事件级参数,不会发送任何 items 数据。

由于这些事件在 GA4 电子商务报告中一般不受支持,因此不会造成任何显著的影响。
不适用
view_promotion 仅限 GA4:
creative_name
creative_slot
location_id
promotion_id
promotion_name
items

仅限 UA:
promotions
不兼容

系统会发送 view_promotion 自定义事件,其中 promotions 作为自定义参数。promotions 自定义参数不包含任何实用数据。
不兼容

系统会发送 UA 事件命中,其中 event_categoryengagementevent_actionview_promotion。不会发送任何 promotions 数据。该事件已被标记为非互动事件
purchase 仅限 GA4:
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id
兼容

所有 UA 参数都会转换为等效的 GA4 参数并发送。

由于商品级 currency 不受支持,因此使用事件级 currency

如果 GA4 报告需要任何“仅限 GA4”参数,则报告将是不完整的。
兼容

系统会转换并发送具有等效的 UA 参数的 GA4 参数。*不会发送“仅限 GA4”参数。

*系统不会发送 item_list_name,但此行为与 gtag.js (UA) 一致,后者不会发送 list_name

填充了来自 GA4 事件的数据的 UA 报告将是完整的/保持不变。
refund 仅限 GA4:
affiliation
items[].affiliation
items[].currency
items[].discount
items[].item_list_id
items[].location_id
兼容

所有 UA 参数都会转换为等效的 GA4 参数并发送。

由于商品级 currency 不受支持,因此使用事件级 currency

如果 GA4 报告需要任何“仅限 GA4”参数,则报告将是不完整的。
兼容

系统会转换并发送具有等效的 UA 参数的 GA4 参数。*不会发送“仅限 GA4”参数。

*系统不会发送 item_list_name,但此行为与 gtag.js (UA) 一致,后者不会发送 list_name

填充了来自 GA4 事件的数据的 UA 报告将是完整的/保持不变。