ใช้ 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 ดังที่แสดงในตัวอย่างนี้

Kotlin 

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

Java 

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

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

Kotlin 

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

Java 

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

Kotlin 

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

Java 

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

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

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

ดูเพิ่มเติม

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