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

Private State Tokens 開發人員指南

過去，第三方 Cookie 是用來儲存及傳達使用者狀態的資訊，例如他們的登入狀態、所使用的裝置相關資訊，或是他們是否為已知且值得信賴的使用者。例如，使用者是否已透過 SSO 登入、使用者是否擁有特定類型的相容裝置，或是使用者是否為已知且值得信賴的使用者。第三方 Cookie 支援功能已淘汰，因此許多這類用途都需要透過其他方式支援。

私人狀態權杖可讓您在網路上分享資訊，但會透過控管可實際分享的資料量，以保護隱私。

Private State Tokens (舊稱 Trust Tokens) 可讓信任的使用者真實性從一個情境傳達至另一個情境，同時協助網站防範詐欺，並區分機器人和真人，而無需進行被動追蹤。

本文將概述實作私密狀態權杖 (PST) 的技術細節。如需更高層級的綱要，請參閱 PST 總覽。

學習流程：PST。 — PST 學習過程：這個過程包含多個步驟，首先要瞭解 API，並定義自己的權杖策略 (更多產品或業務相關活動)。之後，技術階段會在您的本機環境中實作示範，然後將其套用至實際用途。

Private State Token 的運作方式

在 PST 中，您需要瞭解發卡機構和兌換者之間的重要關係。發卡機構和兌換機構可為同一家公司。

發出者：這些實體擁有有關使用者的信號 (例如，使用者是否為機器人)，並將該信號嵌入儲存在使用者裝置上的權杖 (詳情請見後續章節)。
兌換者：這些實體可能沒有使用者信號，但需要瞭解使用者相關資訊 (例如使用者是否為機器人)，並要求向發出者兌換權杖，以瞭解使用者的可信度。

每項 PST 互動都需要發卡機構和兌換者合作，才能在網路上分享信號。這些信號是粗略值，無法提供足夠詳細的資訊來識別個人。

私密狀態權杖是否適合我？

對於需要做出信任決策，並希望在不同情境下提供資訊的公司而言，PST 可能會帶來好處。如要進一步瞭解 PST 的潛在用途，請參閱 PST 用途說明文件。

發出及兌換權杖

PST 導入程序分為三個階段：

發出符記
兌換符記
兌換記錄轉寄

在第一階段，系統會向瀏覽器發出權杖 (通常是在某種驗證程序後)。在第二階段，另一個實體會提出要求，以便兌換已核發的權杖，讀取該權杖中的值。在最後階段，兌換方會收到兌換記錄 (RR)，其中包含符記中的值。兌換方之後可將該記錄用於各種用途，做為該使用者的認證。

Private State Tokens 的基本流程。 — 順序圖：此圖顯示 PST 在實際情境中的基本用法，例如兩個網站想要交換關於特定 Chrome 例項的信號。兩個網站會在不同時間執行發布和兌換作業，並在兩者之間交換可信任的信號。

定義符記策略

如要定義符記號策略，您必須瞭解 PST 重要概念 (符記號和兌換記錄)、變數、行為和限制，才能思考這些概念在您的用途中可能的用途。

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

每部裝置可為每個頂層網站和發出者儲存最多 500 個符記。此外，每個權杖都有中繼資料，說明發布者用來發布權杖的金鑰。系統可在兌換過程中，根據這項資訊決定是否兌換符記。PST 資料會儲存在使用者裝置上的瀏覽器內部，且只有 PST API 可以存取。

兌換代碼後，兌換記錄 (RR) 會儲存在裝置上。這項儲存空間可做為日後兌換的快取。每部裝置、網頁和發證機構，每 48 小時限兌換兩個符記。新的兌換呼叫會盡可能使用快取的 RR，而不會向發布者發出要求。

系統會核發新的權杖 (每個發出者、網站和裝置最多 500 個)。
所有權杖都會儲存在裝置上的權杖儲存庫中 (類似 Cookie 儲存庫)。
如果找不到有效的 RR，則可以在發布後產生新的 RR (每 48 小時最多 2 次)。
系統會將 RR 視為有效，直到到期為止，並將其用作本機快取。
新的兌換呼叫會命中本機快取 (不會產生新的 RR)。

定義用途後，您必須仔細定義 RR 的生命週期，因為這會決定您在用途中可使用 RR 的次數。

請務必先瞭解下列重要行為和變數，再定義策略：

