Topics API 开发者指南

提供反馈

Topics API 可根据用户的应用使用情况来粗略推断设备上的兴趣信号。这些信号(称为“主题”)会与广告主共享,以支持针对用户兴趣投放广告,而无需跨应用跟踪单个用户。设计方案中详细了解 Topics API。

设置

主题分类与开源 Chrome 分类类似,后续版本将更改为 Android 设备专用系统,包括设备端分类系统。请确保您使用的是 Android Privacy Sandbox 开发者预览版 SDK,因为这是该 SDK 唯一包含隐私保护 API 的版本。您需要添加权限,并为应用创建广告服务配置,以便使用 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 对象以及接收主题数据所需的参数。若要初始化参数,请创建一个 GetTopicsRequest、一个 Executor 和一个 OutcomeReceiver 回调。GetTopicsRequest 用于传递检索主题数据所需的信息,Executor 允许 getTopics() 在界面线程之外执行,而 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 项目,其中包括展示如何初始化和调用 Topics API 的示例。

主题计算会在“周期”结束时进行。默认情况下,每个周期为 7 天,但您可以使用以下 Android 调试桥 shell 命令修改此时间间隔,以便更快地获得结果:

# 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 的正在开发中的功能列表,请查看版本说明

报告 bug 和问题

您的反馈对 Privacy Sandbox on Android 而言至关重要!如果发现任何问题或有任何关于改进 Privacy Sandbox on Android 的想法,欢迎告诉我们。