ใช้ Topics API ใน Android

ตั้งค่า

หากต้องการใช้ Topics API คุณต้องตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์ก่อน โปรดทำตามขั้นตอนการตั้งค่าต่อไปนี้

  1. ใช้ Privacy Sandbox SDK ของ Android เวอร์ชันล่าสุดเพื่อรับเวอร์ชันล่าสุด เวอร์ชัน API การรักษาความเป็นส่วนตัว

  2. เพิ่มข้อมูลต่อไปนี้ลงในไฟล์ Manifest

    • สิทธิ์: ใส่สิทธิ์ ACCESS_ADSERVICES_TOPICS เพื่ออนุญาตให้แอปเข้าถึง Topics API

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

    • การกำหนดค่าบริการโฆษณา: อ้างอิงไฟล์การกำหนดค่าบริการโฆษณาในองค์ประกอบ <application> ของไฟล์ Manifest

      <property android:name="android.adservices.AD_SERVICES_CONFIG"
android:resource="@xml/ad_services_config" />

      ระบุทรัพยากร XML ของบริการโฆษณาที่อ้างถึงในไฟล์ Manifest เช่น res/xml/ad_services_config.xml ใช้แอตทริบิวต์ allowAllToAccess เพื่อ ให้สิทธิ์เข้าถึง SDK ทั้งหมด หรือแอตทริบิวต์ allowSdksToAccess เพื่อให้สิทธิ์เข้าถึง กับ SDK แต่ละรายการ ดูข้อมูลเพิ่มเติมเกี่ยวกับสิทธิ์บริการโฆษณาและการควบคุมการเข้าถึง SDK

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

  3. ลงทะเบียนเทคโนโลยีโฆษณากับ Privacy Sandbox เพื่อเรียกใช้ Topics API ใน SDK สำหรับการทดสอบในเครื่อง คุณสามารถปิดใช้การตรวจสอบการลงทะเบียน Topics ด้วยคำสั่งต่อไปนี้

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. เปิดใช้การเข้าถึง Topics API Topics API จะปิดใช้อยู่โดยค่าเริ่มต้น คุณต้องเปิดใช้โดยใช้คำสั่ง ADB ต่อไปนี้

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

  5. เริ่มต้นใช้งานด้วยการแยกแอปตัวอย่างเวอร์ชัน Java หรือ Kotlin เพื่อทำความคุ้นเคยกับวิธีเรียกข้อมูลหัวข้อในอุปกรณ์

ขอชุดหัวข้อ

ฟังก์ชันหลักของ Topics API อยู่ในเมธอด getTopics() ภายใน TopicsManager ตามที่แสดงในตัวอย่างนี้

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)

หากต้องการใช้วิธีนี้ ให้เริ่มต้นออบเจ็กต์ TopicsManager และพารามิเตอร์ ที่จำเป็นในการรับข้อมูลหัวข้อ ต้องการข้อมูลบัตร GetTopicsRequest ใบ เพื่อดึงข้อมูล Topics API ซึ่งรวมถึงแฟล็กเพื่อระบุว่าผู้โทร จะทำหน้าที่เป็นผู้สังเกตการณ์หรือไม่ เมื่อไม่ได้ทำหน้าที่เป็นผู้สังเกตการณ์ การเรียกใช้ getTopics แสดงหัวข้อจาก Epoch ก่อนหน้า แต่จะไม่แสดง ข้อมูลหัวข้อต่อไปนี้มีผลต่อข้อมูล ฟังก์ชัน callback ของ OutcomeReceiver จะจัดการผลลัพธ์แบบไม่พร้อมกัน เช่น

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

เมื่อตั้งค่าพร้อมแล้ว คุณสามารถโทรออกเพื่อรับ GetTopicsResponse เป็นผลลัพธ์จากเมธอด getTopics():

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

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

การเรียกใช้นี้จะแสดงรายการออบเจ็กต์ Topics ที่มีค่ารหัสซึ่งสอดคล้องกับหัวข้อในการจัดหมวดหมู่แบบโอเพนซอร์สที่เกี่ยวข้องกับผู้ใช้ หรือข้อผิดพลาดที่เกี่ยวข้อง หัวข้อจะคล้ายกับตัวอย่างนี้:

/Internet & Telecom/Text & Instant Messaging

โปรดดูการจัดหมวดหมู่สำหรับรายการหัวข้อที่เป็นไปได้ที่สามารถ ส่งคืนแล้ว การจัดหมวดหมู่นี้เป็นโอเพนซอร์สและคุณสามารถส่งการเปลี่ยนแปลงที่แนะนำได้โดยใช้ปุ่มความคิดเห็นที่ด้านบนของหน้านี้

การทดสอบ

Topics API นำเสนอหัวข้อที่เกี่ยวข้องและสดใหม่โดยอิงตามการใช้งานแอป เวอร์ชันทดลองนี้แสดงตัวอย่างลักษณะการทํางานของ API และเราจะปรับปรุงคุณภาพของหัวข้อในรุ่นที่เผยแพร่ในอนาคต

