本文介绍的是 Google Analytics(分析)4 媒体资源。如果您仍在使用 Universal Analytics 媒体资源,请参阅 Universal Analytics 部分,这些媒体资源将于 2023 年 7 月 1 日起停止处理数据(Analytics 360 媒体资源将从 2023 年 10 月 1 日起停止)。

[GA4] BigQuery Export 架构

本文介绍了 Google Analytics(分析)4 媒体资源和 Google Analytics for Firebase 中的数据在导出至 BigQuery 时所采用的格式和架构。

数据集

对于每个关联到 BigQuery 的 Google Analytics(分析)4 媒体资源和 Firebase 项目,系统都会在 BigQuery 项目中添加一个名为“analytics_<property_id>”的数据集。“媒体资源 ID”是指您的 Google Analytics(分析)媒体资源 ID,可以在 Google Analytics(分析)4 媒体资源的“媒体资源设置”以及 Firebase 中的“应用分析设置”下找到。任何 Google Analytics(分析)4 媒体资源和应用在启用了 BigQuery Export 之后,其数据都会导出到与之对应的数据集中。

如果启用了“每天”导出选项,系统会每天在每个数据集中创建一个名为 events_YYYYMMDD 的表。

如果启用了“流式”导出选项,系统会创建一个名为 events_intraday_YYYYMMDD 的表。此表会随着全天事件的记录而不断填充。一旦 events_YYYYMMDD 完成,此表将在每天结束时删除。

并非所有设备都会在触发事件的同一天将其数据发送给 Google Analytics(分析)。考虑到这种延迟,Google Analytics(分析)会在更新每天的表 (events_YYYYMMDD) 时记录在事件触发日期后的三天内发送的事件。无论相应数据是否延迟,事件都具有正确的时间戳。如果数据在三天之后才送达,相应事件将不会被记录。

 

如果您使用的是 BigQuery 沙盒,则不会在当日导入事件,并且受其他限制约束

如果您想在当日导入,请从沙盒升级

下面列出了导出结果中的各个列。

字段名称 数据类型 说明
应用    
app_info RECORD 包含应用信息的一条记录。
app_info.id STRING 应用的程序包名称或软件包 ID。
app_info.firebase_app_id STRING 与应用关联的 Firebase 应用 ID。
app_info.install_source STRING 表示该应用是通过哪个应用商店安装的。
app_info.version STRING 应用的版本名称 (Android) 或短软件包版本号。
设备    
device RECORD 一条包含设备信息的记录。
device.category STRING 设备类别(移动设备、平板电脑、桌面设备)。
device.mobile_brand_name STRING 设备的品牌名称。
device.mobile_model_name STRING 设备的型号名称。
device.mobile_marketing_name STRING 设备的宣传名称。
device.mobile_os_hardware_model STRING 直接从操作系统检索到的设备型号信息。
device.operating_system STRING 设备的操作系统。
device.operating_system_version STRING 操作系统版本。
device.vendor_id STRING IDFV(仅在未收集到 IDFA 时存在)。
device.advertising_id STRING 广告 ID/广告标识符 (IDFA)。
device.language STRING 操作系统语言。
device.time_zone_offset_seconds INTEGER 与格林尼治标准时间 (GMT) 的时差(以秒为单位)。
device.is_limited_ad_tracking BOOLEAN

设备的“限制广告跟踪”设置。

在 iOS14+ 上,如果 IDFA 不为零,则返回 false。

