Định cấu hình AdServices

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.

Hãy làm theo hướng dẫn bên dưới để khai báo quyền dành riêng cho API và định cấu hình quyền truy cập của SDK vào các tài nguyên do API được nhắm mục tiêu quản lý.

Khai báo các quyền AdServices theo API cụ thể

Để truy cập vào từng PPAPI, quyền normal đối với Dịch vụ quảng cáo là bắt buộc. Trong tệp kê khai, hãy khai báo quyền truy cập phù hợp tương ứng với các API cần thiết trong SDK hoặc ứng dụng của bạn.

Attribution Reporting API:

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

Attribution Reporting API (với báo cáo gỡ lỗi):

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

API đối tượng tuỳ chỉnh/Protected Audience API:

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

Topics API:

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

Để nhận báo cáo gỡ lỗi với Attribution Reporting API (không bắt buộc), hãy thêm quyền AD_ID:

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

Nếu dự án của bạn có các phần phụ thuộc trên mô-đun hoặc SDK, thì chúng có thể đã khai báo các quyền Dịch vụ quảng cáo bắt buộc trong tệp kê khai. Theo mặc định, bản dựng Gradle sẽ sáp nhập tất cả các tệp kê khai vào một tệp kê khai duy nhất được đóng gói vào ứng dụng. Hãy dùng khung hiển thị Tệp kê khai sáp nhập để xác minh rằng đang sử dụng các quyền chính xác.

Nếu bạn cần ngăn chặn việc hợp nhất bất kỳ quyền nào vào ứng dụng thông qua các phần phụ thuộc như SDK, hãy thêm điểm đánh dấu nút remove cho các quyền cụ thể đó. Ví dụ sau minh hoạ cách ngăn chặn việc hợp nhất quyền của Topics.

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

Định cấu hình Dịch vụ quảng cáo theo API cụ thể

Tương tự như quyền truy cập PPAPI, mỗi API có một mục tương ứng trong cấu hình dịch vụ quảng cáo. Cấu hình này cấp cho bạn quyền truy cập kiểm soát chi tiết vào các tài nguyên do API quản lý trong ứng dụng hoặc SDK nhúng của bạn. Trong tệp kê khai, hãy chỉ định một thuộc tính adservicesConfig như trong ví dụ sau:

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

      ...
</application>

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. Đối với mỗi API bảo đảm quyền riêng tư áp dụng cho ứng dụng (hoặc SDK nhúng) của bạn, hãy đặt thuộc tính allowAllToAccess thành true để cấp quyền truy cập cho mọi phương thức gọi.

Ngoài ra, bạn có thể dùng thuộc tính allowAdPartnersToAccess để cấp quyền truy cập chi tiết vào API cho từng công nghệ quảng cáo. Bạn cần cung cấp danh sách mã tài khoản đăng ký dành cho nhà phát triển có được bằng cách đăng ký. Nếu bạn đặt thuộc tính allowAllToAccess thành true, thì thuộc tính này sẽ được ưu tiên hơn mọi mã tài khoản đăng ký được chỉ định trong thuộc tính allowAdPartnersToAccess.

Các nền tảng công nghệ quảng cáo cũng phải đảm bảo rằng máy khách của ứng dụng cấp quyền truy cập thích hợp vào các API bảo đảm quyền riêng tư bắt buộc trong cấu hình dịch vụ quảng cáo.

Ví dụ sau đây cho thấy cách chỉ định quyền truy cập rộng rãi để cho phép mọi mã tài khoản có đăng ký được truy cập vào tất cả các API bảo đảm quyền riêng tư:

<ad-services-config>
   <!-- Attribution API -->
   <attribution allowAllToAccess="true" />

   <!-- Topics API -->
   <topics allowAllToAccess="true" />

   <!-- Protected Audience on Android API -->
   <custom-audiences allowAllToAccess="true" />
</ad-services-config>

Ví dụ sau cho thấy cách chỉ định quyền truy cập chi tiết vào từng API bảo đảm quyền riêng tư cho một số mã tài khoản đăng ký:

<ad-services-config>
    <!-- Attribution API -->
    <attribution allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Topics API →-->
    <includes-sdk-library name="ENROLLMENT-ID" />
    <topics allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Protected Audience on Android API -->
    <custom-audiences allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />
</ad-services-config>

Khai báo phần phụ thuộc của thư viện Jetpack

Để tích hợp với các API bảo đảm quyền riêng tư của Hộp cát về quyền riêng tư, hãy dùng thư viện Jetpack ads-adservices 1.0.0-beta01 trở lên. Bạn có thể dùng thư viện này để tóm tắt ứng dụng của mình từ các thông tin chi tiết ở cấp nền tảng và đơn giản hoá quá trình tích hợp bằng các API bảo đảm quyền riêng tư.

1. Thêm kho lưu trữ Maven vào dự án.
2. Khai báo các phần phụ thuộc của thư viện Jetpack ads-adservices trong tệp build.gradle cho ứng dụng hoặc mô-đun của bạn.
3. Dùng API từ các gói androidx.privacysandbox.ads.adservices.*.
4. Thư viện Jetpack ads-adservices hỗ trợ coroutine Kotlin tích hợp. Bạn có thể cần kết hợp các phần phụ thuộc nhận biết được vòng đời phù hợp với dự án của mình để quản lý phạm vi coroutine.

Kiểm tra tính sẵn có của phiên bản Tiện ích Dịch vụ quảng cáo

Nếu bạn sử dụng thư viện Jetpack ads-services để tích hợp với API bảo đảm quyền riêng tư, thì thư viện sẽ kiểm tra tính sẵn có của các API được yêu cầu trong hàm obtain(). Hàm này trả về giá trị rỗng nếu API được yêu cầu không có sẵn trên thiết bị. Ví dụ sau minh hoạ cách khởi chạy TopicsManager cho Topics API. Đây là cách tương tự như cách truy cập vào các API bảo đảm quyền riêng tư khác.

import androidx.privacysandbox.ads.adservices.topics.TopicsManager

// The initialization function will return null if the requested
// functionality is not available on the device.
val topicsManager = TopicsManager.obtain(context)

import androidx.privacysandbox.ads.adservices.topics.TopicsManager;

// The initialization function will return null if the requested
// functionality is not available on the device.
TopicsManager topicsManager = TopicsManager.obtain(context);

Nếu bạn dùng API AdServices trực tiếp trong SDK Tiện ích, hãy kiểm tra phiên bản Tiện ích AdServices bao gồm các API AdServices mà bạn muốn dùng. Trong tài liệu tham khảo API, bạn có thể xác định phiên bản mà một API AdServices cụ thể được giới thiệu. Ví dụ: tài liệu tham khảo API cho lớp TopicsManager cho biết rằng lớp đó "Đã được thêm vào Tiện ích Dịch vụ quảng cáo 4". Bạn có thể làm theo các bước kiểm tra có điều kiện sau đây để xác thực những tiện ích SDK chứa các API AdServices.

import android.os.ext.SdkExtensions

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

import android.os.ext.SdkExtensions;

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Giới hạn quyền truy cập khi ở nền trước

Để đảm bảo tính minh bạch, chỉ có các ứng dụng hiện Activity (Hoạt động) hoặc có RunningAppProcessInfo của IMPORTANCE_FOREGROUND mới truy cập được vào môi trường Thời gian chạy SDK và API bảo đảm quyền riêng tư.