Mengimplementasikan Topics API di Android

Penyiapan

Untuk menerapkan Topics API, Anda perlu menyiapkan lingkungan pengembangan terlebih dahulu. untuk melakukan langkah-langkah penyiapan berikut:

  1. Gunakan Android Privacy Sandbox SDK terbaru untuk mendapatkan versi terbaru API perlindungan privasi.

  2. Tambahkan kode berikut ke manifes Anda:

    • Izin: Sertakan izin ACCESS_ADSERVICES_TOPICS untuk mengizinkan aplikasi Anda mengakses Topics API:

      <uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />

    • Konfigurasi Layanan Iklan: Referensikan file 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 lebih lanjut izin Layanan Iklan dan kontrol akses SDK.

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

  3. Mendaftarkan teknologi iklan Anda dengan Privacy Sandbox untuk memanggil Topics API di SDK Anda. Untuk pengujian secara lokal, Anda dapat menonaktifkan pemeriksaan pendaftaran Topics dengan perintah berikut:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Mengaktifkan akses ke Topics API. Secara default, Topics API dinonaktifkan. Anda perlu mengaktifkannya menggunakan perintah ADB:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  5. Mulai penerapan Anda dengan melakukan fork pada aplikasi contoh versi Java atau Kotlin untuk memahami cara mengambil topik di perangkat.

Meminta serangkaian topik

Fungsi utama Topics API berada dalam metode getTopics() di dalam TopicsManager seperti yang ditunjukkan dalam contoh berikut:

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

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

Setelah penyiapan siap, Anda dapat melakukan panggilan untuk menerima GetTopicsResponse sebagai hasil dari metode getTopics():

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

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

Pemanggilan ini akan memberikan daftar objek Topics 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 Privacy Preserving API dan Runtime SDK 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 dilakukan 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.

Detail enkripsi

Dengan diperkenalkannya enkripsi, panggilan ke GetTopics() kini akan menghasilkan respons dengan daftar objek EncryptedTopic. Mendekripsi hasil ini akan menghasilkan objek dengan format JSON yang sama dengan objek Topic sebelumnya.

Topics API mendukung implementasi satu kali HPKE (Hybrid Public Key Enkripsi). Kita mengharapkan pemanggil yang terdaftar menghosting kunci publik 32-bit pada endpoint URL enkripsi publik yang disediakan selama pendaftaran. Kunci-kunci ini adalah diharapkan berenkode Base64.

Objek EncryptedTopic memiliki 3 kolom. Daftar topik yang dikembalikan dapat yang diperoleh dengan menggunakan kunci pribadi yang sesuai untuk kunci publik.

Untuk tujuan pengembangan, Anda dapat menguji enkripsi Topics API dengan menonaktifkan pemeriksaan pendaftaran. Ini akan memaksa API menggunakan kunci publik tes untuk mengenkripsi respons Anda. Anda dapat mendekripsi topik terenkripsi menggunakan kunci pribadi yang sesuai.

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.

Langkah berikutnya

Pelajari cara pengguna dan developer dapat mengelola dan menyesuaikan Topics API agar sesuai dengan preferensi dan kebutuhan pengguna.
Pahami cara kerja Topics di Android dan pelajari langkah-langkah inti alur API.

Lihat juga

Lihat referensi kami untuk lebih memahami Topics API di Android.