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

การคํานวณหัวข้อจะเกิดขึ้นเมื่อสิ้นสุดศักราช โดยค่าเริ่มต้น แต่ละยุคจะมีระยะเวลา 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

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 นี้ได้อย่างไร
• โปรดดูแหล่งข้อมูลการสนับสนุนเพื่อถามคำถาม มีส่วนร่วม และแชร์ความคิดเห็น