Topics API 開發人員指南

提供意見回饋

Topics API 會根據使用者的應用程式使用情形,在裝置上推斷出概略的興趣信號。當這些稱為「主題」的信號與廣告客戶共用後,後者無需跨應用程式追蹤個別使用者,就能按照使用者興趣投放廣告。如要進一步瞭解 Topics API,請參閱設計提案

設定

主題分類類似開放原始碼 Chrome 分類,日後推出的版本會變更為 Android 專屬系統,包括裝置端分類。請務必使用 Android 版 Privacy Sandbox 開發人員預覽版 SDK,因為這是唯一提供隱私權保護 API 的 SDK 版本。您必須加入權限,並為應用程式建立廣告服務設定,才能使用 Topics API,如下所示:

 <uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />

在資訊清單的 <application> 元素中參照廣告服務設定:

<property android:name="android.adservices.AD_SERVICES_CONFIG"
   android:resource="@xml/ad_services_config" />

指定資訊清單所參照的廣告服務 XML 資源,例如 res/xml/ad_services_config.xml。透過 allowAllToAccess 屬性授予所有 SDK 的存取權,或使用 allowSdksToAccess 屬性來授予個別 SDK 的存取權:

<ad-services-config>
    <topics allowAllToAccess="true" />
</ad-services-config>

Topics API 的主要功能位於 TopicsManager 物件的 getTopics() 方法中,如以下範例所示:

Kotlin

fun getTopics(
        getTopicsRequest: GetTopicsRequest?,
        executor: Executor?,
        callback: OutcomeReceiver<GetTopicsResponse?, AdServicesException?>?
    ) { }

Java

public void getTopics (GetTopicsRequest getTopicsRequest, Executor executor,
    OutcomeReceiver<GetTopicsResponse, AdServicesException> callback)

如要使用這個方法,請初始化 TopicsManager 物件,以及接收主題資料所必需的參數。如要初始化參數,請建立 GetTopicsRequestExecutorOutcomeReceiver,以進行回呼。GetTopicsRequest 會傳送必要資訊來擷取主題資料,Executor 能讓 getTopics() 從 UI 執行緒執行,而 OutcomeReceiver 回呼會以非同步的方式處理結果。例如:

Kotlin

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val getTopicsRequest = GetTopicsRequest.Builder(mContext)
    mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback)
}

private var mCallback: OutcomeReceiver<GetTopicsResponse, GetTopicsException> =
    object : OutcomeReceiver<GetTopicsResponse, GetTopicsException> {
        override fun onResult(result: GetTopicsResponse) {
            // handle successful result
            val topicsResult = result.topics
            for (i in topicsResult.indices) {
                Log.i("Topic", topicsResult[i].getTopicID().toString())
            }
            if (topicsResult.size == 0) {
                Log.i("Topic", "Returned Empty")
            }
        }

        override fun onError(error: GetTopicsException) {
            // handle error
            Log.i("Topic", "Error, did not return successfully")
        }
    }

Java

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    GetTopicsRequest.Builder getTopicsRequest = new GetTopicsRequest.Builder(mContext);
    mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback);
}

OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse,
                                                GetTopicsException>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        // handle successful result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicID().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }

    @Override
    public void onError(@NonNull GetTopicsException error) {
        // handle error
        Log.i("Topic", "Error, did not return successfully");

    }
};

要求一組主題

設定完成後,您可以撥打電話,以獲取使用 getTopics()方法所得到的 GetTopicsResponse

Kotlin

mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, GetTopicsException>)

Java

mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback);

上述的叫用將提供包含 ID 值的清單主題,這些物件應對應至開放原始碼分類中與使用者相關的主題,或相關的錯誤。主題會類似於下列範例:

/Internet & Telecom/Text & Instant Messaging

請參閱「分類」,瞭解系統可傳回哪些主題。這個分類可能隨時會有變動。

測試

Topics API 會根據應用程式的使用情況提供相關的最新主題。這個早期版本可讓您預覽 API 的行為,我們會在日後版本中不斷改進主題的品質。

為獲得最佳體驗,建議使用包含多個應用程式的測試環境,並可在其中呼叫 getTopics() 以瞭解如何選取主題。GitHub 上的 SDK 執行階段和隱私權保護 API 存放區包含一組可幫助您入門的 Android Studio 專案,其中包括一些展示如何初始化和呼叫主題 API 的範例。

「訓練週期」結束時會進行主題計算。在預設情況下,每個訓練週期都是 7 天,但您可以透過下列 Android Debug Bridge 殼層指令修改時間間隔,以便快速取得結果:

# Shortens the epoch length to 5 minutes.
adb shell setprop debug.adservices.topics_epoch_job_period_ms 300000

您可以使用 getprop 確認 topics_epoch_job_period_ms 值:

adb shell getprop debug.adservices.topics_epoch_job_period_ms

如要手動觸發訓練週期運算,請執行下列指令:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

限制

如需 Topics API 處於開發階段的功能清單,請參閱「版本資訊」。

回報錯誤和問題

您的意見回饋對 Android 版 Privacy Sandbox 至關重要!如果您發現了任何問題,或希望針對 Android 版 Privacy Sandbox 提出改進意見,請告訴我們