device.web_info.browser STRING 用户浏览内容时所用的浏览器。
device.web_info.browser_version STRING 用户浏览内容时所用浏览器的版本。
device.web_info.hostname STRING 与所记录事件相关联的主机名。
数据流和平台    
stream_id STRING 数据流的数字 ID。
platform STRING 应用的开发平台。
用户    
user_first_touch_timestamp INTEGER 用户首次打开应用或访问网站的时间(以微秒为单位)。
user_id STRING 通过 setUserId API 设置的用户 ID。
user_pseudo_id STRING 用户的假名 ID(例如,应用实例 ID)。
user_properties RECORD 一条重复记录,包含使用 setUserProperty API 设置的用户属性。
user_properties.key STRING 用户属性的名称。
user_properties.value RECORD 一条包含用户属性值的记录。
user_properties.value.string_value STRING 用户属性的字符串形式值。
user_properties.value.int_value INTEGER 用户属性的整数值。
user_properties.value.double_value FLOAT 用户属性的双精度值。
user_properties.value.float_value FLOAT 此字段目前尚未使用。
user_properties.value.set_timestamp_micros INTEGER 上次设置用户属性的时间(以微秒为单位)。
user_ltv RECORD 一条记录,包含用户的生命周期价值信息。当日汇成的表中不会填充此字段。
user_ltv.revenue FLOAT 此用户的生命周期价值(收入)。当日汇成的表中不会填充此字段。
user_ltv.currency STRING 此用户的生命周期价值(币种)。当日汇成的表中不会填充此字段。
广告系列   注意:traffic_source 归因以跨渠道最终点击为依据。如果用户在安装应用后与后续广告系列进行互动,traffic_source 的值不会改变。
traffic_source RECORD 最先获取到用户的流量来源的名称。当日汇成的表中不会填充此字段。
traffic_source.name STRING 最先获取到用户的营销广告系列的名称。当日汇成的表中不会填充此字段。
traffic_source.medium STRING 最先获取到用户的媒介名称(付费搜索、自然搜索、电子邮件等)。当日汇成的表中不会填充此字段。
traffic_source.source STRING 最先获取到用户的广告联盟的名称。当日汇成的表中不会填充此字段。
地理位置    
geo RECORD 用户的地理位置信息记录。
geo.continent STRING 报告的事件所在的大洲(基于 IP 地址)。
geo.sub_continent STRING 报告的事件所在的次大陆(基于 IP 地址)。
geo.country STRING 报告的事件所在的国家/地区(基于 IP 地址)。
geo.region STRING 报告的事件所在的区域(基于 IP 地址)。
geo.metro STRING 报告的事件所在的都市圈(基于 IP 地址)。
geo.city STRING 报告的事件所在的城市(基于 IP 地址)。
事件    
event_date STRING 此事件的记录日期(应用所注册时区的 YYYYMMDD 格式)。
event_timestamp INTEGER 客户端中记录此事件的时间(以微秒为单位,采用世界协调时间)。
event_previous_timestamp INTEGER 客户端中上一次记录此事件的时间(以微秒为单位,采用世界协调时间)。
event_name STRING 事件名称。
event_params RECORD 与此事件关联的参数的重复记录。
event_params.key STRING 事件参数的键。
event_params.value RECORD 事件参数值的记录。
event_params.value.string_value STRING 事件参数的字符串值。
event_params.value.int_value INTEGER 事件参数的整数值。
event_params.value.double_value FLOAT 事件参数的双精度值。
event_params.value.float_value FLOAT 事件参数的浮点值。此字段目前尚未使用。
event_value_in_usd FLOAT 事件的“value”参数在换算至以美元为单位后的值。
event_bundle_sequence_id INTEGER 上传这些事件的软件包的序列 ID。
event_server_timestamp_offset INTEGER 收集时间和上传时间之间的时间戳偏移量(以微秒为单位)。
电子商务    
ecommerce RECORD 一条包含电子商务相关信息的记录。
ecommerce.total_item_quantity INTEGER 此事件中的商品总数,即 items.quantity 的总和。
ecommerce.purchase_revenue_in_usd FLOAT 此事件的购买收入,以美元标准单位表示。仅为购买事件填充。
ecommerce.purchase_revenue FLOAT 此事件的购买收入,以本地货币标准单位表示。仅为购买事件填充。
ecommerce.refund_value_in_usd FLOAT 此事件中的退款金额,以美元标准单位表示。仅为退款事件填充。
ecommerce.refund_value FLOAT 此事件中的退款金额,以本地货币标准单位表示。仅为退款事件填充。
ecommerce.shipping_value_in_usd FLOAT 此事件中的运费,以美元标准单位表示。
ecommerce.shipping_value FLOAT 此事件中的运费,以本地货币表示。
ecommerce.tax_value_in_usd FLOAT 此事件中的税费,以美元标准单位表示。
ecommerce.tax_value FLOAT 此事件中的税费,以本地货币标准单位表示。
ecommerce.transaction_id STRING 电子商务交易的交易 ID。
ecommerce.unique_items INTEGER 此事件中非重复商品的数量(根据 item_id、item_name 和 item_brand 确定)。
商品    
items RECORD 一条重复记录,包含此事件中所含的商品。
items.item_id STRING 商品的 ID。
items.item_name STRING 商品的名称。
items.item_brand STRING 商品所属品牌。
items.item_variant STRING 商品的款式。
items.item_category STRING 商品所属类别。
items.item_category2 STRING 商品所属的子类别。
items.item_category3 STRING 商品所属的子类别。
items.item_category4 STRING 商品所属的子类别。
items.item_category5 STRING 商品所属的子类别。
items.price_in_usd FLOAT 商品的价格,以美元标准单位表示。
items.price FLOAT 商品的价格(以本地货币表示)。
items.quantity INTEGER 商品的数量。如果未指定,则数量会设置为 1。
items.item_revenue_in_usd FLOAT 此商品的收入,计算方式为:price_in_usd * 数量。仅为采用美元标准单位的购买事件填充。
items.item_revenue FLOAT 此商品的收入,计算方式为:价格 * 数量。仅为采用本地货币标准单位的购买事件填充。
items.item_refund_in_usd FLOAT 此商品的退款金额,计算方式为:price_in_usd * 数量。仅为采用美元标准单位的退款事件填充。
items.item_refund FLOAT 此商品的退款金额,计算方式为:价格 * 数量。仅为采用本地货币标准单位的退款事件填充。
items.coupon STRING 适用于此商品的优惠券代码。
items.affiliation STRING 用于指定供应公司或实体店位置的商品关联商户。
items.location_id STRING 与商品相关的营业地点。
items.item_list_id STRING 商品向用户展示时所在列表的 ID。
items.item_list_name STRING 商品向用户展示时所在列表的名称。
Items.item_list_index STRING 商品在列表中的位置。
items.promotion_id STRING 商品促销活动的 ID。
items.promotion_name STRING 商品促销活动的名称。
items.creative_name STRING 在促销位置采用的广告素材的名称。
items.creative_slot STRING 广告素材位置的名称。
网页    
web_info RECORD 网站数据的信息记录。
隐私权信息  

