ใช้ Topics API ใน Android

ตั้งค่า

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

1. ใช้ Android Privacy Sandbox SDK เวอร์ชันล่าสุดเพื่อรับ 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. เริ่มต้นการติดตั้งใช้งานโดยการ Fork แอปตัวอย่างเวอร์ชัน Java หรือ Kotlin เพื่อทำความคุ้นเคยกับวิธีดึงหัวข้อในอุปกรณ์

ขอชุดหัวข้อ

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

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 และพารามิเตอร์ที่จำเป็นเพื่อรับข้อมูล Topics GetTopicsRequest ส่งข้อมูลที่จำเป็น เพื่อดึงข้อมูล Topics API รวมถึงค่าสถานะเพื่อระบุว่าผู้เรียก จะทำหน้าที่เป็นผู้สังเกตการณ์หรือไม่ เมื่อไม่ได้ทำหน้าที่เป็นผู้สังเกตการณ์ การเรียกใช้ getTopicsจะแสดงผลหัวข้อจาก Epoch ก่อนหน้า แต่จะไม่ส่งผลต่อข้อมูลหัวข้อสำหรับ Epoch ถัดไป โดยแฮนเดิลการเรียกกลับ OutcomeReceiver จะจัดการผลลัพธ์แบบอะซิงโครนัส เช่น

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() ได้

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

การคำนวณหัวข้อจะเกิดขึ้นเมื่อสิ้นสุด Epoch โดยค่าเริ่มต้น แต่ละ Epoch จะยาว 7 วัน แต่คุณสามารถแก้ไขช่วงเวลานี้เพื่อให้ได้ผลลัพธ์ คำสั่งเชลล์ Android Debug Bridge นี้จะลดความยาวของ Epoch เป็น 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

หากต้องการทริกเกอร์การคำนวณ Epoch ด้วยตนเอง ให้เรียกใช้คำสั่งต่อไปนี้

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

Next steps

Control & transparency

Learn how users and developers can manage and customize the Topics API to suit user's preferences and needs.

Topics on Android overview

Understand how Topics works on Android and lear about the core steps of the API flow.

ดูเพิ่มเติม

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

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