Định cấu hình AdServices cho Android

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ý.

Lưu ý: Có một thư viện Jetpack mới cho phép tích hợp với công cụ Quyền riêng tư Các API Bảo đảm quyền riêng tư của Hộp cát (Chủ đề, Đối tượng được bảo vệ và Báo cáo phân bổ. Bạn có thể dùng thư viện này làm tiện ích bổ sung thay thế cho API Hộp cát về quyền riêng tư (được cung cấp trong SDK Tiện ích).

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 bằng Báo cáo phân bổ (không bắt buộc) API, bao gồ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 cung 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 của bạn hoặc SDK được nhúng.

Lưu ý: Bạn không bắt buộc phải định cấu hình Dịch vụ quảng cáo cụ thể. và chỉ cần thiết khi nhà phát triển ứng dụng muốn thay đổi hoặc hạn chế quyền truy cập vào vì mọi quyền truy cập đều được cấp theo mặc định.

Trong tệp kê khai, hãy chỉ định một thuộc tính adservicesConfig như dưới đây trong phần sau ví dụ:

<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 của bạn (hoặc SDK nhúng), hãy đặt thuộc tính allowAllToAccess thành true thành cấp quyền truy cập cho bất kỳ phương thức gọi nào.

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.

Lưu ý: Để truy cập vào các API Hộp cát về quyền riêng tư trong bản phát hành Tiện ích SDK AdServices mới nhất và trong Bản dùng thử cho nhà phát triển, bạn cần hoàn tất quy trình đăng ký.

Các nền tảng công nghệ quảng cáo cũng phải đảm bảo rằng ứng dụng khách của họ cấp quyền thích hợp quyền truy cậ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.

Lưu ý: Do có một lỗi đã được nhận biết, bạn nên đặt allowAllToAccess thành true khi kiểm thử cục bộ.

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 quy trình đăng ký mã tài khoản 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>

Lưu ý: Nếu việc đăng ký bị tắt cho Topics API hoặc Protected Audience API bằng cách sử dụng các lệnh adb, ứng dụng có thể truy cập các API liên quan bất kể các biện pháp kiểm soát quyền truy cập được chỉ định trong 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ể sử dụng thư viện này để tóm tắt ứng dụng của bạn từ thông tin chi tiết ở cấp nền tảng và đơn giản hoá quá trình tích hợp với 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 đang 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ư 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.

Kotlin

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)

Java

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 AdServices cụ thể Ra mắt API. 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.

Kotlin

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.
...
}

Java

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, hãy truy cập vào Thời gian chạy SDK và API bảo đảm quyền riêng tư chỉ bao gồm những ứng dụng có Hoạt động hiển thị hoặc có RunningAppProcessInfo trong tổng số IMPORTANCE_FOREGROUND.