Triển khai Topics API trên Android

Thiết lập

Để triển khai API Chủ đề, trước tiên, bạn cần thiết lập môi trường phát triển. Hãy thực hiện các bước thiết lập sau:

  1. Hãy dùng SDK Hộp cát về quyền riêng tư của Android mới nhất để nhận được thông tin mới nhất của API bảo đảm quyền riêng tư.

  2. Thêm đoạn mã sau vào tệp kê khai:

    • Quyền: Thêm quyền ACCESS_ADSERVICES_TOPICS để cho phép ứng dụng truy cập vào Topics API:

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

    • Cấu hình dịch vụ quảng cáo: Tham chiếu tệp cấu hình Dịch vụ quảng cáo trong phần tử <application> của tệp kê khai.

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

      Chỉ định tài nguyên XML của Dịch vụ quảng cáo được tham chiếu trong tệp kê khai, chẳng hạn như res/xml/ad_services_config.xml. Sử dụng thuộc tính allowAllToAccess để cấp quyền truy cập vào tất cả các SDK hoặc thuộc tính allowSdksToAccess để cấp quyền truy cập vào từng SDK. Tìm hiểu thêm về việc kiểm soát quyền truy cập vào SDK và Dịch vụ quảng cáo.

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

  3. Đăng ký công nghệ quảng cáo bằng Hộp cát về quyền riêng tư để gọi Topics API trong SDK của bạn. Để kiểm thử cục bộ, bạn có thể tắt tính năng kiểm tra việc đăng ký Chủ đề bằng các lệnh sau:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Bật quyền truy cập vào Topics API. Theo mặc định, Topics API sẽ bị tắt. Bạn cần bật chế độ này bằng lệnh ADB:

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

  5. Bắt đầu triển khai bằng cách phát triển nhánh Java hoặc Kotlin của ứng dụng mẫu để làm quen với cách truy xuất chủ đề trên thiết bị.

Yêu cầu một nhóm chủ đề

Chức năng chính của Topics API nằm trong phương thức getTopics() bên trong TopicsManager như trong ví dụ sau:

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)

Để sử dụng phương thức này, hãy khởi tạo đối tượng TopicsManager và các tham số cần thiết để nhận dữ liệu chủ đề. GetTopicsRequest truyền thông tin cần thiết để truy xuất dữ liệu của Topics API, bao gồm cả cờ, để cho biết phương thức gọi có đóng vai trò là trình quan sát hay không. Khi không đóng vai trò là trình quan sát, lệnh gọi getTopics sẽ trả về một chủ đề từ khoảng thời gian bắt đầu trước đây của hệ thống, nhưng sẽ không ảnh hưởng đến dữ liệu chủ đề cho thời gian bắt đầu sau của hệ thống. Chiến lược phát hành đĩa đơn OutcomeReceiver lệnh gọi lại xử lý kết quả một cách không đồng bộ. Ví dụ:

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

Sau khi thiết lập xong, bạn có thể thực hiện lệnh gọi để nhận GetTopicsResponse theo kết quả từ phương thức getTopics():

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

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

Lệnh gọi này sẽ cung cấp danh sách các đối tượng Chủ đề có chứa giá trị mã nhận dạng tương ứng với các chủ đề trong hệ thống phân loại nguồn mở có liên quan đến người dùng, hoặc lỗi có liên quan. Các chủ đề sẽ giống như ví dụ bên dưới:

/Internet & Telecom/Text & Instant Messaging

Hãy tham khảo hệ thống phân loại để biết danh sách các chủ đề có thể được trả về. Hệ thống phân loại này là nguồn mở và bạn có thể gửi các thay đổi được đề xuất bằng cách sử dụng nút phản hồi ở đầu trang này.

Kiểm thử

Topics API cung cấp các chủ đề mới và phù hợp dựa trên mức sử dụng ứng dụng. Phiên bản sớm này cung cấp bản xem trước về các hành vi của API và chúng tôi sẽ cải thiện chất lượng của các chủ đề so với các bản phát hành trong tương lai.

