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.
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 mức sử dụng ứng dụng của người dùng. Những tín hiệu này được gọi là chủ đề và được chia sẻ với các nhà quảng cáo để hỗ trợ quảng cáo dựa trên sở thích mà không cần theo dõi từng người dùng qua của chúng tôi. Tìm hiểu thêm về Topics API trong đề xuất thiết kế. Lưu ý 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 để hãy chọn phiên bản chương trình 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 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
.
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.
Đề xuất cho bạn
- Lưu ý: văn bản có đường liên kết sẽ hiện khi JavaScript tắt
- Hướng dẫn cho nhà phát triển về Protected Audience API trên Android
- Ghi chú phát hành
- Định cấu hình AdServices {:#configure-adservices}