定義目標對象資料

瞭解如何使用 Protected Audience API 建立興趣群組，藉此定義目標對象。如要瞭解 Protected Audience API 完整生命週期，請參閱開發人員指南；如要深入瞭解瀏覽器記錄興趣群組的方式，請參閱 Protected Audience API 說明。

您不是開發人員嗎？請參閱「Protected Audience API 總覽」。

Protected Audience API 興趣群組

Protected Audience API 興趣群組代表一組與再行銷名單相關，有共同興趣的使用者。每個 Protected Audience API 興趣群組都有一個擁有者。

興趣群組擁有者是 Protected Audience API 廣告競價的買方。興趣群組成員資格是由瀏覽器儲存在使用者的裝置上，不會與瀏覽器供應商或任何人分享。

API 函式

joinAdInterestGroup()

廣告客戶的需求端平台 (DSP) 或廣告客戶本身呼叫 navigator.joinAdInterestGroup()，要求瀏覽器將興趣群組加入瀏覽器的成員資格清單。

joinAdInterestGroup() 的呼叫情境來源必須與興趣群組擁有者的來源相符，因此除非興趣群組擁有者的來源與目前文件的來源相符 (例如具有專屬興趣群組的網站)，否則必須透過 iframe (例如 DSP) 呼叫 joinAdInterestGroup()。

「joinAdInterestGroup()」需要下列權限：

• 造訪的網站
• 興趣群組擁有者

因此您無法在未dsp.example.com授予權限的情況下，malicious.example呼叫 joinAdInterestGroup() 為 dsp.example.com 擁有的興趣群組呼叫 。

造訪網站的權限

您可以從同一來源或跨來源授予權限。根據預設，系統會針對造訪網站的相同來源 (也就是與目前網頁的頂層頁框相同的來源) 發出 joinAdInterestGroup() 呼叫，藉此獲得權限。

使用案例：

以下範例說明使用者如何定義興趣群組，並要求瀏覽器加入群組。

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

傳遞至函式的 interestGroup 物件大小不得超過 50 KB，否則呼叫將會失敗。第二個參數指定興趣群組的時間長度 (上限為 30 天)。連續呼叫會覆寫先前儲存的值。

重點：用於 Protected Audience API 方法參數的所有網址都必須來自安全來源：所有資源都必須透過 HTTPS 網址提供。如何在本機執行 Protected Audience API 時透過 HTTPS 進行開發。 此外，biddingLogicUrl、decisionLogicUrl 和 trustedBiddingSignals 也需要 X-Allow-FLEDGE: true HTTP 回應標頭。

必要屬性

興趣群組只需要 owner 和 name 屬性：

屬性	範例	角色
owner	https://dsp.example	興趣群組擁有者的來源。
name	custom-bikes	興趣群組名稱。

選用屬性

其餘屬性為選用屬性：

biddingLogicUrl^1、2

範例：https://dsp.example/bid/custom-bikes/bid.js

角色：出價 JavaScript 在 Worklet 中執行的網址。

biddingWasmHelperUrl^1、2

範例：https://dsp.example/bid/custom-bikes/bid.wasm

角色：從 biddingLogicUrl 驅動的 WebAssembly 程式碼網址。

updateUrl²

範例：https://dsp.example/bid/custom-bikes/update

角色：傳回 JSON 以更新興趣群組屬性的網址。 (請參閱「更新目標對象資料並重新整理廣告」)。

trustedBiddingSignalsUrl²

範例：https://dsp.example/trusted/bidding-signals

角色：向出價方信任鍵/值服務發出的鍵/值要求基準網址。

trustedBiddingSignalsKeys

範例：['key1', 'key2' ...]

角色：向鍵/值受信任鍵/值服務提出要求的鍵，

userBiddingSignals

範例：{...}

角色：擁有者可在出價期間使用的其他中繼資料。

ads¹

範例：[bikeAd1, bikeAd2, bikeAd3]

角色：系統可能會向這個興趣群組顯示廣告。

adComponents

範例：[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]

角色：由多個部分構成的廣告元件。

¹ biddingLogicUrl 和 ads 是選用屬性，但這是參與競價的必要項目。有時候，您可能想要在沒有這些屬性的情況下建立興趣群組：舉例來說，興趣群組擁有者可以針對尚未放送的廣告活動，將瀏覽器加入興趣群組，或在日後有需要的情況下運用，或是暫時用完廣告預算。

² 在目前的 Protected Audience API 實作中，biddingLogicUrl、biddingWasmHelperUrl、updateUrl 和 trustedBiddingSignalsUrl 的來源必須與擁有者相同。這個限制可能不是長期的限制，而 ads 和 adComponents 網址則沒有這類限制。

為興趣群組指定廣告

ads 和 adComponents 物件包含廣告素材的網址，以及可用於出價的任意中繼資料 (選用)。

例如：

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

leaveAdInterestGroup()

興趣群組擁有者可以要求將瀏覽器從興趣群組中移除。瀏覽器會從成員資格清單中移除興趣群組。

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

如果使用者回到要求瀏覽器新增興趣群組的網站，興趣群組擁有者即可呼叫 navigator.leaveAdInterestGroup() 函式，要求瀏覽器移除該興趣群組。

廣告的程式碼也可以針對其興趣群組呼叫此函式。

常見問題

單一使用者的每個群組擁有者最多可以建立多少個興趣群組？

Chrome 最多可讓每位擁有者最多 1000 個興趣群組，以及最多 1000 個興趣群組擁有者。這些限制的用意在於保護欄，不得在一般運作過程中發揮作用。

如何提升興趣群組廣告達到 K-anon 門檻？

如公開說明所述，由於單一興趣群組可包含多則可能顯示的廣告，因此這個群組有機會重新出價，將另一個廣告當做「備用廣告」來放送任何優先選項低於門檻。也就是說，目前仍低於 k-anonymity 門檻的小型明確廣告仍可選擇參與競價，興趣群組則會變回較籠統的廣告，直到較專業的廣告擁有足夠的目標對象為止。

從策略的角度來看，您可以考量以下因素：

• 若要讓新廣告開始放送，只要在需要顯示廣告的情況下開始出價即可。您無需採取其他行動。
• 您可以製作一個備用廣告，以便在新廣告不是 k-anon 時使用。您的備用廣告本身可能會有 k-anon 的風險，因此您可以先考慮直接使用備用廣告出價。也許 1% 的時間，例如，如果情況良好，確保備用廣告預期會超過門檻，請採取這種做法。

最近也曾探討過其他可行的因應方式，如果您有這種機制會造成問題，請繼續與大眾交流，瞭解 API 的改善方式。

所有 Protected Audience API 參考資料

可用的 API 參考指南如下：

• Protected Audience API 的開發人員指南。
• 廣告買方指南：Protected Audience 興趣群組與出價產生。
• Protected Audience 廣告競價的廣告賣方指南。
• 製作競價結果報表指南
• Protected Audience 廣告競價延遲的最佳做法
• 排解 Protected Audience 相關問題

Protected Audience API 說明也提供功能支援和限制的詳細資料。