Panduan developer Topics API

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.

Berikan masukan

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.

Penting: Pilih tombol Rilis Ekstensi SDK atau Pratinjau Developer untuk memilih versi program yang sedang Anda kerjakan, karena petunjuknya dapat bervariasi.

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 SDK individual. 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:

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:

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

    }
};

Meminta serangkaian topik

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

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

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 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

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.