gtag.js API 参考

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

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

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

config

用于向目标添加其他配置信息。这通常是针对具体产品的配置信息,例如 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-TRACKING_ID');

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

gtag('config', 'GA-TRACKING_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

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

参数范围

参数值的范围既可以是单个事件,也可以是发送到特定 <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>' });