本頁面由 Cloud Translation API 翻譯而成。

Google tag API 參考資料

Google 代碼 (gtag.js) API 包含一個 gtag() 函式，其語法如下：

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

<command> 是下列其中一個指令：
- config
- get
- set
- event
- consent
<command parameters> 是您可以傳遞至 gtag() 的參數。指令參數會因指令而異；請參閱下方的指令參考資料。

只要指令出現在 Google 代碼片段下方，即可在網頁上的任何位置叫用 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', 'TAG_ID');

其中「TAG_ID」是 Google 代碼的代碼 ID。

為示範如何傳送其他設定資訊，以下示範如何設定代碼傳送資料至 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)

引數	類型	範例	說明
<目標>	`string`	UA-XXXXXXXX-Y	用來擷取值的指定目標。
<field_name>	欄位名稱	client_id	要取得的欄位名稱。
回呼	`Function`	`(field) => console.log(field)`	系統會透過要求的欄位叫用這個函式，如未設定，則會傳回 `undefined`。

欄位名稱

欄位名稱可以是您使用 gtag('set') 指令設定的自訂欄位名稱，或下列其中一個值：

欄位名稱	支援的目標
client_id	Google Analytics (分析) 4 Google Analytics (分析) 通用 Analytics (分析)
session_id	Google Analytics (分析) 4
gclid	Google Ads 泛光燈

範例

發揮承諾的價值

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 事件則會不含任何參數。在第二個示例中， login 和 share 都會傳遞 method 的 'Google' 值。

`event`

使用 event 指令傳送事件資料。

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

<event_name> 為以下其中一種：

建議事件。每個建議事件可以採用建議參數。
自訂事件。自訂事件是指包含任意 (即自訂) 參數的任意事件名稱。例如，請參閱在 Google Analytics (分析) 中如何使用自訂事件。

<event_params> 是一或多個參數值組合。每對組合之間以半形逗號分隔。

下列 event 指令會透過兩個參數啟動建議的事件 screen_view：app_name 和 screen_name。

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