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

Private State Tokens 開發人員指南

使用者過去曾使用第三方 Cookie 來儲存及傳達資訊使用者狀態，例如登入狀態、裝置相關資訊或使用它們的已知和可信任狀態舉例來說使用者已透過單一登入 (SSO) 登入，無論使用者是否使用特定類型的相容應用程式互動、使用者的身分以及受信任的使用者取代為第三方 Cookie 支援功能即將淘汰，因此，在這些應用情境中，我們必須取得其他支援。

Private State Tokens 可用於在網路上分享資訊藉由控管能實際取得的資料量，保障隱私權共用。

私密狀態權杖 (舊稱「信任權杖」) 可讓使用者信任使用者的網站在不同背景間傳達的真實性防範詐欺行為，區分機器人和真人，以免被動追蹤。

本文件將概略說明導入非公開狀態的技術細節權杖 (PST)。如需更詳細的大綱，請參閱 PST 總覽。

PST 的學習流程。 — PST 學習程序：這個過程包含多個步驟，從瞭解 API 開始，並制定自己的權杖策略 (更多產品或業務相關活動)。之後，技術階段會說明如何在本機環境中進行示範，然後用於實際用途。

私密狀態權杖的運作方式為何？

在 PST 中，需要瞭解的重點關係在於發卡機構和兌換者。核發機構和兌換者可以隸屬於同一間公司。

Issuer：這些實體具備使用者的信號 (用於例如該使用者是否為機器人) 儲存在使用者裝置上的權杖 (詳情請參閱下一節)。
兌換者：這些實體可能沒有使用者的信號，必須瞭解他們的相關資訊 (例如使用者是否為機器人要求核發發卡機構的代碼，瞭解以及使用者的信任度

每次與 PST 互動時，發卡機構和兌換者必須共同合作才能分享網路上的信號這些信號是較不詳細的值足以識別個人

我適合使用私密狀態權杖嗎？

負責做出信任決策，並希望以這些資訊做為公司行號資訊的公司這些背景資訊都可能受益於 PST。如要進一步瞭解可能的用途太平洋標準時間請參閱 PST 應用實例說明文件

核發及兌換代碼

導入 PST 時分為三個階段：

核發符記
兌換代碼
兌換記錄轉送

在第一階段，系統會將權杖發給瀏覽器 (通常在經過某種要求後驗證)。在第二階段中，另一個實體會提出兌換請求為讀取該權杖值而核發的權杖。在這邊階段，兌換方會收到兌換記錄 (RR)，包含在權杖中接著，兌換的一方可使用該記錄做為使用者認證。

私密狀態權杖的基本流程。 — 序列圖：此圖顯示 PST 在實際情境下的基本使用情境，其中兩個網站在交換特定 Chrome 執行個體相關信號的情況下。這兩個網站會在不同時刻執行核發和兌換作業，以便在兩者之間交換受信任的信號。

制定權杖策略

如要定義權杖策略，您需要瞭解 PST 的重要概念 (權杖) 變數、行為和限制思考一下這些因素可能的應用方式。

權杖和兌換記錄：這兩者之間的關係為何？

每個頂層網站和發行者最多可以儲存 500 個權杖。另外，每個權杖都有中繼資料，會指出核發者用於核發憑證的金鑰。沒錯能否根據顧客在兌換期間決定兌換代碼上傳資料集之後，您可以運用 AutoML 自動完成部分資料準備工作使用者裝置上的瀏覽器會將 PST 資料儲存在內部，只能透過 PST API 存取

代碼兌換後，兌換記錄 (RR) 就會儲存在裝置上。這個儲存空間可做為日後兌換的快取。最多只能上傳兩個每 48 小時兌換一次權杖 (每部裝置、網頁和核發者)。新的兌換呼叫會在可能的情況下使用快取 RR，而不是導致核發者。

核發新權杖 (每個核發機構、網站和裝置最多 500 個)。
所有權杖都會儲存在裝置端權杖存放區 (類似 Cookie 儲存庫)。
如果找不到有效的 RR，就能在發出後產生新的 RR (每 48 小時最多 2 次)。
RR 會在到期前視為有效，並會在到期時視為本機使用快取。
新的兌換呼叫將耗用本機快取，但不會產生新的 RR。

定義用途後，您必須審慎定義 RR 的生命週期這個選項能定義在確認是否屬於此情況

請務必瞭解以下關鍵行為和變數：制定策略：

變數 / 行為	說明	可能用量
權杖金鑰中繼資料	每個權杖只能使用一組加密編譯金鑰，且的 API 金鑰規定每個核發機構最多只能使用六組金鑰。	要使用這個變數，其中一種可能的做法是定義信任範圍加入您的權杖 (例如，金鑰 1 = 而鍵 6 = 不信任)。
權杖到期日	憑證到期日與金鑰到期日相同。	金鑰至少每 60 天輪替一次，且金鑰核發的所有憑證無效金鑰也會被視為無效。
權杖兌換頻率限制	每部裝置和發卡機構最多只能兌換兩次代碼 48 小時。	視使用情形預估的兌換次數而定且每 48 小時無法追蹤一次案例
每個頂層來源的核發者數量上限	目前每個頂層來源的核發者數量上限為兩個。	仔細定義每個網頁的核發者。
裝置上每個核發機構的權杖數量	目前特定裝置上每個發卡機構的權杖數量上限 500。	請務必將每個核發機構的權杖數量控制在 500 個以內。遇到問題時，請務必處理網頁上的錯誤符記
金鑰承諾使用合約輪替	每個 PST 核發者都必須透過金鑰公開端點承諾使用合約可以每 60 天變更一次，而且任何輪替作業速度較快系統就會忽略該值	如果金鑰將在 60 天內到期，請務必請在上述日期前更新重要承諾使用合約，以免服務中斷 (請參閱詳細資料)。
兌換記錄效期	定義 RR 的壽命來判斷到期時間日期。系統會快取 RR，避免不必要的新的兌換呼叫請務必確保兌換信號	由於兌換頻率限制為每 48 小時兩個符記請務必定義 RR 的壽命至少在這段期間內成功兌換 (RR) 的兌換呼叫效期內應根據這項資訊設定)。建議您設定這個效期。

