傳送 User-ID

User-ID 是您指派給個別使用者的專屬 ID。 本指南說明如何將使用者 ID 傳送至 Google Analytics，以便連結不同工作階段、裝置和平台的使用者行為。

如要進一步瞭解 User-ID 功能，請參閱「評估跨平台活動」。如要瞭解如何為應用程式設定 User-ID，請參閱「設定 User-ID」。

user_id 參數是設定參數，不是自訂使用者屬性或標準事件參數。user_id 是保留的系統參數，專門用於跨裝置和工作階段識別已驗證的使用者。請勿將其設為自訂使用者屬性 (例如在 user_properties 物件中或 Google 代碼管理工具代碼的「使用者屬性」gtag.js部分)，也不要在 Analytics 使用者介面中將其註冊為自訂維度。 同樣地，請勿在個別事件中將其做為事件層級參數傳遞。 請改為只將 user_id 設為設定參數，方法如下。


事前準備

傳送使用者 ID 前，請務必完成下列事項：

傳送 User-ID

您為 user_id 傳送的值取決於使用者狀態：

  • 使用者從未登入：請勿傳送 user_id 參數。
  • 使用者已登入：傳送使用者 ID。
  • 使用者先登入，然後登出：傳送 null。

如要將 User-ID 傳送到 Analytics，請在網站的每個網頁中，將 user_id 參數加入 config 指令：

if (/* your logic for determining if the user is signed in */) {
  gtag('config', 'TAG_ID', {
    'user_id': 'USER_ID'
  });
} else if (/* your logic for determining if the user signed out */) {
  gtag('config', 'TAG_ID', {
    'user_id': null
  });
} else {
  // Do nothing if the user never signed in.
}
  1. 將 TAG_ID 替換為代碼 ID。
  2. 將註解替換成檢查使用者是否已登入，以及使用者是否已登入但隨後登出的檢查。
  3. 如果使用者已登入，請將 USER_ID 替換成使用者 ID。
  4. 使用者登出時，請將 user_id 設為 null。請勿傳送空字串 ("")、空白字串 (" ") 或以引號括住的字詞 "null" 或 "NULL"。

在初始化後設定 User-ID

在許多情況下，Google 代碼首次初始化時，user_id 並不為人所知。舉例來說，使用者可能造訪您的網站，但稍後才登入。

如要在初始網頁載入後設定或更新 user_id，請使用 gtag('set') 指令。這個指令會為網頁上後續的所有事件設定 user_id，建議您採用這種做法，而非使用 gtag('config')。

在登入時設定使用者 ID

使用者成功登入後，請呼叫 gtag('set')，將 ID 與日後的事件建立關聯：

// Example function called after successful login
function handleUserLogin(userId) {
  if (userId) {
    gtag('set', {'user_id': userId});
    console.log('User ID set for GA:', userId);

    // You can also send a login event
    gtag('event', 'login', { method: 'your_login_method' });
  }
}

// Example usage:
// handleUserLogin('12345_user');

登出時清除使用者 ID

使用者登出時，您應將 user_id 的值設為 null，藉此清除 user_id：

// Example function called after logout
function handleUserLogout() {
  gtag('set', {'user_id': null});
  console.log('User ID cleared for GA.');

  // You can also send a logout event
  gtag('event', 'logout');
}

// Example usage:
// handleUserLogout();

使用 gtag('set') 可確保 user_id 在整個使用者工作階段中獲得正確管理，即使使用者登入狀態在網頁載入後有所變更，也能反映使用者目前的登入狀態。

Google Analytics 如何使用 User-ID

將 user_id 值傳送至 Google Analytics 後，系統會使用這些值執行下列操作：

  • 整合使用者歷程：連結已登入使用者的活動，包括不同工作階段、裝置和平台。
  • 提升使用者人數準確度：提供更準確且去除重複的使用者指標。
  • 啟用分析：
    • 根據登入狀態分析活動：使用「已使用 User-ID 登入」等維度，在標準報表中建立比較項目，或在探索中建立區隔。
    • 支援使用者多層檢視探索技巧，讓您細查個別使用者的活動時間軸。

重要注意事項

  • 請勿為使用者 ID 建立自訂維度：您不應將 user_id 登錄為以使用者為範圍的自訂維度。這是重要的最佳做法。這麼做會建立不必要的高基數維度，嚴重影響報表效能，導致資料匯總到「(其他)」列，並耗用自訂維度配額。內建的 User-ID 功能會處理使用者縫合作業。詳情請參閱「User-ID 的最佳做法」。

  • 將 user_id 設為配置設定，而非使用者屬性或事件參數： 由於 user_id 是保留的系統參數，因此只能做為配置或設定參數 (使用 gtag() config 或 set 指令，或是 Google 代碼管理工具的 Google 代碼配置設定)。請勿將其設為自訂使用者屬性、在user_properties設定物件中傳遞，或在個別事件中以事件層級參數的形式傳送。

  • 標準報表與探索中的直接 ID 可見度：為維護隱私權及管理基數，原始user_id值不會在標準報表或大多數探索 (例如任意形式) 中做為標準維度提供。不過，您可以在「使用者多層檢視」探索範本中，查看已登入使用者的原始 user_id，位置在標示為「有效使用者 ID」的欄下方。

  • 存取原始 User-ID：如要使用原始 user_id 值進行分析，建議使用 Google Analytics 4 BigQuery Export。匯出的資料中會包含 user_id 欄位。

如要確保系統使用 User-ID 資料，並在使用者多層檢視中顯示這些資料，請確認資源的報表識別資訊已設為「混合」或「已觀測」。

上一頁
新增參數
下一頁
評估例外狀況