Saat Anda membaca dokumentasi Privacy Sandbox di Android, gunakan tombol Pratinjau Developer atau Beta untuk memilih versi program yang sedang Anda gunakan, karena petunjuknya dapat bervariasi.
Topics API menyimpulkan secara terperinci sinyal minat di perangkat berdasarkan penggunaan aplikasi pengguna. Sinyal ini, yang disebut topik, dibagikan kepada pengiklan untuk mendukung periklanan menurut minat tanpa melacak setiap pengguna di aplikasi. Pelajari Topics API lebih lanjut di proposal desain. Penting: Pilih tombol Rilis Ekstensi SDK atau Pratinjau Developer untuk pilih versi program yang sedang Anda kerjakan, karena instruksinya mungkin berbeda-beda.
Penyiapan
Gunakan Android Privacy Sandbox SDK terbaru untuk mendapatkan versi terbaru API perlindungan privasi. Anda perlu menyertakan izin dan membuat konfigurasi Layanan Iklan di manifes agar aplikasi Anda dapat menggunakan Topics API:
<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 masing-masing SDK. Pelajari izin Layanan Iklan dan kontrol akses SDK lebih lanjut.
<ad-services-config>
<topics allowAllToAccess="true" />
</ad-services-config>
Selain itu, Anda harus mengaktifkan akses ke Topics API (dinonaktifkan secara default) dengan perintah adb ini.
adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
adb shell setprop debug.adservices.disable_topics_enrollment_check true
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, Exception>
) { }
Java
public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
@NonNull Executor executor,
@NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)
Untuk menggunakan metode ini, inisialisasi objek TopicsManager
dan parameter
yang diperlukan untuk menerima data topik. GetTopicsRequest
meneruskan informasi yang diperlukan untuk mengambil data Topics
API, termasuk tanda untuk menunjukkan apakah pemanggil akan bertindak sebagai
pengamat atau tidak. Jika tidak bertindak sebagai pengamat, panggilan
getTopics
menampilkan topik dari epoch sebelumnya, tetapi tidak akan
memengaruhi data topik untuk epoch berikutnya. 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 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");
}
};
Meminta serangkaian topik
Setelah penyiapan beres, Anda dapat melakukan panggilan untuk menerima GetTopicsResponse
sebagai hasil dari metode getTopics()
:
Kotlin
mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)
Java
mTopicsManager.getTopics(mTopicsRequestBuilder.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 bersifat open source dan perubahan yang disarankan dapat diajukan menggunakan tombol masukan di bagian atas halaman ini.
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. Halaman Repositori Runtime
SDK dan Privacy Preserving API di GitHub berisi kumpulan
masing-masing project Android Studio 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. Perintah shell Android Debug Bridge ini akan mempersingkat durasi epoch menjadi 5 menit:
adb shell device_config put adservices topics_epoch_job_period_ms 300000
Anda dapat mengonfirmasi nilai topics_epoch_job_period_ms
dengan get
:
adb shell device_config get 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
Selain menggunakan aplikasi contoh, ada colab yang
dapat Anda gunakan untuk menguji berbagai kombinasi info aplikasi terhadap
pengklasifikasi topik. Gunakan colab ini untuk melihat jenis hasil yang kemungkinan akan
diperoleh aplikasi Anda saat memanggil getTopics
.
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.
Direkomendasikan untuk Anda
- Catatan: teks link ditampilkan saat JavaScript nonaktif
- Panduan developer Protected Audience API di Android
- Catatan rilis
- Mengonfigurasi AdServices {:#configure-adservices}