範例情境

情境 #1：RR 效期不到 24 小時 (t=t)，兌換時間為在不同 48 小時內多次執行此工作

太平洋標準時間中的情境 1 範例：壽命較小。 — 在此情境下，使用者無法在 28 小時內執行兌換新權杖，所有 RR 都會過期。

情境 #2：RR 效期為 24 小時，且已執行兌換作業刊登了多次廣告請求

太平洋標準時間 2 範例：效期 24 小時。 — 由於 RR 的效期為 24 小時，因此你可以在整個 48 小時內兌換，不受任何限制。

情境 #3：RR 效期為 48 小時，且已執行兌換作業多次曝光

太平洋標準時間 3 範例：效期 48 小時。 — 由於 RR 的效期為 48 小時，因此創作者可以在整個 48 小時內進行兌換，不受任何限制。

執行示範

採用 PST 之前，建議您先使用示範進行設定。試用 PST 示範，則必須執行 Chrome 並搭配旗標，才能啟用示範核發者主要承諾使用合約 (按照示範內容網頁)。

執行這部示範影片時，你的瀏覽器使用的是試用版發卡機構和兌換者提供及消耗權杖

技術考量

您必須完成下列步驟，才能獲得最佳示範：

請先停止所有 Chrome 執行個體，再執行含旗標的 Chrome。
如果您是在 Windows 電腦上運作，請參閱已納入這份指南，瞭解如何將參數傳遞給 Chrome 可執行二進位檔。
前往 [應用程式] > [開啟 Chrome 開發人員工具]儲存空間 >私人狀態使用試用版應用程式查看已核發/兌換權杖的權杖 特定權限。

設定採用項目

成為發卡機構

核發者在 PST 中扮演著關鍵角色，他們會指派值給符記指定是否為機器人的使用者如果您想開始使用 PST 核發機構，則須則必須先完成核發機構註冊程序。

如要申請成為發卡機構，發卡機構網站的營運商必須開啟新的 GitHub 上的問題「新增 PST」清單核發者」範本。按照存放區指南填寫問題。端點通過驗證後，會合併至這個存放區， Chrome 伺服器端基礎架構會開始擷取這些金鑰。

核發者伺服器

核發者和兌換者是 PST 的關鍵執行者；是 Google Cloud 的推出與 PST 相關的工具雖然我們已針對符記和 GitHub 說明文件提供更多 PST 伺服器的詳細資料如要設為 PST 的核發者，您必須先設定核發伺服器

部署環境：核發者伺服器

如要實作權杖核發機構伺服器，您必須建構自己的伺服器端來公開 HTTP 端點

核發者元件由兩個主要模組組成：(1) 核發機構伺服器和 (2) 憑證核發者

如同所有面向網頁的應用程式，我們建議多一層保護傳送至您的核發機構伺服器

核發者伺服器：在我們實作範例中，核發伺服器是使用 Express 架構來代管主機的 Node.js 伺服器核發者 HTTP 端點您可以前往 GitHub 查看程式碼範例。
權杖核發者：核發機構加密編譯元件不需要但基於這個元件的效能要求我們提供 C 實作範例，其中採用 Boring 管理權杖。您可以查看發卡機構程式碼範例和安裝作業詳情前往 GitHub 查看
金鑰：權杖核發者元件會使用自訂 EC 金鑰來加密權杖。這些金鑰都必須受到妥善保護，並儲存在安全的儲存空間中。

發卡機構伺服器的技術相關規定

根據通訊協定，您至少必須在核發機構伺服器

金鑰使用承諾 (例如 /.well-known/private-state-token/key-commitment)：瀏覽器可透過這個端點確認加密公開金鑰詳細資料伺服器的正當性
- 範例程式碼
權杖核發作業 (例如 /.well-known/private-state-token/issuance)：用於處理所有權杖要求的憑證核發端點。這個端點將是權杖核發者元件的整合點
- 範例程式碼