Để có được trải nghiệm đầy đủ nhất, chúng tôi khuyến cáo môi trường thử nghiệm với nhiều ứng dụng trong đó bạn gọi là getTopics() để xem cách các chủ đề được chọn. Chiến lược phát hành đĩa đơn Kho lưu trữ API Thời gian chạy SDK và API Bảo đảm quyền riêng tư trên GitHub chứa một tập hợp các dự án Android Studio riêng lẻ để giúp bạn tải bắt đầu, bao gồm các mẫu minh hoạ cách khởi chạy và gọi Topics API.

Quá trình tính toán chủ đề diễn ra khi hết thời gian bắt đầu của hệ thống. Theo mặc định, mỗi khoảng thời gian bắt đầu của hệ thống sẽ kéo dài 7 ngày, nhưng bạn có thể sửa đổi khoảng thời gian này để nhận được kết quả. Lệnh shell Cầu gỡ lỗi Android sẽ rút ngắn khoảng thời gian bắt đầu của hệ thống xuống còn 5 phút:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Bạn có thể xác nhận giá trị topics_epoch_job_period_ms bằng get:

adb shell device_config get adservices topics_epoch_job_period_ms

Để kích hoạt việc tính toán thời gian bắt đầu của hệ thống theo cách thủ công, hãy thực thi lệnh sau:

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

Ngoài việc dùng ứng dụng mẫu, bạn cũng có thể dùng một colab để kiểm thử các kiểu kết hợp thông tin ứng dụng so với thuật toán phân loại chủ đề. Hãy sử dụng colab này để xem các loại kết quả mà ứng dụng của bạn có thể nhận được khi gọi getTopics.

Thông tin chi tiết về quá trình mã hoá

Với sự ra mắt của lớp mã hoá, các lệnh gọi đến GetTopics() giờ đây sẽ tạo ra một phản hồi có danh sách các đối tượng EncryptedTopic. Khi giải mã những kết quả này, dẫn đến một đối tượng có cùng định dạng JSON của đối tượng Topic trước đó.

Topics API hỗ trợ triển khai một lần HPKE (Mã hoá khoá công khai kết hợp). Chúng tôi dự kiến phương thức gọi đã đăng ký lưu trữ khoá công khai 32 bit trên được cung cấp trong quá trình đăng ký. Những khoá này là phải được mã hoá Base64.

Đối tượng EncryptedTopic có 3 trường. Danh sách các chủ đề được trả về có thể là có được bằng cách sử dụng khoá riêng tư tương ứng cho khoá công khai.

Đối với mục đích phát triển, bạn có thể kiểm thử việc mã hoá Topics API bằng cách tắt việc kiểm tra đăng ký. Điều này sẽ buộc API sử dụng khoá công khai kiểm thử cho mã hoá phản hồi của bạn. Bạn có thể giải mã các chủ đề đã mã hoá bằng khoá riêng tư tương ứng.

Các điểm hạn chế

Để biết danh sách các tính năng đang tiến hành cho Topics API, hãy tham khảo ghi chú phát hành.

Báo cáo lỗi và vấn đề

Ý kiến phản hồi của bạn có vai trò quan trọng đối với Hộp cát về quyền riêng tư trên Android. Hãy cho chúng tôi biết về mọi vấn đề bạn tìm thấy hoặc ý tưởng để cải thiện Hộp cát về quyền riêng tư trên Android.

Các bước tiếp theo

Tìm hiểu cách người dùng và nhà phát triển có thể quản lý và tuỳ chỉnh API Chủ đề cho phù hợp với lựa chọn ưu tiên và nhu cầu của người dùng.
Tìm hiểu cách hoạt động của Chủ đề trên Android và nắm rõ các bước cốt lõi của quy trình phát triển API.

Xem thêm

Hãy xem các tài nguyên của chúng tôi để hiểu rõ hơn về API Chủ đề trên Android.