Topics API デベロッパー ガイド

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

フィードバックを送信

Topics API は、デバイス上でのユーザーのアプリ使用状況に基づいて、興味に関する大まかなシグナルを推定します。こうしたシグナルを「トピック」といいます。トピックは、アプリ間で個々のユーザーをトラッキングすることなくインタレスト ベース広告をサポートするために広告主と共有されます。Topics API の詳細については、設計案をご覧ください。

重要: SDK Extensions リリースまたは [デベロッパー プレビュー] ボタンで対象のプログラム バージョンを選択してください（手順が異なる場合があります）。

セットアップ

最新の Android プライバシー サンドボックス SDK を使用して、プライバシー保護 API の最新バージョンを入手します。アプリで Topics API を使用するには、次に示すように権限を追加して、広告サービス構成を作成する必要があります。

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

マニフェストの <application> 要素で広告サービス構成を参照します。1

<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_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 (GetTopicsRequest getTopicsRequest, Executor executor,
    OutcomeReceiver<GetTopicsResponse, Exception> callback)

このメソッドを使用するには、TopicsManager オブジェクトと、トピックデータの受信に必要なパラメータを初期化します。パラメータを初期化するには、コールバックの GetTopicsRequest、Executor、OutcomeReceiver を作成します。GetTopicsRequest は、Topics API データの取得に必要な情報を渡します。Executor により、getTopics() を UI スレッド外で実行し、OutcomeReceiver コールバックが結果を非同期で処理するという要件を満たすことができます。次に例を示します。

Kotlin

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = true
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    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());
    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 の動作のプレビューを提供し、今後のリリースでトピックの品質を改善する予定です。

最良のエクスペリエンスを実現するために、複数のアプリを使用するテスト環境で、getTopics() を呼び出してトピックがどのように選択されるかを確認することをおすすめします。GitHub の SDK ランタイムとプライバシー保護 API のリポジトリには、Topics API の初期化方法と呼び出し方法を示すサンプルなど、使用を開始するために役立つ個別の Android Studio プロジェクトのセットが含まれています。

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

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

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

制限事項

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

バグと問題の報告

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