此页面由 Cloud Translation API 翻译。

Google 代码 API 参考文档

Google 代码 (gtag.js) API 由单个函数 (gtag()) 构成，其语法如下：

gtag(<command>, <command parameters>);

<command> 是以下命令之一：
- config
- get
- set
- event
- consent
<command parameters> 是您可以传递给 gtag() 的参数。命令参数因命令而异；请参阅下文中的命令参考。

只要您的 gtag() 命令显示在 Google 代码段之后，您就可以在网页上的任何位置调用这些命令。如需了解如何向网页添加代码段，请参阅添加指南。

`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', 'TAG_ID');

其中，“TAG_ID”是 Google 代码的代码 ID。

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

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

`get`

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

gtag('get', '<target>', '<field_name>', callback)

参数名	类型	示例	说明
<target>	`string`	G-XXXXXXXXXX	要从中提取值的目标。
<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', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

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

获取您设置的值

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

gtag('get', 'G-XXXXXXXXXX', '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');

and

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

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

`event`

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

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

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

推荐事件。每个推荐事件都可以采用推荐参数。
自定义事件。自定义事件的事件名称是任意的，其参数也是任意的（即自定义的）。有关示例，请参阅自定义事件在 Google Analytics（分析）中的用法。

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

下面的 event 命令会触发带有两个参数（app_name 和 screen_name）的推荐事件 screen_view。

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

`consent`

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

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

如需详细了解这些参数配置的行为，请参阅帮助中心内的意见征求部分。

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

支持以下 <consent_params>：

字段名称	允许的值
`ad_storage`	`'granted'` \| `'denied'`
`analytics_storage`	`'granted'` \| `'denied'`
`wait_for_update`	任意正整数

参数范围

您可以将参数值的范围限定为单个事件、发送到特定 <TARGET_ID> 的所有事件，或全局范围内的所有事件。其实现方式是使用 event、config 和 set 命令。

在一个范围内设置的参数值不会用于修改针对不同范围内的同一参数设置的值。在下面的示例中，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>' });