變數 / 行為	說明	可能的用途
權杖鍵中繼資料	每個權杖都可以使用單一加密金鑰核發，且在 PST 中，每個發出者最多只能有六個金鑰。	使用這個變數的其中一種方法，是根據密碼金鑰定義權杖的信任範圍 (例如，金鑰 1 = 高信任，金鑰 6 = 不信任)。
權杖到期日	權杖到期日與金鑰到期日相同。	金鑰輪替間隔至少為 60 天，且所有使用無效金鑰核發的權杖也視為無效。
符記兌換率上限	每部裝置和發卡機構每 48 小時最多可兌換兩個符記。	取決於您的用途每 48 小時需要的預估兌換次數。
每個頂層來源的發證機構數量上限	目前每個頂層來源的發證機構數量上限為兩個。	請仔細定義每個網頁的發布者。
裝置上每個發出者可用的符記	目前，每個發出者在特定裝置上的符記數量上限為 500 個。	請確保每個發出者代碼數量不超過 500 個。嘗試發出符記時，請務必處理網頁中的錯誤。
金鑰承諾輪替	每個 PST 發布者都必須公開端點，其中包含每 60 天可變更一次的關鍵提交內容，且系統會忽略任何比此更快速的輪替作業。	如果您的車鑰將在 60 天內到期，則必須在該日期前更新車鑰承諾，以免服務中斷 (請參閱詳細資料)。
兌換記錄的效期	您可以定義 RR 的生命週期，以便判斷到期日。由於 RR 會快取，以免向發布者發出不必要的新兌換呼叫，因此請務必確保有足夠新鮮的兌換信號。	每 48 小時只能兌換兩個符記，因此請務必定義 RR 的生命週期，以便在至少這段時間內成功執行兌換呼叫 (應相應設定 RR 生命週期)。建議您將這個生命週期設為以週為單位。

範例情境

情境 1：RR 生命週期少於 24 小時 (t=t)，且在 48 小時的期間內多次兌換。

範例 1：PST 生命週期短。 — 在這種情況下，使用者將無法兌換新的代幣，且所有 RR 都會過期，這段時間為 28 小時。

情境 2：RR 生命週期為 24 小時，且在 48 小時的回購期間執行多次回購。

太平洋標準時間的範例情境 2：24 小時生命週期。 — 在這種情況下，由於 RR 的生命週期為 24 小時，因此在整個 48 小時內都可以兌換，不受任何限制。

情境 #3：RR 生命週期為 48 小時，且在 48 小時的回購期間執行多次回購。

太平洋標準時間的範例情境 3：48 小時的生命週期。 — 在這種情況下，由於 RR 的生命週期為 48 小時，因此在整個 48 小時內都可以兌換，不受任何限制。

執行示範

在採用 PST 之前，建議您先設定示範版本。如要試用 PST 示範，您必須使用標記執行 Chrome，以便啟用示範發布者重要承諾 (請按照示範頁面上的操作說明操作)。

執行這個示範時，瀏覽器會使用示範發出者和兌換者伺服器提供及使用權杖。

技術考量

如要讓這個示範執行得最好，請實作下列步驟：

請務必先停止所有 Chrome 執行個體，再執行帶有標記的 Chrome。
如果您在 Windows 機器上執行，請參閱這份指南，瞭解如何將參數傳遞至 Chrome 可執行二進位檔。
使用示範應用程式時，開啟 Chrome 開發人員工具，並依序前往「Applications」>「Storage」>「Private State Tokens」，查看由示範發出者核發/兌換的權杖。

設定採用方式

成為核發單位

發布者在 PST 中扮演重要角色。並為這些符記指派值，以判斷使用者是否為機器人。如要以核發機構的身分開始使用 PST，您必須完成核發機構註冊程序。

如要申請成為發證機構，發證機構網站的操作者必須使用「新 PST 發證機構」範本，在GitHub 存放區中開啟新的問題。請按照存放區中的指示填寫問題。端點經過驗證後，就會合併至這個存放區，Chrome 伺服器端基礎架構會開始擷取這些金鑰。

發證者伺服器

核發機構和兌換機構是 PST 的關鍵角色；伺服器和符記是 PST 的關鍵工具。雖然我們已在 GitHub 說明文件中提供一些關於權杖的詳細資訊，但我們想進一步說明 PST 伺服器。如要設定為 PST 發布者，您必須先設定發布伺服器。

