セットアップ
Topics API を実装するには、まず開発環境を設定する必要があります。次の設定手順を行います。
最新の Android プライバシー サンドボックス SDK を使用して、プライバシー保護 API の最新バージョンを入手します。
マニフェストに次の行を追加します。
権限: アプリが 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>
プライバシー サンドボックスに広告テクノロジーを登録して、SDK で Topics API を呼び出します。ローカルでテストする場合は、次のコマンドを使用して Topics 登録チェックを無効にできます。
adb shell setprop debug.adservices.disable_topics_enrollment_check true
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
サンプルアプリの Java または Kotlin バージョンをフォークして、デバイス上でトピックを取得する方法についてよく理解してから、実装を開始します。
トピックのセットをリクエストする
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 の動作のプレビューを提供し、今後のリリースでトピックの品質を改善する予定です。
最良のエクスペリエンスを実現するために、複数のアプリを使用するテスト環境で、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 版プライバシー サンドボックスを改善するためのアイデアがありましたらお知らせください。
次のステップ
管理と透明性
Android の Topics の概要
関連情報
Android の Topics API について詳しくは、Google のリソースをご覧ください。
- Topics のサンプルアプリ、コラボレーション、チュートリアル動画をご確認ください。
- ユーザーとデベロッパーが API を制御する方法を確認する。
- サポート リソースで質問したり、フィードバックを共有したりできます。