Android で Topics API を実装する

セットアップ

Topics API を実装するには、まず開発環境を設定する必要があります。次の設定手順を行います。

1. 最新の Android プライバシー サンドボックス SDK を使用して、プライバシー保護 API の最新バージョンを入手します。

2. マニフェストに次の行を追加します。

   • 権限: アプリが Topics API にアクセスできるように、ACCESS_ADSERVICES_TOPICS 権限を追加します。

     <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 など）。すべての SDK へのアクセスを許可するには allowAllToAccess 属性を使用し、個々の SDK へのアクセスを許可するには allowSdksToAccess 属性を使用します。広告サービスの権限と SDK のアクセス制御の詳細をご覧ください。

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

3. プライバシー サンドボックスに広告テクノロジーを登録して、SDK で Topics API を呼び出します。ローカルでテストする場合は、次のコマンドを使用して Topics 登録チェックを無効にできます。

   adb shell setprop debug.adservices.disable_topics_enrollment_check true
   

4. Topics API へのアクセスを有効にする。デフォルトでは、Topics API は無効になっています。ADB コマンドを使用して有効にする必要があります。

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

   adb shell setprop debug.adservices.disable_topics_enrollment_check true

5. サンプルアプリの Java または Kotlin バージョンをフォークして、デバイス上でトピックを取得する方法についてよく理解してから、実装を開始します。

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

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

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

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

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

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")
    }
}

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 を受け取ることができます。

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

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 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 を呼び出したときにアプリが取得する可能性がある結果の種類を確認できます。

暗号化の詳細

暗号化の導入により、GetTopics() の呼び出しで EncryptedTopic オブジェクトのリストを含むレスポンスが生成されるようになりました。これらの結果を復号すると、前の Topic オブジェクトと同じ JSON 形式のオブジェクトが生成されます。

Topics API は、HPKE（ハイブリッド公開鍵暗号化）のワンショット実装をサポートしています。登録された呼び出し元は、登録時に提供された公開暗号 URL エンドポイントで 32 ビットの公開鍵をホストする必要があります。これらの鍵は Base64 でエンコードされている必要があります。

EncryptedTopic オブジェクトには 3 つのフィールドがあります。返されたトピックのリストは、公開鍵に対応する秘密鍵を使用して取得できます。

開発目的で、登録チェックを無効にして Topics API の暗号化をテストできます。これにより、API はレスポンスの暗号化にテスト公開鍵を使用します。暗号化されたトピックは、対応する秘密鍵を使用して復号できます。

制限事項

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

バグと問題を報告する

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

次のステップ

管理と透明性

ユーザーとデベロッパーが、ユーザーの好みやニーズに合わせて Topics API を管理、カスタマイズする方法について学びます。

Android の Topics の概要

Android での Topics の仕組みと、API フローのコアステップについて学びます。

See also

Check out our resources to better understand the Topics API on Android.

• Check out Topics sample apps, collab and walkthrough videos.
• See how users and developers can control the API.
• Check out the support resources to ask questions, engage and share feedback.