Hướng dẫn cho nhà phát triển Topics API

Khi bạn đọc tài liệu Hộp cát về quyền riêng tư trên Android, hãy sử dụng nút Bản dùng thử cho nhà phát triển hoặc Beta để chọn phiên bản chương trình bạn đang làm việc, vì hướng dẫn có thể khác nhau.

Gửi ý kiến phản hồi

Topics API dự đoán các tín hiệu thô về mối quan tâm trên thiết bị dựa trên hoạt động dùng ứng dụng của người dùng. Các tín hiệu này được gọi là chủ đề, được chia sẻ với các nhà quảng cáo để hỗ trợ hoạt động quảng cáo dựa trên mối quan tâm mà không cần theo dõi từng người dùng trên ứng dụng. Tìm hiểu thêm về Topics API trong đề xuất thiết kế.

Quan trọng: Chọn nút Bản phát hành tiện ích SDK hoặc Bản dùng thử cho nhà phát triển để chọn phiên bản chương trình mà bạn đang sử dụng, vì hướng dẫn có thể khác nhau.

Thiết lập

Hãy dùng SDK Hộp cát về quyền riêng tư của Android mới nhất để nhận phiên bản mới nhất của các API bảo đảm quyền riêng tư. Bạn cần tích hợp quyền truy cập và tạo cấu hình Dịch vụ quảng cáo trong tệp kê khai để ứng dụng dùng Topics API:

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

Tham chiếu một 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. Hãy 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>

Ngoài ra, bạn phải cấp quyền truy cập vào Topics API (bị tắt theo mặc định) bằng các lệnh adb sau đây.

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

Chức năng chính của Topics API nằm trong phương thức getTopics() bên trong đối tượng TopicsManager, như minh hoạ trong ví dụ sau:

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)

Để 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. Lệnh gọi lại OutcomeReceiver xử lý kết quả một cách không đồng bộ. Ví dụ:

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

    }
};

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

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 

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

Java 

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

Lệnh gọi ở trên sẽ cung cấp danh sách các đối tượng Chủ đề, 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 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. Kho lưu trữ API Thời gian chạy và bảo đảm quyền riêng tư SDK trên GitHub chứa một tập hợp các dự án Android Studio riêng lẻ để giúp bạn bắt đầu, bao gồm cả các mẫu trình bày 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 setprop debug.adservices.topics_epoch_job_period_ms 300000

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

adb shell getprop debug.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.

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 đề

Phản hồi của bạn có vai trò quan trọng trong 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.