Topics API menyimpulkan secara terperinci sinyal minat di perangkat berdasarkan penggunaan aplikasi pengguna. Sinyal ini, yang disebut topics, dibagikan kepada pengiklan untuk mendukung periklanan menurut minat tanpa melacak masing-masing pengguna di aplikasi. Pelajari Topics API lebih lanjut di proposal desain.
Penyiapan
Taksonomi Topik mirip dengan taksonomi Chrome open source, dengan rilis mendatang yang berubah ke sistem khusus Android termasuk klasifikasi di perangkat. Pastikan Anda menggunakan Android Privacy Sandbox Developer Preview SDK, karena ini adalah satu-satunya versi SDK yang menyertakan API yang menjaga privasi. Anda perlu menyertakan izin dan membuat konfigurasi layanan iklan untuk aplikasi Anda agar dapat menggunakan Topics API, seperti yang ditunjukkan di bawah ini:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />
Referensikan konfigurasi layanan iklan di elemen <application>
manifes Anda:
<property android:name="android.adservices.AD_SERVICES_CONFIG"
android:resource="@xml/ad_services_config" />
Tentukan resource XML layanan iklan yang dirujuk dalam manifes, seperti
res/xml/ad_services_config.xml
. Gunakan atribut allowAllToAccess
untuk memberikan akses ke semua SDK, atau atribut allowSdksToAccess
untuk memberikan
akses ke SDK individual:
<ad-services-config>
<topics allowAllToAccess="true" />
</ad-services-config>
Fungsi utama Topics API berada dalam metode
getTopics()
di dalam objek TopicsManager
, seperti yang ditunjukkan
dalam contoh ini:
Kotlin
fun getTopics(
getTopicsRequest: GetTopicsRequest?,
executor: Executor?,
callback: OutcomeReceiver<GetTopicsResponse?, AdServicesException?>?
) { }
Java
public void getTopics (GetTopicsRequest getTopicsRequest, Executor executor,
OutcomeReceiver<GetTopicsResponse, AdServicesException> callback)
Untuk menggunakan metode ini, inisialisasi objek TopicsManager
dan parameter
yang diperlukan untuk menerima data topik. Untuk melakukan inisialisasi parameter, buat
GetTopicsRequest
, Executor
, danOutcomeReceiver
untuk callback. GetTopicsRequest
meneruskan informasi yang diperlukan untuk mengambil data topik,
Executor
memungkinkan getTopics()
untuk mengeksekusi UI thread, dan callback
OutcomeReceiver
menangani hasilnya secara asinkron. Contoh:
Kotlin
private fun topicGetter() {
val mContext = baseContext
val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
val mExecutor: Executor = Executors.newCachedThreadPool()
val getTopicsRequest = GetTopicsRequest.Builder(mContext)
mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, GetTopicsException> =
object : OutcomeReceiver<GetTopicsResponse, GetTopicsException> {
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: GetTopicsException) {
// 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();
GetTopicsRequest.Builder getTopicsRequest = new GetTopicsRequest.Builder(mContext);
mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse,
GetTopicsException>() {
@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 GetTopicsException error) {
// handle error
Log.i("Topic", "Error, did not return successfully");
}
};
Meminta serangkaian topik
Setelah penyiapan beres, Anda dapat melakukan panggilan untuk menerima GetTopicsResponse
sebagai hasil dari metode getTopics()
:
Kotlin
mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor,
mCallback as OutcomeReceiver<GetTopicsResponse, GetTopicsException>)
Java
mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback);
Pemanggilan di atas akan menampilkan daftar objek Topik yang berisi nilai ID yang sesuai dengan topik dalam taksonomi open source yang relevan dengan pengguna, atau error yang relevan. Topiknya akan menyerupai contoh ini:
/Internet & Telecom/Text & Instant Messaging
Lihat taksonomi untuk daftar kemungkinan topik yang dapat ditampilkan. Taksonomi ini dapat berubah sewaktu-waktu.
Pengujian
Topics API menyediakan topik yang relevan dan terbaru berdasarkan penggunaan aplikasi. Versi awal ini memberikan pratinjau perilaku API, dan kami akan meningkatkan kualitas topik dibandingkan rilis mendatang.
Untuk mendapatkan pengalaman lengkap, sebaiknya gunakan lingkungan pengujian dengan beberapa
aplikasi tempat Anda memanggil getTopics()
untuk melihat cara topik dipilih. SDK
Runtime and Privacy Preserving APIs Repository di GitHub berisi kumpulan
project Android Studio individual untuk membantu Anda memulai, termasuk contoh
yang menunjukkan cara menginisialisasi dan memanggil Topics API.
Penghitungan topik terjadi di akhir "epoch". Secara default, setiap epoch berdurasi 7 hari, tetapi Anda dapat mengubah interval ini untuk mendapatkan hasil lebih cepat menggunakan perintah shell Android Debug Bridge berikut:
# Shortens the epoch length to 5 minutes.
adb shell setprop debug.adservices.topics_epoch_job_period_ms 300000
Anda dapat mengonfirmasi nilai topics_epoch_job_period_ms
dengan getprop
:
adb shell getprop debug.adservices.topics_epoch_job_period_ms
Untuk memicu komputasi epoch secara manual, jalankan perintah berikut:
adb shell cmd jobscheduler run -f com.google.android.adservices.api 2
Batasan
Untuk daftar kemampuan yang sedang berlangsung untuk Topics API, lihat catatan rilis.
Melaporkan bug dan masalah
Masukan Anda adalah bagian penting dari Privacy Sandbox di Android. Beri tahu kami jika ada masalah yang Anda temukan atau ide untuk meningkatkan Privacy Sandbox di Android.