以下字段基于您在使用意见征求模式时的用户意见征求状态

privacy_info.ads_storage STRING

是否针对用户启用了广告定位。

可能的值:Yes、No、Unset

privacy_info.analytics_storage STRING

是否针对用户启用了 Google Analytics(分析)存储机制。

可能的值:Yes、No、Unset

privacy_info.uses_transient_token STRING

网站用户是否拒绝了 Google Analytics(分析)使用存储空间的请求,以及开发者是否启用了在没有 Cookie 的情况下基于服务器数据中的临时令牌进行衡量的功能。

可能的值:Yes、No、Unset

 

表中的每一行都与一个事件相对应。每个事件都有许多特定于事件的嵌套参数及相应的值。例如,page_view 事件类似于如下所示:

event_date event_timestamp event_name event_params_key event_params_value_string_value
20220222 1643673600483790 page_view page_location https://example.com
      page_title Home
      ga_session_id null
      来源 google
      page_referrer https://www.google.com
      <parameters...> <values...>

 

将 SDK 更新到 Android 17.2.5(或更高版本)和/或 iOS 16.20.0(或更高版本)时的注意事项

如果您使用的是旧版 SDK 并计划升级到 Android 17.2.5(或更高版本)和/或 iOS 16.20.0(或更高版本),则应考虑以下事项:

  • 要使用当前的 BigQuery Export 架构,您必须将 SDK 升级到 Android 17.2.5(或更高版本)和/或 iOS 16.20.0(或更高版本)。使用早期版本的 SDK 时,导出的数据将反映旧架构
  • 升级后,您将只能在重复 items 数组中访问商品数据;商品数据将不再在标准事件参数中可用,因为它低于这些 SDK 版本。
  • 进行此项更改是为了支持多产品分析。
  • 您可能需要因此调整对商品/产品数据的引用。
使用以下脚本将现有的 BigQuery 数据集从旧版导出架构迁移到新版导出架构
  1. 登录到 Cloud Platform 控制台 > 管理资源页面。
  2. 打开要迁移数据的项目,然后在页面顶部点击激活 Google Cloud Shell
  3. 在该 shell 打开后,将以下脚本复制到一个名为 migration_script.sql 的文件中:
    1. 发送 cat > migration_script.sql 命令。
    2. 将以下脚本复制并粘贴到 shell 中。
    3. Ctrl+D 保存并退出。
    脚本 (migration_script.sql):
      SELECT
      @date AS event_date,
      event.timestamp_micros AS event_timestamp,
      event.previous_timestamp_micros AS event_previous_timestamp,
      event.name AS event_name,
      event.value_in_usd  AS event_value_in_usd,
       user_dim.bundle_info.bundle_sequence_id AS event_bundle_sequence_id,
      user_dim.bundle_info.server_timestamp_offset_micros as event_server_timestamp_offset,
      (
      SELECT
        ARRAY_AGG(STRUCT(event_param.key AS key,
            STRUCT(event_param.value.string_value AS string_value,
              event_param.value.int_value AS int_value,
              event_param.value.double_value AS double_value, 
              event_param.value.float_value AS float_value) AS value))
      FROM
        UNNEST(event.params) AS event_param) AS event_params,
      user_dim.first_open_timestamp_micros AS user_first_touch_timestamp,
      user_dim.user_id AS user_id,
      user_dim.app_info.app_instance_id AS user_pseudo_id,
      "" AS stream_id,
      user_dim.app_info.app_platform AS platform,
      STRUCT( user_dim.ltv_info.revenue AS revenue,
        user_dim.ltv_info.currency AS currency ) AS user_ltv,
      STRUCT( user_dim.traffic_source.user_acquired_campaign AS name,
          user_dim.traffic_source.user_acquired_medium AS medium,
          user_dim.traffic_source.user_acquired_source AS source ) AS traffic_source,
      STRUCT( user_dim.geo_info.continent AS continent,
        user_dim.geo_info.country AS country,
        user_dim.geo_info.region AS region,
        user_dim.geo_info.city AS city ) AS geo,
      STRUCT( user_dim.device_info.device_category AS category,
        user_dim.device_info.mobile_brand_name,
        user_dim.device_info.mobile_model_name,
        user_dim.device_info.mobile_marketing_name,
        user_dim.device_info.device_model AS mobile_os_hardware_model,
        @platform AS operating_system,
        user_dim.device_info.platform_version AS operating_system_version,
        user_dim.device_info.device_id AS vendor_id,
        user_dim.device_info.resettable_device_id AS advertising_id,
        user_dim.device_info.user_default_language AS language,
        user_dim.device_info.device_time_zone_offset_seconds AS time_zone_offset_seconds,
        IF(user_dim.device_info.limited_ad_tracking, "Yes", "No") AS is_limited_ad_tracking ) AS device,
      STRUCT( user_dim.app_info.app_id AS id,
        @firebase_app_id  AS firebase_app_id,
        user_dim.app_info.app_version AS version,
        user_dim.app_info.app_store AS install_source ) AS app_info,
      (
      SELECT
        ARRAY_AGG(STRUCT(user_property.key AS key,
            STRUCT(user_property.value.value.string_value AS string_value,
              user_property.value.value.int_value AS int_value,
              user_property.value.value.double_value AS double_value,
              user_property.value.value.float_value AS float_value,
              user_property.value.set_timestamp_usec AS set_timestamp_micros ) AS value))
      FROM
        UNNEST(user_dim.user_properties) AS user_property) AS user_properties
    FROM
      `SCRIPT_GENERATED_TABLE_NAME`,
      UNNEST(event_dim) AS event
      
  4. 打开一个新 shell,然后将以下 bash 脚本复制到一个名为 migration.sh 的文件中:
    1. 发出 cat > migration.sh 命令
    2. 将以下脚本复制并粘贴到 shell 中。
    3. Ctrl+D 保存并退出。
    修改以下脚本,在其中添加您的 Analytics(分析)媒体资源 ID、BigQuery 项目 ID、Firebase 应用 ID、BigQuery 数据集名称,以及所需数据的开始日期和结束日期。
    脚本 (migration.sh):
    # 项目的 Analytics(分析)媒体资源 ID。可在 Firebase 的 Analytics(分析)设置中找到该 ID。
    PROPERTY_ID=您的 Analytics(分析)媒体资源 ID
    
    # BigQuery Export 项目。
    BQ_PROJECT_ID="您的 BigQuery 项目 ID"(例如:"firebase-public-project")
    
    # 该应用的 Firebase 应用 ID。
    FIREBASE_APP_ID="您的 Firebase 应用 ID"(例如:"1:300830567303:ios:09b1ab1d3ca29bda")
    
    # 供导出使用的数据集。
    BQ_DATASET="供导出使用的 BigQuery 数据集的名称"(例如:"com_firebase_demo_IOS")
    
    # 平台
    PLATFORM="应用平台。ANDROID 或 IOS"
    
    # 您希望运行迁移的日期范围,采用 [START_DATE,END_DATE] 格式(包括开始日期和结束日期)。
    All Web Site DataSTART_DATE=20180324
    END_DATE=20180327
    
    # 请勿修改以下脚本,除非您确定要这么做 :)
    startdate=$(date -d"$START_DATE"  +%Y%m%d) || exit -1
    enddate=$(date -d"$END_DATE"  +%Y%m%d) || exit -1
    
    # 遍历相应日期。
    DATE="$startdate"
    while [ "$DATE" -le "$enddate" ]; do
    
            # 使用以上参数构建的 BQ 表。
            BQ_TABLE="$BQ_PROJECT_ID.$BQ_DATASET.app_events_$DATE"
    
            echo "Migrating $BQ_TABLE"
    
            cat migration_script.sql | sed -e "s/SCRIPT_GENERATED_TABLE_NAME/$BQ_TABLE/g" | bq query \
            --debug_mode \
            --allow_large_results \
            --noflatten_results \
            --use_legacy_sql=False \
            --destination_table analytics_$PROPERTY_ID.events_$DATE \
            --batch \
            --append_table \
            --parameter=firebase_app_id::$FIREBASE_APP_ID \
            --parameter=date::$DATE \
            --parameter=platform::$PLATFORM \
            --project_id=$BQ_PROJECT_ID
    
    
            temp=$(date -I -d "$DATE + 1 day")
            DATE=$(date -d "$temp" +%Y%m%d)
    
    done
    exit
    
    # 脚本结束
    
    
  5. 打开一个新 shell,然后发送 bash migration.sh 命令

 

