gtag.js API 参考文档

gtag.js API 由单个函数 (gtag()) 构成,其语法如下:

gtag(<command>, <command parameters>);
  • <command> 是以下命令之一:
  • <command parameters> 是要传递给 gtag() 的参数。命令参数因命令而异;请参阅下文中的命令参考。

只要您的 gtag 命令显示在全局代码段之后,您就可以在网页上的任何位置调用该命令。要了解如何向网页添加全局代码段,请参阅代码段指南

config

用于向目标添加其他配置信息。这通常是针对特定产品的配置信息,例如 Google Ads 或 Google Analytics(分析)等产品。

gtag('config', '<TARGET_ID>', {<additional_config_info>});

<TARGET_ID> 是唯一标识命中目标(如 Google Analytics(分析)媒体资源或 Google Ads 帐号)的标识符。<additional_config_info> 是一个或多个“参数-值”对。

以下这则示例配置了将数据发送到 Google Ads 帐号的代码:

gtag('config', 'AW-CONVERSION_ID');

同样,config 命令也可以用于 Google Analytics(分析):

gtag('config', 'GA_MEASUREMENT_ID');

为了演示如何发送其他 config 信息,我们在以下示例中配置了将数据发送到 Google Analytics(分析)帐号的代码:其中 send_page_view 参数传递的值为 false,而 groups 参数传递的值为 'agency'

gtag('config', 'GA_MEASUREMENT_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

get

让您可以通过 gtag.js 获取各种值,包括使用 set 命令设置的值。

gtag('get', '<target>', '<field_name>', callback)
参数 类型 示例 说明
<target> string UA-XXXXXXXX-Y

要从中提取值的目标。

<field_name> FieldName client_id 要获取的字段的名称。
callback Function (field) => console.log(field)

可通过请求字段调用的函数,如果未设置,则为 undefined

FieldName

字段名称可以是您使用 gtag('set') 命令设置的自定义字段的名称,也可以是以下值之一:

字段名称 支持的目标
client_id
  • Google Analytics(分析)4
  • Google Analytics(分析)Universal Analytics
session_id
  • Google Analytics(分析)4
gclid
  • Google Ads
  • Floodlight

示例

将值添加到 Promise

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

将事件发送到 Measurement Protocol

gtag('get', 'UA-XXXXXXXX-Y', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

获取您设置的值

gtag('set', {currency: 'USD'});

gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

set

用于设置始终存在于网页上的所有后续 gtag() 调用中的值。

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

<parameter-value-pair> 是一个键名,还是一个会始终存在于所有 gtag() 调用中的值。例如,针对网页上所有后续事件,下面的代码将 country 的值设置为 'US',将 currency 的值设置为 'USD'

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

使用 set 命令不同于直接将值传递给 event 命令。如果您直接将值传递给 event 命令,这些值仅会应用到正在被触发的事件。但是如果您使用 set,这些值会始终存在于当前网页上,且会随所有后续事件传递。为进一步说明这一点,我们来比较以下两个示例:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

在第一个示例中,login 事件会在 method 值为 'Google' 时传递,而 share 事件无需任何参数即可传递。在第二个示例中,loginshare 均会在 method 值为 'Google' 时传递。

event

使用 event 命令可发送事件数据。

gtag('event', '<event_name>', {<event_params>});

<event_name> 是以下任何一种事件:

<event_params> 是一个或多个“参数-值”对。每个“参数-值”对均以英文逗号分隔。

下面的 event 命令会触发带有两个参数(app_namescreen_name)的推荐事件 screen_view

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

使用 consent 命令配置意见征求方式。

gtag('consent', {<consent_arg>}, {<consent_params>});

如需详细了解这些参数配置的行为,请参阅帮助中心内的意见征求部分。如需详细了解如何根据用户意见调整代码行为,请参阅根据用户意见调整代码行为

<consent_arg>'default''update' 中的一个。'default' 用于设置应使用的默认意见征求参数,而 'update' 用于在用户表示同意后更新这些参数。

支持以下 <consent_params>

字段名称 允许的值
ad_storage 'allowed' | 'denied'
analytics_storage 'allowed' | 'denied'
wait_for_update 任意正整数。指定等待时间(以毫秒为单位)。

参数范围

参数值的范围既可以是单个事件,也可以是发送到特定 <TARGET_ID> 的所有事件,还可以是全局范围内的所有事件。其实现方式是使用 eventconfigset 命令。

在一个范围内设置的参数值不会用于修改针对不同范围内的同一参数设置的值。在下面的示例中,config 命令不会修改先前使用 set 命令分配的 currency 的全局值。两个命令执行完毕后,currency 的全局值仍然是 'EUR'

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });

参数优先级

如果对不同范围内的同一参数分配了不同的值,则系统在处理事件时只会使用一个值。范围限定为 event 的参数值优先于范围限定为 config 的参数,而 config 参数优先于使用 set 的全局范围参数。

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });