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

行動版 Topics API 總覽

提供意見回饋

關於 Topics API

在行動廣告方面，廣告主會想根據使用者的興趣放送相關廣告。舉例來說，如果某位使用者對烹飪相關資訊有興趣，則相較於與其興趣無關的廣告，該使用者可能會覺得烹飪相關廣告更符合自身需求。

內容相關廣告完全是以按下目前觀眾觀看及宣傳的內容。我們可以在 Topics API 的好處是可以為使用者提供實用服務，但應用程式或許不易透過內容相關廣告營利，以便刊登更相關的廣告而不是他們，這有助於增加對使用者的功能而言。

Topics API 會根據使用者的應用程式使用情形，在裝置上推斷出概略的興趣信號。這些稱為主題的信號會與廣告主分享而且無需追蹤向個別使用者逐一放送應用程式

Topics API 旨在支援通常是在多個應用程式中運作這項支援服務的形式包括找出這些 SDK 通常會有的跨應用程式興趣來觀察個別應用程式開發人員不應需要瞭解使用者的相關資訊

核心概念

「主題」是人類可讀形式的使用者興趣主題，並屬於 Topics 分類。
如果呼叫端 (應用程式或應用程式中使用的第三方 SDK) 在過去 3 個週期內，曾經從與某個主題相關聯的應用程式發出 Topics API 要求，即表示呼叫端「觀察」了該主題。
「週期」是主題計算作業的時間長度，例如一週。

運作方式

我們提議採用的 Topics API 旨在根據使用者的應用程式使用情形，向呼叫端提供概略的感興趣廣告主題。這些主題可在要顯示廣告的應用程式中補充相關的脈絡資訊，也可以彼此結合使用，為使用者尋找適當的廣告。

請參閱 Topics API 開發人員指南中的程式碼範例，瞭解如何針對按照興趣顯示的廣告主題設定擷取功能。注意：API 尚未完成。

系統會從預先定義的開放原始碼分類中選取主題。

平台會使用分類器模型來推斷主題。Topics API 的實作流程與其使用分類器的方式為 Android 開放原始碼計畫的一部分，並會隨著時間持續改進。

為了進行說明，以下透過程式碼範例呈現如何使用主題擷取按照興趣顯示的廣告。這裡使用的 API 並非最終版本。

// Initialize the Topics API.
…
topicsFuture = AdvertisingTopicsClient.getTopics();

// Retrieve Topics and use them in Ad request.
Futures.addCallback(
    topicsFuture,
    new FutureCallback<AdvertisingTopicsInfo>() {
        @Override
        public void onSuccess(@Nullable AdvertisingTopicsInfo topicsInfo) {
            // Sanitize Topics result.
            ...
            // Initialize ad request with Topics obtained.
            AdRequest adRequest = AdRequest.initialize(topicsInfo);
        }

        @Override
        public void onFailure(Throwable t) {
            // Handle error.
            ...
        }
});

如要進一步瞭解分類器模型的運作方式，建議您透過 Android Topics Classifier Colab 測試不同應用程式資料在系統中的回應。

取得 Topics API 存取權

廣告技術平台需要先註冊，才能存取 Topics API。詳情請參閱「註冊 Privacy Sandbox 帳戶」一文。

詳細說明

在每個週期中 (例如每週一次)，系統都會使用裝置端的資訊計算使用者最感興趣的 5 個主題。
- 當 Topics API 受到呼叫時，平台會檢查叫用 API 的應用程式是否已獲指派主題。如果未獲指派，系統會依照以下方式選擇主題，並將所選主題指派給這個應用程式，直到這個週期結束為止。
  - 有 95% 的機率會從該週期計算出的 5 個最感興趣主題清單中，隨機選擇一個主題，
  - 有 5% 的機率會從分類中隨機選擇一個主題。
  - 呼叫端可以使用 shouldRecordObservation = false 參數呼叫 getTopics，指明希望擷取主題而不修改狀態。這表示系統會傳回主題，但該呼叫不會納入每週週期計算作業，也不會為呼叫端更新偵測到的主題清單。
- 之所以要從多個主題中選擇一個主題指派給每個應用程式，是為了確保各個應用程式取得不同的主題，讓多個應用程式與同一使用者產生交互關聯的情形較難發生。
  - 舉例來說，針對某位使用者，應用程式 A 獲派的主題可能是 T1，但應用程式 B 獲派的主題則可能是 T2。這會讓這兩個應用程式較難判斷該資訊是否與同一使用者相關聯。
Topics API 會傳回最多包含 3 個主題 (過去 3 個週期各 1 個) 的清單。
- 藉由提供最多 3 個主題，不常用的應用程式將有足夠的主題來尋找相關廣告，但常用應用程式每週最多只會瞭解到 1 個新主題。
- 傳回的主題資訊包含主題 ID (int)，可對應至分類中的特定項目、分類版本和分類器模型版本。
- 如要接收特定主題，呼叫端必須在過去 3 個週期內，針對與該主題相關聯的應用程式觀察使用者使用情形。
- 所有傳回的主題都代表使用者的興趣，您可以選取任一或所有主題，在廣告請求中提供個人化廣告。

叫用 Topics API 的應用程式獲派某個主題後，平台會判斷呼叫端是否能接收該主題。

如要接收特定主題，呼叫端必須在過去 3 個週期內，針對與該主題相關聯的應用程式觀察使用者互動情形。
如果呼叫端過去並未針對該使用者，在與該主題相關聯的應用程式中呼叫 API，API 傳回的清單就不會包含該主題。
如果呼叫端在過去 3 個週期內未接收任何主題，Topics API 就會傳回空白清單。

舉例來說，假設使用者在裝置上安裝了 A、B、C、D、E、F 和 G 這 7 個應用程式，假設應用程式和廣告的主題分類這些應用程式中的技術 SDK 如下：

應用程式	主題分類	廣告技術 SDK
A	T1、T5	ad-sdk1、ad-sdk2
B	T2	ad-sdk2
C	T3、T6	ad-sdk3、ad-sdk4
D	T1、T4	ad-sdk1
E	T5	ad-sdk4、ad-sdk5
F	T6	ad-sdk2、ad-sdk3、ad-sdk4
G	T7	ad-sdk2

第 1 週結束時，Topics API 會為這個週期產生使用者最感興趣的 5 個主題。

最感興趣的主題	可瞭解該主題的呼叫端
T1	ad-sdk1、ad-sdk2
T2	ad-sdk2
T3	ad-sdk3、ad-sdk4
T4	ad-sdk1
T5	ad-sdk1、ad-sdk2、ad-sdk4、ad-sdk5

在第 2 週，如有任何應用程式的呼叫端呼叫 API，則在傳回的主題清單中，系統只會針對該週期、該應用程式和該主題，列出「可瞭解該主題的呼叫端」欄有該呼叫端的主題。
在計算每個呼叫端可用的主題時，所採用的歷史記錄期間為 3 個週期 (即 3 週)。
僅限與透過廣告叫用 Topics API 的應用程式相關聯系統會使用 SDK也就是說，如果應用程式不含任何廣告 SDK 呼叫 Topics API 時，與該應用程式相關聯的主題不會形成廣告 SDK 可存取的主題庫。
應用程式也可以透過新的資訊清單和 XML 元素，以宣告的方式選擇停用 Topics API，禁止廣告 SDK 針對該應用程式使用 Topics API。如果主題與選擇停用的應用程式相關聯，系統就不會將其納入每週主題計算作業。我們日後會更新本文件，加入相關的實作詳細資料。

如果應用程式使用資訊不足以讓平台推斷出 5 個主題，平台可能會考慮其他選項，例如隨機產生剩餘的主題。

主題分類器

感興趣主題是由分類器模型推斷而來，該模型已根據應用程式名稱、說明和套件名稱等公開應用程式資訊經過訓練。

使用分類器模型進行推斷，針對特定週期計算主題時，所用的信號組合會保留在裝置上。這組信號可能包括已安裝或最近使用的應用程式，但我們日後可能會進一步加入其他信號。
Google 將利用各種訓練資料 (包括應用程式公開資訊的人工收錄標籤) 訓練初始模型，並且會免費提供這個模型，用來測試應用程式所屬的主題分類。
訓練初始模型時，Google 會使用來自少數幾個應用程式商店 (例如 Google Play 商店) 的應用程式公開資訊。
應用程式可能會對應至多個主題或未對應至任何主題，也可能不會納入使用者的主題記錄。如果某個應用程式對應至分類中的多個主題，系統最多只會為該應用程式選擇使用者最感興趣的 3 個主題。

使用者控制項

這項設計的宗旨，是要讓使用者能夠查看和移除與自己的應用程式使用情形相關聯的主題。這項使用者控制功能的實作方式仍在開發階段，相關資訊將於日後更新時提供。
如果使用者解除安裝某個應用程式，但系統在過去 3 個週期中因為該應用程式而選取了某個推斷出的主題，則該主題不會從針對過去 3 個週期傳回的主題清單中移除，這是為了避免揭露與解除安裝事件相關的資訊。

為了進行使用者體驗測試，您也可以啟動應用程式內意圖，以便查看主題的設定使用者介面，就像使用者看到的畫面。呼叫方式如以下範例所示：

//Button that launches settings UI
private Button mSettingsAppButton;
private static final String RB_SETTING_APP_INTENT = "android.adservices.ui.SETTINGS";


//Does setup for button on screen that will launch settings UI to observe Topics
private void registerLaunchSettingsAppButton() {
    mSettingsAppButton.setOnClickListener(
        new View.OnClickListener() {

            @Override
            public void onClick(View view) {
                Context context = getApplicationContext();
                Intent activity2Intent = new Intent(RB_SETTING_APP_INTENT);
                activity2Intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                context.startActivity(activity2Intent);
            }
        });
}

為廣告技術平台進行註冊

所有廣告技術平台 (包括 Google 的平台) 都必須具備完成註冊程序。

應用程式開發人員可透過以下方式，管理哪些廣告技術開發人員可存取 Topics API：包括廣告技術開發人員的註冊 ID。

傳回的主題加密

已註冊、呼叫 Topics API 的廣告技術平台也必須提供確保傳回的主題只能讀取呼叫。

Privacy Sandbox 會從廣告技術提供的端點擷取這些金鑰。三最佳做法是，金鑰必須經常更新，但以後每 6 個月更新一次

Privacy Sandbox 會要求廣告技術確認端點是否可用提供的 Cookie 值。如要進一步瞭解現有和新註冊的廣告技術需要採取的行動，請查看「註冊」頁面開發人員指南。

加密詳細資料

導入加密功能之後，對「GetTopics()」呼叫就會產生回應包含「EncryptedTopic」如需儲存大量結構化物件建議使用 Cloud Bigtable解密這些結果之後會產生與前一個 Topic 物件相同 JSON 格式的物件。

Topics API 支援單樣本導入 HPKE (混合型公開金鑰) 加密)。我們預期已註冊的呼叫端在註冊期間提供的公開加密網址端點。這些金鑰開頭應為 Base64 編碼

EncryptedTopic 物件有 3 個欄位。傳回的主題清單可以透過該公開金鑰的對應私密金鑰取得。

如果是開發用途，您可以停用 Topics API 加密功能，藉此測試檢查狀態這會強制 API 將測試公開金鑰用於將您的回應加密您可以使用對應的私密金鑰

為您推薦

注意：系統會在 JavaScript 關閉時顯示連結文字
版本資訊
Android 開發人員指南中的 Protected Audience API
Topics API 開發人員指南