旧版导出架构

user_dim

字段名称 数据类型 说明
user_dim RECORD 用户维度记录。
user_dim.user_id STRING 通过 setUserId API 设置的用户 ID。
user_dim.first_open_timestamp_micros INTEGER 用户首次打开应用的时间(以微秒为单位)。
user_dim.user_properties RECORD 一条重复记录,包含使用 setUserProperty API 设置的用户属性。
user_dim.user_properties.key STRING 用户属性的名称。
user_dim.user_properties.value RECORD 用户属性相关信息的记录。
user_dim.user_properties.value.value RECORD 一条包含用户属性值的记录。
user_dim.user_properties.value.value.string_value STRING 用户属性的字符串形式值。
user_dim.user_properties.value.value.int_value INTEGER 用户属性的整数值。
user_dim.user_properties.value.value.double_value FLOAT 用户属性的双精度值。
user_dim.user_properties.value.set_timestamp_usec INTEGER 上次设置用户属性的时间(以微秒为单位)。
user_dim.user_properties.value.index INTEGER 用户属性的索引值 (0-24)。
user_dim.device_info RECORD 一条包含设备信息的记录。
user_dim.device_info.device_category STRING 设备类别(移动设备、平板电脑、桌面设备)。
user_dim.device_info.mobile_brand_name STRING 设备的品牌名称。
user_dim.device_info.mobile_model_name STRING 设备的型号名称。
user_dim.device_info.mobile_marketing_name STRING 设备的宣传名称。
user_dim.device_info.device_model STRING 设备型号。
user_dim.device_info.platform_version STRING 操作系统版本。
user_dim.device_info.device_id STRING IDFV(仅在 IDFA 不可用时显示)。
user_dim.device_info.resettable_device_id STRING 广告 ID/广告标识符 (IDFA)。
user_dim.device_info.user_default_language STRING 操作系统语言。
user_dim.device_info.device_time_zone_offset_seconds INTEGER 与格林尼治标准时间 (GMT) 的时差(以秒为单位)。
user_dim.device_info.limited_ad_tracking BOOLEAN 设备的“限制广告跟踪”设置。
user_dim.geo_info RECORD 用户的地理位置信息记录。
user_dim.geo_info.continent STRING 报告的事件所在的大洲(基于 IP 地址)。
user_dim.geo_info.country STRING 报告的事件所在的国家/地区(基于 IP 地址)。
user_dim.geo_info.region STRING 报告的事件所在的区域(基于 IP 地址)。
user_dim.geo_info.city STRING 报告的事件所在的城市(基于 IP 地址)。
user_dim.app_info RECORD 一条包含应用信息的记录。
user_dim.app_info.app_version STRING 应用的版本名称 (Android) 或短软件包版本号。
user_dim.app_info.app_instance_id STRING 这个应用实例的专属 ID。
user_dim.app_info.app_store STRING 此应用是通过哪个应用商店安装的。
user_dim.app_info.app_platform STRING 此应用在哪个平台上运行。
user_dim.traffic_source RECORD 用于获取用户的流量来源的名称。当日汇成的表中不会填充此字段。
user_dim.traffic_source.user_acquired_campaign STRING 获取了用户的营销广告系列的名称。当日汇成的表中不会填充此字段。
user_dim.traffic_source.user_acquired_medium STRING 获取了用户的媒介名称(付费搜索、自然搜索、电子邮件等)。当日汇成的表中不会填充此字段。
user_dim.traffic_source.user_acquired_source STRING 获取了用户的广告联盟的名称。当日汇成的表中不会填充此字段。
user_dim.bundle_info RECORD 与上传这些事件的软件包相关的信息记录。
user_dim.bundle_info.bundle_sequence_id INTEGER 上传这些事件的软件包的序列 ID。
user_dim.ltv_info RECORD 关于此用户的生命周期价值信息的记录。当日汇成的表中不会填充此字段。
user_dim.ltv_info.revenue FLOAT 此用户的生命周期价值(收入)。当日汇成的表中不会填充此字段。
user_dim.ltv_info.currency STRING 此用户的生命周期价值(币种)。当日汇成的表中不会填充此字段。
 

event_dim

字段名称 数据类型 说明
event_dim RECORD 关于此软件包中的事件的重复信息记录。
event_dim.date STRING 记录此事件的日期(应用所注册的时区的 YYYYMMDD 格式)。
event_dim.name STRING 此事件的名称。
event_dim.params RECORD 与此事件关联的参数的重复记录。
event_dim.params.key STRING 事件参数的键。
event_dim.params.value RECORD 事件参数值的记录。
event_dim.params.value.string_value STRING 事件参数的字符串值。
event_dim.params.value.int_value INTEGER 事件参数的整数值。
event_dim.params.value.double_value FLOAT 事件参数的双精度值。
event_dim.timestamp_micros INTEGER 客户端中记录此事件的时间(以微秒为单位,采用世界协调时间)。
event_dim.previous_timestamp_micros INTEGER 客户端中上一次记录此事件的时间(以微秒为单位,采用世界协调时间)。
该内容对您有帮助吗?
您有什么改进建议?

需要更多帮助?

登录可获取更多支持选项,以便快速解决您的问题

搜索
清除搜索查询
关闭搜索框
Google 应用
主菜单
搜索支持中心
true
69256
false
false