本頁面由 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 代碼片段下方若要瞭解如何在頁面中，請參閱安裝指南。

參數範圍

您可以將參數值的範圍限定為個別事件，凡是傳送到特定 <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> 是用來識別命中目標的專屬 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)

引數	類型	範例	說明
<target>	`string`	G-XXXXXXXXXX	要從哪個目標擷取值。
<field_name>	FieldName	client_id	要取得的欄位名稱。
回呼	`Function`	`(field) => console.log(field)`	將使用要求的欄位叫用的函式，或 `undefined`。

FieldName

欄位名稱可以是您使用 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', '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 指令會觸發兩個建議事件 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'`	啟用與廣告相關的儲存功能，例如 Cookie (網站) 或裝置 ID (應用程式)。
`ad_user_data`	`'granted'` \| `'denied'`	設定同意聲明狀態，指明可否基於廣告用途將使用者資料傳送給 Google。
`ad_personalization`	`'granted'` \| `'denied'`	設定個人化廣告的同意聲明。
`analytics_storage`	`'granted'` \| `'denied'`	啟用與數據分析相關的儲存功能，例如 Cookie (網站) 或應用程式 ID (應用程式)，例如造訪時間長度。
`wait_for_update`	任何正整數	設定等待同意聲明更新呼叫的時間 (以毫秒為單位)。