如前所述，由於預期流量過高，建議您以可擴充的讓您靈活調整不必支付任何費用

傳送呼叫至核發機構伺服器

為核發機構堆疊實作網站擷取呼叫，以便發出新的呼叫符記

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

查看程式碼範例。

兌換伺服器

您必須自行建立憑證兌換服務，以實作憑證兌換服務伺服器端應用程式這樣一來，您就能讀取核發者的權杖傳送。下列步驟概述如何兌換代碼及讀取方式與這些符記相關聯的兌換記錄。

你可以選擇在同一伺服器 (或一組伺服器)。

兌換伺服器元件。 — PST 示範元件：兌換者伺服器的主要元件，兌換者伺服器 (Node.js 應用程式) 和權杖兌換工具 (在兌換程序中負責驗證簽章和權杖的加密編譯元件)。

兌換者伺服器的技術相關規定

根據通訊協定，您至少必須為你的兌換者伺服器：

/.well-known/private-state-token/redemption：包含所有端點的端點系統會處理權杖兌換作業這個端點將成為將整合兌換者元件
- 範例程式碼

傳送通話至兌換者伺服器

如要兌換代碼，您必須將網站擷取呼叫導入才能兌換先前核發的代碼。

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

請參閱程式碼範例。

兌換代碼後，如要傳送兌換記錄 (RR)，請按照下列步驟操作：其他擷取呼叫：

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

請參閱程式碼範例。

部署實作項目

如要測試實作項目，請先前往呼叫，並確認符記會按照您的邏輯建立。在後端中，確認呼叫是根據規格發出。接著，前往提供兌換通話服務的網頁，確認 RR 會按照您的邏輯建立

實際部署

建議您選擇特定用途相關的網站。充電盒：

每月造訪量偏低 (每月約 100 萬次造訪)：您的第一步，是先為小型目標對象部署這個 API
資料歸您所有不必進行複雜核准程序
不得超過一個核發者：限制權杖數量簡化測試
兌換者不得超過兩名：簡化疑難排解程序，以備不時之需

權限政策

如要正常運作，頂層網頁和使用 API 的所有子資源都必須能存取 PST API。

權杖要求作業是由 private-state-token-issuance 指令控制。token-redemption 和 send-redemption-record 作業是由 private-state-token-redemption 指令控制。根據預設，這些指令的許可清單會設為自我。這表示這項功能僅適用於頂層網頁 (和相同來源 iframe)，而且在未由網頁明確委派的情況下，跨來源 iframe 無法使用。

如果不想讓網站上的特定網頁收到 PST 權杖核發或兌換作業，請在每個網頁的 Permissions-Policy 標頭中加入 private-state-token-issuance=() 和 private-state-token-redemption=()，

您也可以使用 Permissions-Policy 標頭控管第三方提供的 PST 存取權。做為標頭來源清單的參數，請使用 self 和要允許存取 API 的任何來源。舉例來說，如要完全停止在除了您自己的來源和 https://example.com 以外的所有瀏覽環境內使用 PST，請設定下列 HTTP 回應標頭：

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

如要為所有跨來源資源啟用 API，請將來源清單設為 *。

。

瞭解如何使用權限政策控管 Privacy Sandbox 功能，或深入瞭解權限政策。

疑難排解

您可以在 Chrome 開發人員工具的「網路和應用程式」分頁中檢查 PST。

在「網路」分頁上：

「Network」分頁的開發人員工具檢查。 — PST 的開發人員工具檢查：前往「網路」>**私密狀態權杖**，用於取得特定頁面中的權杖和核發機構的所有相關資訊。

在「應用程式」分頁中：

「應用程式」分頁的開發人員工具檢查。 — PST 的開發人員工具檢查：前往「應用程式」>透過私密狀態權杖，取得特定頁面中的權杖和核發機構的所有相關資訊。

瞭解詳情開發人員工具整合。

客戶最佳做法

如果網站的重要功能需要使用特定權杖核發機構，請優先執行這類功能。請先針對這些偏好的核發機構呼叫 hasPrivateToken(issuer)，再載入任何其他指令碼。之所以如此重要，是為了防止可能無法順利兌換。

每個頂層的核發機構數量上限為兩個，第三方指令碼也可以嘗試呼叫 hasPrivateToken(issuer)，優先處理自家首選核發機構。因此，請事先確保重要發卡機構的安全，確保網站能正常運作。

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

伺服器最佳做法和疑難排解

為了讓發卡機構和兌換服務伺服器有效運作，建議你以下列最佳做法存取、安全性、記錄或流量方面的難題

您的端點必須使用 TLS 1.3 或 1.2 套用高強度密碼編譯。
您的基礎架構必須準備就緒，才能處理變數的流量變化 (包括高點)。
確保金鑰受到妥善保護，且與存取權保持一致控管政策、金鑰管理策略和業務持續計畫。
將觀測指標新增至堆疊，確保有掌握使用情況、瓶頸和效能問題轉換至正式環境