Google 代碼 API 參考資料

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

gtag(<command>, <command parameters>);
  • <command> 是下列其中一個指令：
  • <command parameters> 是您可以傳遞至 gtag() 的參數。指令參數會因指令而異，請參閱下方的指令參考資料。

只要指令出現在 Google 代碼程式碼片段下方，您就可以在網頁上的任何位置叫用 gtag() 指令。如要瞭解如何在網頁中加入程式碼片段，請參閱安裝指南。

參數範圍

您可以將參數值範圍設為個別事件、傳送至特定 <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 擷取值所在欄位的名稱。
callback Function (field) => console.log(field)

將使用要求欄位叫用的函式 (如果欄位未設定則為 undefined)。

FieldName

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

欄位名稱 支援的目標
client_id
  • Google Analytics 4
session_id
  • Google Analytics 4
session_number
  • Google Analytics 4
gclid
  • Google Ads
  • 泛光燈

範例

將值放入 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> 可以是下列任一項：

  • 建議事件。每個建議事件都可以採用建議參數。
  • 自訂事件。自訂事件是指您自行編造的任意事件名稱， 以及任意參數。詳情請參閱「設定事件」。

<event_params> 是一或多個參數值組合。請以半形逗號分隔每個鍵/值組合。

下列 event 指令會觸發建議事件 screen_view，並包含兩個參數：app_name 和 screen_name。

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

使用 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 任何正整數 設定等待同意聲明更新呼叫的時間 (以毫秒為單位)。