部署環境：發證者伺服器

如要實作權杖發出者伺服器，您必須自行建構伺服器端應用程式，公開 HTTP 端點。

發出者元件由兩個主要模組組成：(1) 發出者伺服器和 (2) 權杖發出者。

如同所有面向網際網路的應用程式，我們建議您為發出者伺服器提供額外的保護層。

核發伺服器：在我們的示例實作中，核發伺服器是使用 Express 架構來代管核發者 HTTP 端點的 Node.js 伺服器。您可以查看 GitHub 上的程式碼範例。
權杖發出者：權杖發出者加密元件不需要任何特定語言，但基於此元件效能需求，我們提供 C 實作方式做為範例，該實作方式使用 Boring SSL 程式庫來管理權杖。您可以在 GitHub 上找到發出者程式碼範例和安裝程序的更多資訊
金鑰：符記發出者元件會使用自訂 EC 金鑰加密符記。這些金鑰必須受到保護，並儲存在安全儲存空間中。

核發者伺服器的技術規定

根據通訊協定，您需要在發出者伺服器中實作至少兩個 HTTP 端點：

金鑰承諾 (例如 /.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"
      }
    });

查看程式碼範例。

Redeemer 伺服器

您必須自行建構伺服器端應用程式，才能實作符記兌換服務。這樣您就能讀取發布者傳送的符記。下列步驟將說明如何兌換符記，以及如何讀取與這些符記相關聯的兌換記錄。

您可以選擇在同一個伺服器 (或伺服器群組) 中執行發出者和兌換者。

Redeemer 伺服器元件。 — PST 示範元件：這是兌換伺服器的主要元件。贖回伺服器 (Node.js 應用程式) 和符記贖回工具 (負責在贖回程序中驗證簽名和符記的加密元件)。

兌換者伺服器的技術規定

根據通訊協定，您需要為兌換程式伺服器實作至少兩個 HTTP 端點：

/.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 部署至小型目標對象
您擁有並控管這項功能：如有需要，您可以快速停用導入作業，不必經過複雜的核准程序
發出者不得超過一個：限制符記數量，以簡化測試。
兌換者不得超過兩人：您需要簡化疑難排解程序，以便在發生問題時進行處理。

權限政策

為確保正常運作，PST API 必須可供頂層頁面和任何使用 API 的子資源使用。

符記要求作業由 private-state-token-issuance 指令控制。token-redemption 和 send-redemption-record 作業由 private-state-token-redemption 指令控管。在 Chrome 132 以上版本中，這些指令的許可清單預設為 * (所有來源)。也就是說，這項功能可用於頂層頁面、同來源 iframe 和跨來源 iframe，且無須明確委派。

您可以在每個網頁的 Permissions-Policy 標頭中加入 private-state-token-issuance=() 和 private-state-token-redemption=()，為網站上的特定網頁停用 PST 權杖核發或兌換功能。

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

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

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

瞭解如何透過權限政策控管 Privacy Sandbox 功能，或進一步瞭解權限政策。

疑難排解

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

在「網路」分頁中：

開發人員工具的「網路」分頁檢查畫面。 — DevTools 檢查 PST：依序前往「Network」 >「Private state tokens」，即可取得特定網頁的權杖和發出者相關資訊。

在「應用程式」分頁中：

開發人員工具「應用程式」分頁的檢查項目。 — DevTools 對 PST 的檢查：依序前往「Application」>「Private state tokens」，即可取得特定網頁的權杖和發出者相關資訊。

進一步瞭解這項開發人員工具整合。

用戶端最佳做法

如果網站的重要功能需要特定的權杖發出者，請將這些權杖發出者列為優先。請先為這些偏好發證機構呼叫 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).

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

為了讓發卡機構和兌換伺服器有效運作，建議您實施下列最佳做法，確保不會遇到任何 PST 的存取、安全性、記錄或流量問題。

端點必須使用 TLS 1.3 或 1.2 來套用強加密機制。
基礎架構必須能處理不同的流量量 (包括尖峰流量)。
請確保您的金鑰受到保護，並符合您的存取權控制政策、金鑰管理策略和業務持續性計畫。
請在堆疊中新增可觀察性指標，確保您在正式推出後，能夠瞭解使用情況、瓶頸和效能問題。