Hướng dẫn dành cho nhà lập trình API Chủ đề

Gửi phản hồi

API Chủ đề 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ề API Chủ đề trong đề xuất thiết kế.

Thiết lập

Phân loại Chủ đề tương tự như hệ thống phân loại Chrome nguồn mở, với các bản phát hành trong tương lai thay đổi sang một hệ thống cụ thể dành cho Android, bao gồm thuật toán phân loại trên thiết bị. Hãy đảm bảo bạn đang sử dụng SDK của bản xem trước dành cho nhà phát triển Hộp cát về quyền riêng tư trong Android, vì đây là phiên bản duy nhất của SDK có chứa các API bảo vệ quyền riêng tư. Bạn sẽ cần phải đưa quyền truy cập và tạo cấu hình dịch vụ quảng cáo vào ứng dụng của mình để sử dụng API Chủ đề, như hiển thị bên dưới:

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

Tham chiếu đến 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:

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

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

Kotlin

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

Java

public void getTopics (GetTopicsRequest getTopicsRequest, Executor executor,
    OutcomeReceiver<GetTopicsResponse, AdServicesException> callback)

Để sử dụng phương thức này, hãy khởi tạo đối tượng TopicsManager và các thông số cần thiết để nhận dữ liệu chủ đề. Để khởi tạo thông số, hãy tạo một GetTopicsRequest, một Executor, và một OutcomeReceiver cho lệnh gọi lại. GetTopicsRequest chuyển thông tin cần thiết để truy xuất dữ liệu chủ đề, Executor cho phép getTopics() thực thi ngoài luồng giao diện người dùng và lệnh gọi lại OutcomeReceiver xử lý kết quả 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 getTopicsRequest = GetTopicsRequest.Builder(mContext)
    mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback)
}

private var mCallback: OutcomeReceiver<GetTopicsResponse, GetTopicsException> =
    object : OutcomeReceiver<GetTopicsResponse, GetTopicsException> {
        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: GetTopicsException) {
            // 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();
    GetTopicsRequest.Builder getTopicsRequest = new GetTopicsRequest.Builder(mContext);
    mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor, mCallback);
}

OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse,
                                                GetTopicsException>() {
    @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 GetTopicsException error) {
        // handle error
        Log.i("Topic", "Error, did not return successfully");

    }
};

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

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

Kotlin

mTopicsManager.getTopics(getTopicsRequest.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, GetTopicsException>)

Java

mTopicsManager.getTopics(getTopicsRequest.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 cấu trúc 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 có thể thay đổi.

Thử nghiệm

API Chủ đề 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 vệ 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 API chủ đề.

Tính toán chủ đề diễn ra ở cuối "giai đoạn". Theo mặc định, mỗi giai đoạn 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ả nhanh hơn bằng cách sử dụng lệnh shell Cầu gỡ lỗi Android sau:

# Shortens the epoch length to 5 minutes.
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 tính toán giai đoạn 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

Các hạn chế

Để biết danh sách các tính năng đang tiến hành cho API Chủ đề, 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.