Google 代码 API 参考文档

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

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

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

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

参数范围

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

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

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

参数优先级

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

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// 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>' });

`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。

为了演示如何发送其他配置信息，我们在以下示例中配置了将数据发送到 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', {campaign_name: 'Spring_Sale'});

gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
  // Do something with currency value you set earlier.
})

`set`

您可以使用 set 命令来定义与网页上每个后续事件相关联的参数。

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

例如，您可以共享广告系列参数，以便同一网页上的多个代码可以访问这些参数。

以下示例展示了如何针对黑色星期五购物活动设置广告系列名称和 ID。由于您已使用 set，因此所有其他代码（例如 GA4 事件代码或 Google Ads 再营销代码）均可访问这些数据。

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

`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'`	启用与广告相关的存储机制，例如 Cookie（网站）或设备标识符（应用）。
`ad_user_data`	`'granted'` \| `'denied'`	设置出于广告目的向 Google 发送用户数据的用户意见征求机制。
`ad_personalization`	`'granted'` \| `'denied'`	设置个性化广告的用户意见征求机制。
`analytics_storage`	`'granted'` \| `'denied'`	启用与分析（例如访问时长）相关的存储机制，例如 Cookie（网站）或应用标识符（应用）。
`wait_for_update`	任意正整数	设置等待意见征求更新调用的时间（以毫秒为单位）。