ใช้ Topics API ใน Android

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 ซึ่งรวมถึงแฟล็กเพื่อระบุว่าผู้เรียกจะทำหน้าที่เป็นผู้สังเกตการณ์หรือไม่ เมื่อไม่ ทำหน้าที่เป็นผู้สังเกตการณ์ การเรียก getTopics จะแสดงผลหัวข้อจากยุคก่อนหน้า แต่จะไม่ส่งผลต่อข้อมูลหัวข้อสำหรับยุคถัดไป การเรียกกลับจะจัดการผลลัพธ์แบบไม่พร้อมกัน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");
    }
};

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

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

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

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.

See also

Check out our resources to better understand the Topics API on Android.

• Check out Topics sample apps, collab and walkthrough videos.
• See how users and developers can control the API.
• Check out the support resources to ask questions, engage and share feedback.