เราขอแนะนำให้ใช้สภาพแวดล้อมการทดสอบที่มีแอปหลายแอปซึ่งคุณเรียกใช้ getTopics() เพื่อดูวิธีเลือกหัวข้อ เพื่อให้ได้รับประสบการณ์การใช้งานที่สมบูรณ์ที่สุด ที่เก็บ API ที่รักษาความเป็นส่วนตัวรันไทม์และรันไทม์ของ SDK ใน GitHub มีชุดโปรเจ็กต์ Android Studio แต่ละโปรเจ็กต์ที่จะช่วยให้คุณได้รับ ที่เริ่มใช้งานไปแล้ว ซึ่งรวมถึงตัวอย่างที่สาธิตวิธีเริ่มต้นและเรียกใช้ Topics API

การคํานวณหัวข้อจะเกิดขึ้นเมื่อสิ้นสุดศักราช โดยค่าเริ่มต้น แต่ละยุคจะมีระยะเวลา 7 วัน แต่คุณแก้ไขช่วงเวลานี้เพื่อดูผลลัพธ์ได้ คำสั่งเชลล์ Android Debug Bridge นี้จะลดระยะเวลาของศักราชลงเหลือ 5 นาที

adb shell device_config put adservices topics_epoch_job_period_ms 300000

คุณสามารถยืนยันค่า topics_epoch_job_period_ms ด้วย get ได้โดยทำดังนี้

adb shell device_config get adservices topics_epoch_job_period_ms

หากต้องการเรียกใช้การคํานวณช่วงเวลาด้วยตนเอง ให้เรียกใช้คําสั่งต่อไปนี้

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

นอกจากการใช้แอปตัวอย่างแล้ว ยังมี Colab ที่คุณสามารถใช้เพื่อทดสอบการผสมผสานข้อมูลแอปต่างๆ กับตัวแยกประเภทหัวข้อได้ ใช้ Colab นี้เพื่อดูประเภทผลการค้นหาที่แอปมีแนวโน้มที่จะ รับเมื่อโทรหา getTopics

รายละเอียดการเข้ารหัส

เมื่อมีการเปิดตัวการเข้ารหัส การเรียกใช้ GetTopics() จะสร้างการตอบกลับพร้อมรายการออบเจ็กต์ EncryptedTopic การถอดรหัสผลลัพธ์เหล่านี้จะ ผลลัพธ์เป็นออบเจ็กต์ที่มีรูปแบบ JSON เดียวกันกับออบเจ็กต์ Topic ก่อนหน้านี้

Topics API รองรับการใช้งาน HPKE (การเข้ารหัสคีย์สาธารณะแบบผสม) แบบครั้งเดียว เราคาดหวังว่าผู้โทรที่ลงทะเบียนจะโฮสต์คีย์สาธารณะ 32 บิตในปลายทาง URL การเข้ารหัสสาธารณะที่ระบุไว้ระหว่างการลงทะเบียน คีย์เหล่านี้จะ ต้องเข้ารหัส Base64

ออบเจ็กต์ EncryptedTopic รายการมี 3 ฟิลด์ คุณดูรายการหัวข้อที่แสดงผลได้โดยใช้คีย์ส่วนตัวที่สอดคล้องกันสำหรับคีย์สาธารณะ

คุณสามารถทดสอบการเข้ารหัส Topics API เพื่อการทํางานได้โดยปิดใช้การตรวจสอบการลงทะเบียน การดำเนินการนี้จะบังคับให้ API ใช้คีย์สาธารณะทดสอบสำหรับ เพื่อเข้ารหัสคำตอบของคุณ คุณสามารถถอดรหัสหัวข้อที่เข้ารหัสได้โดยใช้คีย์ส่วนตัวที่เกี่ยวข้อง

ข้อจำกัด

ดูรายการความสามารถที่อยู่ระหว่างดำเนินการสำหรับ Topics API ได้จาก บันทึกประจำรุ่น

รายงานข้อบกพร่องและปัญหา

ความคิดเห็นของคุณเป็นส่วนสำคัญของ Privacy Sandbox ใน Android โปรดแจ้งให้เราทราบ ทุกปัญหาที่คุณพบหรือเสนอไอเดียในการปรับปรุง Privacy Sandbox ใน Android

ขั้นตอนถัดไป

ดูวิธีที่ผู้ใช้และนักพัฒนาซอฟต์แวร์สามารถจัดการและปรับแต่ง Topics API ให้เหมาะกับความต้องการและความต้องการของผู้ใช้
ทำความเข้าใจวิธีการทำงานของ Topics ใน Android และเรียนรู้ขั้นตอนหลักๆ ของโฟลว์ API

ดูเพิ่มเติม

ดูแหล่งข้อมูลของเราเพื่อทำความเข้าใจเกี่ยวกับ Topics API บน Android ให้ดียิ่งขึ้น