Topics API デベロッパー ガイド

Android 版プライバシー サンドボックスのドキュメントをご覧になる際は、[デベロッパー プレビュー] または [ベータ版] ボタンで対象のプログラム バージョンを選択してください（手順が異なる場合があります）。

フィードバックを送信

Topics API は、オンデバイスで大まかな関心のシグナルを推定し、 分析します。トピックと呼ばれるこれらのシグナルは、 個々のユーザーをトラッキングせずにインタレスト ベース広告に対応する 。Topics API について詳しくは、設計案をご覧ください。 重要: [SDK Extensions Release] ボタンまたは [Developer Preview] ボタンを選択して、 手順は異なる場合がありますので、お使いのプログラムのバージョンを選択してください。

セットアップ

最新の Android プライバシー サンドボックス SDK を使用して、プライバシー保護 API の最新バージョンを入手します。その際、権限とその権限を含める必要があります。 マニフェストで Ad Services 構成を作成し、アプリが Topics API:

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

<application> 要素で広告サービス構成を参照するには、 manifest:

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

マニフェストで参照される広告サービス XML リソースを指定します。 res/xml/ad_services_config.xml。すべての SDK へのアクセスを許可するには allowAllToAccess 属性を使用し、個々の SDK へのアクセスを許可するには allowSdksToAccess 属性を使用します。広告サービスの権限と SDK のアクセス制御の詳細をご覧ください。

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

さらに、これらの adb コマンドを使用して Topics API へのアクセスを有効にする必要があります（デフォルトでは無効）。

adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

Topics API の主な機能は、次の例に示すように、TopicsManager オブジェクト内の getTopics() メソッドにあります。

Kotlin

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

Java

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

このメソッドを使用するには、TopicsManager オブジェクトと、トピックデータの受信に必要なパラメータを初期化します。GetTopicsRequest 個のパスに必要な情報 Topics API データを取得します。これには、呼び出し元が オブザーバーとして機能するかどうかです。オブザーバーとして動作していない場合、 getTopics 呼び出しは前のエポックのトピックを返しますが、 次のトピックのトピックデータへの影響を確認できますOutcomeReceiver コールバック 結果を非同期で処理します例:

Kotlin

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    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: java.lang.Exception) {
        // 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();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @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 Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

トピックのセットをリクエストする

セットアップの準備が整ったら、次のように呼び出しを行い、getTopics() メソッドの結果として GetTopicsResponse を受け取ることができます。

Kotlin

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

Java

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

上記の呼び出しは、ユーザーに関連するオープンソースの分類のトピックに対応する ID 値を含む Topics オブジェクトのリスト、または関連するエラーを提供します。トピックは次の例のようになります。

/Internet & Telecom/Text & Instant Messaging

返される可能性のあるトピックのリストについては、分類をご覧ください。この分類はオープンソースです。ページ上部のフィードバック ボタンを使用して変更の提案を提出できます。

テスト

Topics API は、アプリの使用状況に基づいて、関連性の高い新しいトピックを提供します。これは早期に により API の動作をプレビューできます。また、今後 API の動作を 今後のリリースで取り上げるトピックです。 最良のエクスペリエンスを実現するために、複数のアプリを使用するテスト環境で、getTopics() を呼び出してトピックがどのように選択されるかを確認することをおすすめします。GitHub の SDK ランタイムとプライバシー保護 API のリポジトリには、Topics API の初期化方法と呼び出し方法を示すサンプルなど、使用を開始するために役立つ個別の Android Studio プロジェクトのセットが含まれています。

トピックの計算は「エポック」の最後で行われます。デフォルトでは各エポックは 7 日間ですが、この間隔を変更して結果を取得できます。この Android Debug Bridge シェルコマンドを使用すると、エポックの長さを 5 分に短縮できます。

adb shell device_config put adservices topics_epoch_job_period_ms 300000

get で topics_epoch_job_period_ms の値を確認できます。

adb shell device_config get adservices topics_epoch_job_period_ms

エポックの計算を手動でトリガーするには、次のコマンドを実行します。

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

サンプルアプリを使用するほかに、トピック分類器に対してアプリ情報のさまざまな組み合わせをテストするための colab があります。この Colab を使用して、getTopics を呼び出したときにアプリが取得する可能性がある結果の種類を確認できます。

制限事項

Topics API に関する開発中の機能の一覧については、リリースノートをご覧ください。

バグと問題の報告

皆様からのフィードバックは、Android 版プライバシー サンドボックスに欠かせない要素です。問題が見つかった場合や Android 版プライバシー サンドボックスを改善するためのアイデアがありましたらお知らせください。