Panduan developer Topics API

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.

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:

fun getTopics(
        getTopicsRequest: GetTopicsRequest?,
        executor: Executor?,
        callback: OutcomeReceiver<GetTopicsResponse?, AdServicesException?>?
    ) { }

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:

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

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():

mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, GetTopicsException>)

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.