セットアップ
Topics API を実装するには、まず開発環境をセットアップする必要があります。セットアップ手順は次のとおりです。
最新の Android 向けプライバシー サンドボックス SDK を使用して、 プライバシー保護 API の新しいバージョンです。
マニフェストに次の行を追加します。
権限:
ACCESS_ADSERVICES_TOPICS権限を含めて、アプリに 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。すべての SDK へのアクセスを許可するにはallowAllToAccess属性を使用し、個々の SDK へのアクセスを許可するにはallowSdksToAccess属性を使用します。詳しくは、Ad Services の権限と SDK のアクセス制御をご覧ください。<ad-services-config> <topics allowAllToAccess="true"/> </ad-services-config>
プライバシー サンドボックスに広告テクノロジーを登録し、SDK で Topics API を呼び出すようにします。ローカルでテストする場合は、次のコマンドを使用して Topics 登録チェックを無効にできます。
adb shell setprop debug.adservices.disable_topics_enrollment_check trueTopics 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まず、サンプルアプリの Java または Kotlin 版をフォークして実装を開始し、デバイスでトピックを取得する方法に慣れてください。
トピックのセットをリクエストする
Topics API の主な機能は getTopics() メソッドにあります
（TopicsManager 内）
渡します。
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");
}
};
セットアップの準備ができたら、
GetTopicsResponse
getTopics() メソッドにより、次のことがわかります。
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 300000get で 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 版プライバシー サンドボックスを改善するためのアイデアがありましたらお知らせください。
Next steps
Control & transparency
Topics on Android overview
関連情報
Android の Topics API について詳しくは、Google のリソースをご覧ください。
- Topics のサンプルアプリ、コラボレーション、チュートリアル動画をご確認ください。
- ユーザーとデベロッパーが API を制御する方法を確認する。
- サポート リソースで質問したり、フィードバックを共有したりできます。