Hướng dẫn cho nhà phát triển về Protected Audience 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

Protected Audience API trên Android (trước đây là FLEDGE) bao gồm Custom Audience API (API Đối tượng tuỳ chỉnh) và Ad Selection API (API Lựa chọn quảng cáo). Các nhà quảng cáo và nền tảng công nghệ quảng cáo có thể sử dụng những API này để phân phát quảng cáo tuỳ chỉnh dựa trên hoạt động tương tác trước đây với ứng dụng nhằm giới hạn việc chia sẻ giá trị nhận dạng giữa các ứng dụng, đồng thời giới hạn việc chia sẻ thông tin tương tác của người dùng ứng dụng với các bên thứ ba.

API Đối tượng tuỳ chỉnh tập trung vào bản tóm tắt "đối tượng tuỳ chỉnh", đại diện cho một nhóm người dùng có ý định chung. Nhà quảng cáo có thể đăng ký người dùng với một đối tượng tuỳ chỉnh và liên kết quảng cáo có liên quan với đối tượng đó. Thông tin này được lưu trữ trên máy và có thể dùng để thông báo giá thầu của nhà quảng cáo, lọc quảng cáo và hiển thị quảng cáo.

API lựa chọn quảng cáo cung cấp một khung cho phép nhiều nhà phát triển tiến hành một phiên đấu giá cục bộ cho đối tượng tuỳ chỉnh. Để đạt được điều này, hệ thống sẽ xem xét các quảng cáo liên quan được liên kết với đối tượng tuỳ chỉnh, đồng thời thực hiện việc xử lý bổ sung đối với các quảng cáo mà một nền tảng công nghệ quảng cáo đưa trở lại thiết bị.

Nền tảng công nghệ quảng cáo có thể tích hợp các API này để triển khai hoạt động tái tiếp thị bảo vệ quyền riêng tư của người dùng. Chúng tôi dự định hỗ trợ thêm nhiều trường hợp sử dụng, bao gồm cả quảng cáo cài đặt ứng dụng, dự kiến sẽ phát hành trong tương lai. Hãy tìm hiểu thêm về Protected Audience API trên Android trong đề xuất thiết kế.

Hướng dẫn này mô tả cách dùng Protected Audience API trên Android để thực hiện những việc sau:

1. Quản lý đối tượng tuỳ chỉnh
2. Thiết lập và chạy lựa chọn quảng cáo trên thiết bị
3. Báo cáo số lượt hiển thị quảng cáo

Trước khi bắt đầu

Trước khi bắt đầu, hãy hoàn thành các bước sau:

1. Thiết lập môi trường phát triển của bạn cho Hộp cát về quyền riêng tư trên Android.
2. Cài đặt hình ảnh hệ thống trên một thiết bị được hỗ trợ hoặc thiết lập một trình mô phỏng có hỗ trợ Hộp cát về quyền riêng tư trên Android.

3. Trong dòng lệnh, hãy bật quyền truy cập vào Protected Audience API (bị tắt theo mặc định) bằng lệnh adb sau đây.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. Đưa quyền ACCESS_ADSERVICES_CUSTOM_AUDIENCE vào tệp kê khai ứng dụng:

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

5. 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" />
   

6. 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. 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>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

7. Theo mặc định, API Lựa chọn quảng cáo sẽ thực thi các giới hạn về dung lượng bộ nhớ tối đa mà một tập lệnh báo cáo lượt hiển thị hoặc phiên đấu giá có thể phân bổ. Tính năng giới hạn bộ nhớ yêu cầu có WebView phiên bản 105.0.5195.58 trở lên. Nền tảng sẽ thực thi quy trình kiểm tra phiên bản cũng như các lệnh gọi đến API selectAds và reportImpression sẽ không thành công nếu quy trình này không được thực thi. Có 2 lựa chọn để thiết lập:

   • Lựa chọn 1: Chạy lệnh adb sau để tắt quy trình kiểm tra này:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Lựa chọn 2: Cài đặt WebView bản Beta từ Cửa hàng Google Play. Phiên bản này phải bằng hoặc cao hơn phiên bản nêu trên.

Tham gia một đối tượng tuỳ chỉnh

Đối tượng tuỳ chỉnh đại diện cho một nhóm người dùng có cùng ý định hoặc mối quan tâm do một ứng dụng của nhà quảng cáo quyết định. Một ứng dụng hoặc SDK có thể sử dụng đối tượng tuỳ chỉnh để cho biết một đối tượng cụ thể, chẳng hạn như ai đó đã chọn sẵn các mặt hàng trong giỏ hàng. Để tạo hoặc tham gia một đối tượng tuỳ chỉnh một cách không đồng bộ, hãy làm như sau:

1. Khởi động đối tượng CustomAudienceManager.
2. Tạo đối tượng CustomAudience bằng cách chỉ định các tham số chính, chẳng hạn như gói của người mua và tên có liên quan. Sau đó, hãy khởi động đối tượng JoinCustomAudienceRequest bằng đối tượng CustomAudience.
3. Gọi joinCustomAudience() không đồng bộ với đối tượng JoinCustomAudienceRequest cũng như các đối tượng Executor và OutcomeReceiver có liên quan.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

Tổ hợp các tham số sau sẽ xác định duy nhất từng đối tượng CustomAudience trên thiết bị:

• owner: Tên gói ứng dụng của chủ sở hữu. Giá trị này được ngầm đặt thành tên gói của ứng dụng gọi.
• buyer: Giá trị nhận dạng của mạng quảng cáo của người mua quản lý quảng cáo cho đối tượng tuỳ chỉnh này.
• name: Tên hoặc giá trị nhận dạng tuỳ ý của đối tượng tuỳ chỉnh.

Việc gọi joinCustomAudience() nhiều lần bằng một thực thể khác của CustomAudience sẽ cập nhật mọi CustomAudience hiện có với tham số owner, buyer và name phù hợp. Để bảo vệ quyền riêng tư, kết quả của API không phân biệt giữa lệnh "tạo" và "cập nhật".

Ngoài ra, CustomAudience phải được tạo bằng các tham số bắt buộc sau:

• URL cập nhật hằng ngày: Một URL loại HTTPS được truy vấn hằng ngày ở chế độ nền để cập nhật các tín hiệu đặt giá thầu của người dùng thuộc đối tượng tuỳ chỉnh, dữ liệu đặt giá thầu đáng tin cậy, URL hiển thị và siêu dữ liệu cho quảng cáo.
• URL logic đặt giá thầu: Một URL loại HTTPS được truy vấn trong quá trình lựa chọn quảng cáo để tìm nạp logic đặt giá thầu JavaScript của người mua. Xem các chữ ký hàm bắt buộc trong JavaScript này.
• Mã nhận dạng hiển thị quảng cáo: Một mã nhận dạng tuỳ ý do công nghệ quảng cáo của người mua đặt. Đây là hoạt động tối ưu hoá để tạo tải trọng cho dịch vụ Đặt giá thầu và Phiên đấu giá (B&A).

Các tham số không bắt buộc cho đối tượng CustomAudience có thể bao gồm:

• Thời gian kích hoạt: Đối tượng tuỳ chỉnh chỉ có thể tham gia vào việc lựa chọn quảng cáo và cập nhật hằng ngày sau thời gian kích hoạt. Điều này, chẳng hạn, có thể có ích khi thu hút người dùng cũ.
• Thời gian hết hạn: Một khoảng thời gian trong tương lai mà sau đó đối tượng tuỳ chỉnh bị xoá khỏi thiết bị.
• Tín hiệu đặt giá thầu của người dùng: Một chuỗi JSON chứa các tín hiệu của người dùng, chẳng hạn như ngôn ngữ ưu tiên của người dùng, mà logic đặt giá thầu JavaScript của người mua sử dụng để tạo giá thầu trong quá trình lựa chọn quảng cáo. Định dạng này giúp các nền tảng công nghệ quảng cáo sử dụng lại mã trên nhiều nền tảng và giảm bớt mức sử dụng trong các hàm JavaScript.
• Dữ liệu đặt giá thầu đáng tin cậy: URL loại HTTPS và danh sách các chuỗi (dùng trong quá trình lựa chọn quảng cáo) tìm nạp tín hiệu đặt giá thầu từ dịch vụ Khoá/giá trị đáng tin cậy.
• Quảng cáo: Danh sách các đối tượng AdData tương ứng với các quảng cáo tham gia vào quá trình lựa chọn quảng cáo. Mỗi đối tượng AdData bao gồm:
  • URL hiển thị: URL HTTPS được truy vấn để hiển thị quảng cáo cuối cùng.
  • Siêu dữ liệu: Đối tượng JSON được chuyển đổi tuần tự dưới dạng một chuỗi chứa thông tin mà logic đặt giá thầu của người mua sẽ sử dụng trong quá trình lựa chọn quảng cáo.
  • Bộ lọc quảng cáo: Lớp chứa tất cả các thông tin cần thiết để lọc quảng cáo cài đặt ứng dụng và giới hạn tần suất trong quá trình lựa chọn quảng cáo.

Dưới đây là ví dụ về một lệnh tạo đối tượng CustomAudience:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

Xử lý kết quả joinCustomAudience()

Phương thức joinCustomAudience() không đồng bộ sử dụng đối tượng OutcomeReceiver để báo hiệu kết quả của lệnh gọi API.

• Lệnh gọi lại onResult() biểu thị đối tượng tuỳ chỉnh đã được tạo hoặc cập nhật thành công.
• Lệnh gọi lại onError() biểu thị 2 điều kiện có thể xảy ra.
  • Nếu JoinCustomAudienceRequest được khởi động bằng các đối số không hợp lệ, thì AdServicesException sẽ chỉ ra nguyên nhân là IllegalArgumentException.
  • Tất cả các lỗi khác nhận được AdServicesException với nguyên nhân là IllegalStateException.

Sau đây là ví dụ về cách xử lý kết quả của joinCustomAudience():

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

Rời khỏi một đối tượng tuỳ chỉnh

Nếu người dùng không còn đáp ứng các tiêu chí kinh doanh cho một đối tượng tuỳ chỉnh nhất định, thì ứng dụng hoặc SDK có thể gọi leaveCustomAudience() để xoá đối tượng tuỳ chỉnh khỏi thiết bị. Để xoá CustomAudience dựa trên các tham số riêng biệt, hãy làm như sau:

1. Khởi động đối tượng CustomAudienceManager.
2. Khởi động LeaveCustomAudienceRequest bằng name và buyer của đối tượng tuỳ chỉnh. Để tìm hiểu thêm về các trường nhập dữ liệu này, vui lòng đọc phần "Tham gia một đối tượng tuỳ chỉnh".
3. Gọi phương thức leaveCustomAudience() không đồng bộ với đối tượng LeaveCustomAudienceRequest cũng như các đối tượng. Executor và OutcomeReceiver có liên quan.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

Tương tự như việc gọi joinCustomAudience(), OutcomeReceiver báo hiệu việc kết thúc một lệnh gọi API. Để bảo vệ quyền riêng tư, kết quả lỗi không phân biệt giữa lỗi nội bộ và đối số không hợp lệ. Lệnh gọi lại onResult() được gọi khi lệnh gọi API đã hoàn tất, cho dù đối tượng tuỳ chỉnh phù hợp có được xoá thành công hay không.

Chạy quá trình lựa chọn quảng cáo

Để chọn quảng cáo bằng Protected Audience API, hãy gọi phương thức selectAds():

1. Khởi động một đối tượng AdSelectionManager.
2. Tạo một đối tượng AdSelectionConfig.
3. Gọi phương thức selectAds() không đồng bộ với đối tượng AdSelectionConfig cũng như các đối tượng. Executor và OutcomeReceiver có liên quan.

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

Phương thức selectAds() yêu cầu đầu vào AdSelectionConfig, trong đó bạn phải chỉ định các tham số bắt buộc sau:

• Người bán: Giá trị nhận dạng cho mạng quảng cáo của người bán bắt đầu quá trình lựa chọn quảng cáo.
• URL logic quyết định: URL loại HTTPS được truy vấn để lấy logic JavaScript của mạng quảng cáo cho người bán.
  • URL loại HTTPS: được truy vấn để lấy logic JavaScript của mạng quảng cáo cho người bán. Hãy xem các chữ ký hàm bắt buộc.
  • URI tạo sẵn: tuân theo định dạng lựa chọn quảng cáo của FLEDGE. IllegalArgumentException sẽ được gửi nếu truyền một URI tạo sẵn không được hỗ trợ hoặc sai định dạng.
• Người mua đối tượng tuỳ chỉnh: Danh sách đầy đủ các giá trị nhận dạng cho mạng quảng cáo của người mua được người bán cho phép tham gia vào quá trình lựa chọn quảng cáo. Các giá trị nhận dạng người mua này tương ứng với CustomAudience.getBuyer() của đối tượng tuỳ chỉnh tham gia.

Nếu muốn, bạn có thể chỉ định các tham số sau đây để lựa chọn thêm nhiều quảng cáo tuỳ chỉnh:

• Tín hiệu lựa chọn quảng cáo: Là một đối tượng JSON, được chuyển đổi tuần tự dưới dạng chuỗi, có chứa các tín hiệu được logic đặt giá thầu JavaScript của người mua (tìm nạp từ CustomAudience.getBiddingLogicUrl()) sử dụng.
• Tín hiệu của người bán: Là một đối tượng JSON, được chuyển đổi tuần tự dưới dạng chuỗi, có chứa các tín hiệu được logic quyết định JavaScript của người bán (tìm nạp từ AdSelectionConfig.getDecisionLogicUrl()) sử dụng.
• Tín hiệu trên mỗi người mua: Dữ liệu ánh xạ các đối tượng JSON, được chuyển đổi tuần tự dưới dạng chuỗi, có chứa các tín hiệu dùng cho logic đặt giá thầu JavaScript của người mua cụ thể (tìm nạp từ CustomAudience.getBiddingLogicUrl()). Các đối tượng này được xác định bằng các trường đối tượng tuỳ chỉnh tham gia của người mua.
• Quảng cáo theo bối cảnh: Tập hợp các đề xuất quảng cáo được thu thập trực tiếp từ người mua trong một phiên đấu giá diễn ra bên ngoài phiên đấu giá trong Protected Audience.

Sau khi bạn chọn một quảng cáo thì kết quả, giá thầu và tín hiệu sẽ được giữ lại trong máy để báo cáo. Lệnh gọi lại OutcomeReceiver.onResult() trả về một AdSelectionOutcome chứa:

• URL hiển thị của quảng cáo thắng cuộc, được lấy từ AdData.getRenderUrl().
• Mã nhận dạng lựa chọn quảng cáo dành riêng cho người dùng thiết bị. Mã này được dùng để báo cáo số lượt hiển thị quảng cáo.

Nếu bạn không thể hoàn tất việc lựa chọn quảng cáo vì những lý do như đối số không hợp lệ, hết thời gian chờ hoặc sử dụng tài nguyên quá mức, thì lệnh gọi lại OutcomeReceiver.onError() cung cấp AdServicesException với các hành vi dưới đây:

• Nếu quá trình lựa chọn quảng cáo được bắt đầu bằng các đối số không hợp lệ, AdServicesException cho biết nguyên nhân là IllegalArgumentException.
• Tất cả các lỗi khác nhận được AdServicesException với nguyên nhân là IllegalStateException.

Quảng cáo theo bối cảnh

Lọc quảng cáo cài đặt ứng dụng

Quy trình lọc quảng cáo cài đặt ứng dụng giúp bạn lọc quảng cáo cài đặt cho các ứng dụng đã cài đặt trên thiết bị.

Bước đầu tiên trong quy trình này là xác định những nhà quảng cáo có khả năng lọc theo gói đã cài đặt. Điều này cần xảy ra trong ứng dụng mà bạn muốn nhắm mục tiêu bằng một quảng cáo.

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

Khi mã trước đó thực thi, dữ liệu nhà quảng cáo đã được truyền vào có thể được dùng để lọc ra các ứng dụng đã cài đặt mà bạn chỉ định trong quá trình tạo giá thầu. Nếu bạn cần xoá một nhà quảng cáo để họ không truy cập được vào trạng thái cài đặt của ứng dụng này, hãy chạy lại mã này khi xoá thông tin của nhà quảng cáo đó.

Bước tiếp theo là thiết lập tính năng lọc quảng cáo bên trong ứng dụng của nhà xuất bản. Bên phân phát quảng cáo trong ứng dụng của nhà xuất bản (rất có thể là SDK phía cung) phải khởi tạo đối tượng AdFilters với thông tin về quảng cáo liên quan đến ứng dụng mà họ muốn lọc:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

Nhà xuất bản (phía cầu) cũng có thể đặt AdFilter cho quảng cáo tồn tại bên trong các đối tượng tuỳ chỉnh của họ.

AdFilters cũng có thể được truyền tại thời điểm tạo thực thể của đối tượng AdData mới:

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

Lọc giới hạn tần suất

Tính năng lọc giới hạn tần suất cho phép các công nghệ quảng cáo giới hạn số lần một quảng cáo xuất hiện. Tính năng lọc giới hạn tần suất giúp giảm tình trạng hiện quảng cáo quá mức và tối ưu hoá lựa chọn quảng cáo thay thế cho một chiến dịch quảng cáo nhất định.

Bộ lọc giới hạn tần suất có 2 thành phần chính: loại sự kiện quảng cáo và khoá bộ đếm quảng cáo. Sau đây là những loại sự kiện quảng cáo có thể sử dụng:

• Chiến thắng: Sự kiện chiến thắng cho biết rằng quảng cáo đó đã giành chiến thắng trong một phiên đấu giá. Các sự kiện chiến thắng được tự động cập nhật bằng Protected Audience API và nhà phát triển không thể gọi trực tiếp những sự kiện này. Dữ liệu chiến thắng chỉ hiển thị cho quảng cáo trong một đối tượng tuỳ chỉnh nhất định.
• Lượt hiển thị: Khác với reportImpression, phương thức gọi trên thiết bị (SSP hoặc MMP) dùng updateAdCounterHistogram() để gọi các sự kiện lượt hiển thị tại điểm trong mã mà họ chọn. Sự kiện hiển thị sẽ hiển thị cho tất cả các quảng cáo thuộc một DSP nhất định và không bị giới hạn ở các quảng cáo trong cùng một đối tượng tuỳ chỉnh.
• Khung hiển thị: Sự kiện được gọi bởi phương thức gọi trên thiết bị (SSP hoặc MMP) tại một điểm trong mã mà chúng chọn bằng lệnh gọi đến updateAdCounterHistogram(). Các sự kiện trong khung hiển thị sẽ hiển thị cho mọi quảng cáo thuộc một DSP nhất định và không bị giới hạn ở các quảng cáo trong cùng một Đối tượng tuỳ chỉnh.
• Lượt nhấp: Sự kiện được gọi bởi phương thức gọi trên thiết bị (SSP hoặc MMP) tại một điểm trong mã mà chúng chọn bằng cách sử dụng lệnh gọi đến updateAdCounterHistogram(). Sự kiện nhấp chuột hiển thị cho tất cả các quảng cáo thuộc về một DSP nhất định và không bị giới hạn ở những quảng cáo trong cùng một Đối tượng tuỳ chỉnh.

Trong ứng dụng của nhà xuất bản, SSP hoặc MMP có trên thiết bị sẽ gọi các sự kiện quảng cáo. Khi updateAdCounterHistogram() được gọi, bộ đếm của bộ lọc giới hạn tần suất sẽ tăng lên để các phiên đấu giá trong tương lai sẽ có thông tin cập nhật về mức hiển thị quảng cáo của người dùng. Các loại sự kiện quảng cáo không bị buộc liên kết với hành động tương ứng của người dùng và là nguyên tắc giúp phương thức gọi cấu trúc hệ thống sự kiện. Để tăng bộ đếm quảng cáo tại thời điểm diễn ra sự kiện, tác nhân trên thiết bị cung cấp mã lựa chọn quảng cáo của phiên đấu giá quảng cáo chiến thắng.

Khoá bộ đếm quảng cáo là các số nguyên 32 bit tuỳ ý đã ký do công nghệ quảng cáo của người mua chỉ định và tương ứng với một tập hợp quảng cáo nhất định do DSP xác định. Vì khoá bộ đếm quảng cáo chỉ được giới hạn cho quảng cáo thuộc một DSP nhất định, nên bạn có thể chọn các khoá này mà không chồng chéo với biểu đồ của một công nghệ quảng cáo khác. Khoá bộ đếm quảng cáo dùng để tăng giá trị nhận dạng dành riêng cho DSP trên các quảng cáo của DSP hoặc trong một đối tượng tuỳ chỉnh nhất định để lọc quảng cáo khỏi các phiên đấu giá trong tương lai.

Bạn có thể tận dụng khoá bộ đếm để ưu tiên những quảng cáo có nhiều khả năng thu hút người dùng nhất định dựa trên hoạt động tương tác của họ với các quảng cáo khác từ một công nghệ quảng cáo nhất định của người mua. Ví dụ: một quảng cáo đã nhận được mức độ tương tác cao từ các phiên đấu giá, lượt xem và lượt nhấp quảng cáo chiến thắng đại diện cho một điểm dữ liệu được dự đoán. Để minh hoạ rõ ràng hơn vấn đề này: một quảng cáo cho câu lạc bộ chơi gôn thuận tay trái có thể cho biết rằng người dùng sẽ không quan tâm đến câu lạc bộ thuận tay phải. Một bộ lọc giới hạn tần suất được đặt cho khoá bộ đếm được gán cho các quảng cáo cho câu lạc bộ thuận tay trái có thể lọc ra những quảng cáo cho các câu lạc bộ thuận tay phải.

Để sử dụng tính năng giới hạn tần suất trong phiên đấu giá, trước tiên, bạn phải tạo các đối tượng KeyedFrequencyCap như sau:

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

Sau khi tạo các đối tượng KeyedFrequencyCap, bạn có thể truyền những đối tượng đó vào đối tượng AdFilters.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

Khi đối tượng AdFilters được điền sẵn bộ lọc giới hạn tần suất, bạn có thể truyền đối tượng khi đối tượng tuỳ chỉnh được tạo:

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

Khi các bộ lọc giới hạn tần suất được triển khai cho một đối tượng tuỳ chỉnh, SSP có thể gọi các sự kiện lượt nhấp, lượt xem hoặc lượt hiển thị cần thiết.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

Các quảng cáo đã đạt đến giới hạn bộ lọc giới hạn tần suất đặt trước sẽ bị lọc ra khỏi phiên đấu giá. Quá trình lọc diễn ra trước khi thực thi logic đặt giá thầu cho các phiên đấu giá trên thiết bị, đồng thời tải trọng được tạo cho các phiên đấu giá của dịch vụ Đặt giá thầu và Phiên đấu giá. Bộ công cụ này cho phép các công nghệ quảng cáo sử dụng linh hoạt hoạt động tương tác giữa người dùng và quảng cáo trong đối tượng tuỳ chỉnh để tập trung nhắm mục tiêu quảng cáo, đồng thời giảm thiểu việc hiện quảng cáo quá nhiều lần.

Lọc quảng cáo theo bối cảnh mà không cần gọi mạng

Nếu không có nhu cầu tiếp thị lại trên thiết bị, bạn có thể chạy lựa chọn quảng cáo cho quảng cáo theo bối cảnh mà không cần gọi mạng. Với URI dựng sẵn và danh sách quảng cáo theo bối cảnh có giá thầu, nền tảng có thể bỏ qua khâu truy xuất logic đặt giá thầu, tín hiệu đặt giá thầu và tín hiệu tính điểm. Nền tảng này sử dụng URI dựng sẵn để chọn quảng cáo theo bối cảnh có giá thầu cao nhất.

Để giảm độ trễ, các công nghệ quảng cáo có thể chạy một quy trình lựa chọn quảng cáo chỉ bao gồm các quảng cáo theo bối cảnh có chức năng lọc quảng cáo mà không cần gọi mạng. Điều này được thực hiện bằng cách sử dụng URI dựng sẵn cho các tín hiệu tính điểm. Hãy tham khảo phần tên và trường hợp sử dụng được hỗ trợ của URI dựng sẵn để biết danh sách các phương thức triển khai scoreAds.

Cách chạy lựa chọn quảng cáo mà không cần gọi mạng:

1. Thiết lập tính năng lọc quảng cáo
2. Tạo quảng cáo theo bối cảnh

3. Tạo đối tượng AdSelectionConfig bằng các thành phần sau:

   1. Danh sách trống liệt kê người mua
   2. URI dựng sẵn để chọn giá thầu cao nhất
   3. Quảng cáo theo bối cảnh
   4. URI trống cho các tín hiệu tính điểm. Nền tảng này cho phép URI trống để cho biết rằng bạn không muốn dùng hoạt động tìm nạp tín hiệu đáng tin cho việc tính điểm:

   Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
   // Initialize AdSelectionConfig
   AdSelectionConfig adSelectionConfig =
     new AdSelectionConfig.Builder()
       .setSeller(seller)
       .setDecisionLogicUri(prebuiltURIScoringUri)
       .setCustomAudienceBuyers(Collections.emptyList())
       .setAdSelectionSignals(adSelectionSignals)
       .setSellerSignals(sellerSignals)
       .setPerBuyerSignals(perBuyerSignals)
       .setBuyerContextualAds(buyerContextualAds)
       .setTrustedScoringSignalsUri(Uri.EMPTY)
       .build();
   

4. Chạy lựa chọn quảng cáo:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Chạy JavaScript báo cáo của riêng bạn trong khi dùng các URI dựng sẵn

Hiện tại, nền tảng Hộp cát về quyền riêng tư chỉ có tính năng triển khai JavaScript báo cáo cơ bản dành cho các URI dựng sẵn. Nếu muốn chạy JavaScript báo cáo của riêng mình mà vẫn dùng URI dựng sẵn để chọn quảng cáo có độ trễ thấp, bạn có thể ghi đè DecisionLogicUri giữa các lần chạy lựa chọn quảng cáo và báo cáo.

1. Thực hiện các bước để chạy lựa chọn quảng cáo cho quảng cáo theo bối cảnh bằng URI dựng sẵn

2. Tạo bản sao của AdSelectionConfig trước khi chạy báo cáo

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. Chạy báo cáo về lượt hiển thị

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

Chạy quy trình dàn xếp kiểu thác nước

Tính năng dàn xếp kiểu thác nước đòi hỏi phải sắp xếp nhiều SDK của bên thứ ba (mạng bên thứ ba) bằng một mạng dàn xếp SDK của bên thứ nhất. Quy trình dàn xếp kiểu thác nước được thực hiện theo cách tương tự, bất kể phiên đấu giá diễn ra trên thiết bị hay chạy trên dịch vụ Đặt giá thầu và Phiên đấu giá (B&A).

Mạng bên thứ ba

Mạng bên thứ ba cần cung cấp một bộ chuyển đổi giúp cho phép mạng dàn xếp gọi các phương thức cần thiết để chạy phiên đấu giá:

• Chạy quá trình lựa chọn quảng cáo
• Báo cáo số lượt hiển thị

Dưới đây là ví dụ về bộ chuyển đổi của mạng dàn xếp:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Mỗi SDK có các ứng dụng và trình quản lý dịch vụ lựa chọn quảng cáo riêng, cũng như cách triển khai selectAds và reportImpressions riêng. Nhà cung cấp SDK có thể tham khảo các phần về cách chạy lựa chọn quảng cáo cho những phiên đấu giá trên thiết bị hoặc tài liệu giải thích về B&A cho những phiên đấu giá B&A. Làm theo cách báo cáo số lượt hiển thị quảng cáo (sau mục báo cáo lượt hiển thị SSP duy nhất) để báo cáo.

Mạng dàn xếp

Tương tự như các mạng bên thứ ba, mạng dàn xếp cần triển khai selectAds và reportImpression. Hãy tham khảo các mục về cách chạy lựa chọn quảng cáo và cách báo cáo số lượt hiển thị quảng cáo để biết thêm thông tin.

Mạng dàn xếp chịu trách nhiệm chạy chuỗi dàn xếp và tự đặt chúng vào chuỗi dàn xếp. Mục tiếp theo sẽ trình bày cách thiết lập và thực thi quy trình này.

Truy xuất chuỗi dàn xếp và giá thầu sàn

Mạng dàn xếp chịu trách nhiệm truy xuất quảng cáo theo bối cảnh của bên thứ nhất (1P), chuỗi dàn xếp và giá thầu sàn trong các mạng bên thứ ba (3P). Điều này có thể xảy ra trong yêu cầu truy xuất quảng cáo theo bối cảnh do mạng dàn xếp thực thi. Chuỗi dàn xếp xác định cách lặp lại thông qua Mạng bên thứ ba và giá thầu sàn có thể được truyền đến quy trình đấu giá dưới dạng adSelectionSignals.

Vị trí mạng trong chuỗi dàn xếp

SDK dàn xếp có thể tự đặt chúng trong chuỗi dàn xếp dựa trên chi phí hiệu quả trên mỗi nghìn lượt hiển thị (eCPM) trực tiếp của giá thầu quảng cáo bên thứ nhất. Trong Protected Audience API, giá thầu quảng cáo là không rõ ràng. SDK dàn xếp nên sử dụng AdSelectionFromOutcomesConfig để có thể so sánh giá thầu của một quảng cáo bên thứ nhất với giá thầu sàn của mạng bên thứ ba tiếp theo trong chuỗi. Nếu giá thầu bên thứ nhất cao hơn giá thầu sàn, điều đó có nghĩa là SDK dàn xếp được đặt trước mạng bên thứ ba đó.

Chạy quá trình lựa chọn quảng cáo

Để truy xuất đề xuất quảng cáo bên thứ nhất, mạng dàn xếp có thể thực thi phiên đấu giá trên thiết bị theo các bước trong mục chọn quảng cáo. Thao tác này sẽ tạo đề xuất quảng cáo của bên thứ nhất, giá thầu và AdSelectionId dùng trong quá trình dàn xếp.

Tạo AdSelectionFromOutcomesConfig

AdSelectionFromOutcomesConfig cho phép mạng dàn xếp truyền danh sách AdSelectionIds (kết quả từ các phiên đấu giá trước đó), tín hiệu lựa chọn quảng cáo và URI để tìm nạp JavaScript giúp chọn một quảng cáo từ nhiều đề xuất. Danh sách AdSelectionIds cùng với giá thầu và tín hiệu được chuyển đến JavaScript. JavaScript có thể trả về một trong các AdSelectionIds nếu giá thầu quảng cáo cao hơn giá thầu sàn hoặc trả về giá trị rỗng nếu chuỗi dàn xếp nên tiếp tục.

Mạng dàn xếp tạo AdSelectionFromOutcomesConfig bằng cách sử dụng AdSelectionId bên thứ nhất từ mục trước và giá thầu sàn cho Mạng bên thứ ba đang được xem xét. Bạn nên tạo một AdSelectionFromOutcomesConfig mới cho từng bước trong chuỗi dàn xếp.

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

Việc ghi đè phương thức selectAds() cho tính năng dàn xếp kiểu thác nước đòi hỏi phải nhập dữ liệu AdSelectionFromOutcomesConfig, trong đó bạn phải chỉ định các tham số bắt buộc sau đây:

• Người bán: Giá trị nhận dạng cho mạng quảng cáo của người bán bắt đầu quá trình lựa chọn quảng cáo.
• AdSelectionIds: Danh sách singleton của một selectAds() trước được chạy cho quảng cáo bên thứ nhất.
• Tín hiệu lựa chọn quảng cáo: Đối tượng JSON được chuyển đổi tuần tự dưới dạng một chuỗi, chứa các tín hiệu dùng cho logic đặt giá thầu của người mua. Trong trường hợp này, hãy thêm giá thầu sàn được truy xuất cho mạng bên thứ ba đã cho.
• URI logic lựa chọn: Một URL loại HTTPS được truy vấn trong quá trình lựa chọn quảng cáo nhằm tìm nạp JavaScript của mạng dàn xếp để chọn một quảng cáo chiến thắng. Xem các chữ ký hàm bắt buộc trong JavaScript này. JavaScript sẽ trả về quảng cáo của bên thứ ba nếu giá thầu cao hơn giá thầu sàn hoặc trả về null. Điều này cho phép SDK dàn xếp cắt bớt chuỗi dàn xếp khi tìm thấy quảng cáo chiến thắng.

Sau khi tạo AdSelectionOutcomesConfig, hãy gọi phương thức selectAds() của mạng bên thứ ba đầu tiên trong chuỗi.

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

Sắp xếp quy trình dàn xếp kiểu thác nước

Dưới đây là thứ tự các thao tác cần chạy trong quy trình dàn xếp.

1. Chạy lựa chọn quảng cáo bên thứ nhất.
2. Lặp lại trên chuỗi dàn xếp. Đối với mỗi mạng bên thứ ba, hãy làm như sau:
   1. Tạo AdSelectionFromOutcomeConfig bao gồm outcomeId bên thứ nhất và giá thầu sàn của SDK bên thứ ba.
   2. Gọi selectAds() bằng cấu hình ở bước trước.
   3. Nếu kết quả không trống, hãy trả về quảng cáo.
   4. Gọi phương thức selectAds() của bộ chuyển đổi mạng SDK hiện tại. Nếu kết quả không trống, hãy trả về quảng cáo.
3. Nếu không tìm thấy quảng cáo chiến thắng từ chuỗi, hãy trả về quảng cáo bên thứ nhất.

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

Báo cáo số lượt hiển thị quảng cáo

Có hai quy trình để báo cáo lượt hiển thị quảng cáo tuỳ thuộc vào cách chạy phiên đấu giá. Nếu bạn là một SSP chạy phiên đấu giá, hãy làm theo mục dưới đây. Nếu bạn định triển khai tính năng dàn xếp kiểu thác nước, hãy làm theo các bước trong mục báo cáo lượt hiển thị trong quy trình dàn xếp kiểu thác nước.

Báo cáo về lượt hiển thị trên một SSP

Sau khi đã chọn một quảng cáo giành chiến thắng trong quy trình lựa chọn quảng cáo, bạn có thể báo cáo lượt hiển thị cho nền tảng bên mua và bên bán tham gia bằng phương thức AdSelectionManager.reportImpression(). Để báo cáo một lượt hiển thị quảng cáo, hãy làm như sau:

1. Khởi động một đối tượng AdSelectionManager.
2. Tạo đối tượng ReportImpressionRequest bằng mã lựa chọn quảng cáo.
3. Gọi phương thức reportImpression() không đồng bộ với đối tượng ReportImpressionRequest cũng như các đối tượng. Executor và OutcomeReceiver có liên quan.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

Khởi động ReportImpressionRequest bằng các tham số bắt buộc sau:

• Mã lựa chọn quảng cáo: Mã nhận dạng duy nhất cho một người dùng thiết bị xác định một lựa chọn quảng cáo thành công.
• Cấu hình lựa chọn quảng cáo: Cấu hình tương tự dùng trong lệnh gọi selectAds() được xác định theo mã lựa chọn quảng cáo đã cung cấp.

Phương thức reportImpression() không đồng bộ sử dụng đối tượng OutcomeReceiver để báo hiệu kết quả của lệnh gọi API.

• Lệnh gọi lại onResult() cho biết liệu URL báo cáo lượt hiển thị đã được tạo và yêu cầu đã được lên lịch hay chưa.
• Lệnh gọi lại onError() cho biết các tình trạng sau đây có thể xảy ra:
  • Nếu lệnh gọi được khởi tạo bằng một đối số đầu vào không hợp lệ, AdServicesException sẽ cho biết nguyên nhân là IllegalArgumentException.
  • Tất cả các lỗi khác nhận được AdServicesException với nguyên nhân là IllegalStateException.

Báo cáo lượt hiển thị trong quy trình dàn xếp kiểu thác nước

Một SDK dàn xếp cần theo dõi SDK chiến thắng để kích hoạt luồng báo cáo của các SDK đó. Các SDK tham gia vào chuỗi dàn xếp phải cung cấp một phương thức để bên trung gian kích hoạt quy trình báo cáo của riêng họ. SDK tham gia vào phiên đấu giá đã dàn xếp có thể làm theo các bước ở trên để triển khai quy trình báo cáo của riêng họ.

SSP có thể sử dụng nguyên mẫu là ví dụ về mã SDK bên thứ ba này để tham gia quy trình dàn xếp:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

Điểm cuối của báo cáo lượt hiển thị

API lượt hiển thị báo cáo sẽ gửi yêu cầu HTTPS GET đến các điểm cuối do nền tảng bên bán và bên mua thắng cuộc cung cấp:

Điểm cuối trên nền tảng bên mua:

• API này sử dụng URL logic đặt giá thầu được chỉ định trong đối tượng tuỳ chỉnh để tìm nạp JavaScript do người mua cung cấp, bao gồm cả logic để trả về URL báo cáo lượt hiển thị.
• Gọi hàm JavaScript reportWin(). Hàm này dự kiến sẽ trả về URL báo cáo lượt hiển thị của người mua.

Điểm cuối trên nền tảng bên bán:

• Sử dụng URL logic quyết định được chỉ định trong đối tượng AdSelectionConfig để tìm nạp logic quyết định JavaScript của người bán.
• Gọi hàm JavaScript reportResult(). Hàm này dự kiến sẽ trả về URL báo cáo lượt hiển thị của người mua.

Báo cáo dịch vụ Đặt giá thầu và Phiên đấu giá

Một phiên đấu giá được thực thi trên các dịch vụ Đặt giá thầu và Phiên đấu giá sẽ có mọi thông tin báo cáo cần thiết, bao gồm cả những URL được tạo để báo cáo lượt tương tác với quảng cáo, có trong phản hồi được mã hoá từ phiên đấu giá phía máy chủ. Khi phản hồi được giải mã, các URL thích hợp sẽ được đăng ký với nền tảng, vì vậy, việc báo cáo quảng cáo và lượt hiển thị cũng tuân theo những bước nêu trên.

Báo cáo lượt hiển thị tuỳ khả năng

Phương thức reportImpression() được thiết kế để mang lại khả năng hoàn thành báo cáo tốt nhất.

Báo cáo lượt tương tác với quảng cáo

Protected Audience hỗ trợ báo cáo các lượt tương tác chi tiết hơn cho quảng cáo được hiển thị. Báo cáo này có thể bao gồm các lượt tương tác như thời gian xem, lượt nhấp, thao tác di chuột hoặc bất kỳ chỉ số hữu ích nào khác có thể thu thập được. Quy trình nhận các báo cáo này cần có 2 bước. Trước tiên, người mua và người bán phải đăng ký nhận các báo cáo này trong JavaScript báo cáo của họ. Sau đó, ứng dụng cần báo cáo các sự kiện này.

Đăng ký nhận sự kiện tương tác

Việc đăng ký nhận các sự kiện tương tác diễn ra trong hàm JavaScript reportWin() của người mua và reportResult() của người bán bằng cách sử dụng hàm JavaScript do nền tảng cung cấp: registerAdBeacon. Để đăng ký nhận báo cáo sự kiện, bạn chỉ cần gọi Hàm JavaScript của nền tảng từ JavaScript báo cáo. Đoạn mã sau dùng reportWin() của người mua nhưng phương pháp áp dụng cho reportResult() cũng tương tự.

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri
    registerAdBeacon("click", clickUri)
    registerAdBeacon("view", viewUri)
    registerAdBeacon("hover", hoverUri)

    return reportingUrl;
}

Báo cáo sự kiện tương tác

Sau khi báo cáo một lượt hiển thị, ứng dụng có thể áp dụng phương thức AdSelectionManager.reportInteraction() để báo cáo lượt tương tác đó trở lại các nền tảng bên mua và bên bán thắng cuộc đã đăng ký trước đây. Cách báo cáo sự kiện quảng cáo:

1. Khởi động một đối tượng AdSelectionManager.
2. Tạo đối tượng ReportInteractionRequest bằng mã lựa chọn quảng cáo, khoá tương tác, dữ liệu về lượt tương tác và đích báo cáo.
3. Gọi phương thức reportInteraction() không đồng bộ bằng đối tượng request cũng như các đối tượng Executor và OutcomeReceiver có liên quan.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

Khởi động ReportInteractionRequest bằng các tham số bắt buộc sau:

• Mã lựa chọn quảng cáo: Mã lựa chọn quảng cáo được truy xuất từ AdSelectionOutcome trước đó đã trả về.
• Khoá tương tác: Khoá chuỗi do ứng dụng xác định mô tả thao tác đang được báo cáo. Khoá này phải khớp với khoá mà người bán hoặc người mua đã đăng ký trong các hàm JavaScript báo cáo.
• Dữ liệu về lượt tương tác: Chuỗi chứa dữ liệu sẽ được đưa vào báo cáo sự kiện để được POST trở lại máy chủ báo cáo.
• Đích báo cáo: Mặt nạ bit chỉ định liệu sự kiện sẽ được báo cáo cho người mua, người bán hay cả hai. Những cờ này do nền tảng cung cấp và mặt nạ đích cuối cùng có thể được tạo bằng các thao tác bit. Để báo cáo cho một đích đến, bạn có thể sử dụng cờ do nền tảng trực tiếp cung cấp. Để báo cáo cho nhiều đích đến, bạn có thể sử dụng thao tác bit HOẶC (|) để kết hợp các giá trị cờ.

Phương thức reportInteraction() không đồng bộ sử dụng đối tượng OutcomeReceiver để báo hiệu kết quả của lệnh gọi API.

• Lệnh gọi lại onResult() cho biết lệnh gọi tương tác báo cáo là hợp lệ.
• Lệnh gọi lại onError() cho biết các tình trạng sau đây có thể xảy ra:
  • Nếu lệnh gọi được thực hiện khi ứng dụng đang chạy ở chế độ nền, thì một IllegalStateException có mô tả lỗi sẽ được trả về.
  • Nếu ứng dụng bị điều tiết khi gọi reportInteraction(), thì LimitExceededException sẽ được trả về.
  • Nếu gói không được đăng ký để gọi các Privacy Preserving API (API Bảo đảm quyền riêng tư), thì SecurityException() sẽ được trả về.
  • Nếu số lượt tương tác theo báo cáo của ứng dụng khác với của ứng dụng đã gọi selectAds(), thì IllegalStateException sẽ được trả về.
• Nếu người dùng chưa đồng ý bật các Privacy Sandbox API (API Hộp cát về quyền riêng tư), thì lệnh gọi sẽ tự động không thực hiện được.

Điểm cuối báo cáo lượt tương tác

API báo cáo lượt tương tác đưa ra yêu cầu POST qua HTTPS cho các điểm cuối do nền tảng bên bán và nền tảng bên mua thắng cuộc cung cấp. Protected Audience sẽ so khớp các khoá tương tác với các URI được khai báo khi báo cáo JavaScript và đưa ra yêu cầu POST cho mỗi điểm cuối của từng lượt tương tác đang được báo cáo. Loại nội dung của yêu cầu này là loại văn bản thuần tuý với phần nội dung là Dữ liệu về lượt tương tác.

Báo cáo lượt tương tác tuỳ khả năng

reportInteraction() được thiết kế để mang lại khả năng hoàn thành báo cáo tốt nhất thông qua yêu cầu POST qua HTTP.

Cập nhật hằng ngày ở chế độ nền

Khi tạo một đối tượng tuỳ chỉnh, ứng dụng hoặc SDK của bạn có thể khởi động siêu dữ liệu đối tượng tuỳ chỉnh. Ngoài ra, nền tảng có thể cập nhật các siêu dữ liệu đối tượng tuỳ chỉnh sau đây bằng quy trình cập nhật hằng ngày ở chế độ nền.

• Tín hiệu đặt giá thầu của người dùng
• Dữ liệu đặt giá thầu đáng tin cậy
• Danh sách AdData

Quá trình này truy vấn URL cập nhật hằng ngày được xác định trong đối tượng tuỳ chỉnh và URL có thể trả về phản hồi JSON.

• Phản hồi JSON có thể chứa bất kỳ trường siêu dữ liệu nào được hỗ trợ cần được cập nhật.
• Mỗi trường JSON sẽ được xác thực một cách độc lập. Máy khách sẽ bỏ qua mọi trường không đúng định dạng dẫn đến việc không có nội dung cập nhật của trường cụ thể đó trong phản hồi.
• Phản hồi HTTP trống hoặc đối tượng JSON trống "{}" sẽ dẫn đến việc không cập nhật siêu dữ liệu.
• Kích thước của thông báo phản hồi phải được giới hạn ở mức 10 KB.
• Bạn cần phải có tất cả các URI để sử dụng HTTPS.
• trusted_bidding_uri phải chia sẻ cùng một ETLD+1 với người mua.

Ví dụ: phản hồi JSON cho tính năng cập nhật hằng ngày ở chế độ nền

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

JavaScript cho lựa chọn quảng cáo

Quy trình lựa chọn quảng cáo phối hợp thực thi JavaScript do người mua và người bán cung cấp.

JavaScript do người mua cung cấp được tìm nạp từ URL logic Đặt giá thầu đã chỉ định trong đối tượng tuỳ chỉnh. JavaScript được trả về phải bao gồm các hàm sau:

• generateBid()
• reportWin()

JavaScript do người bán cung cấp được tìm nạp từ URL logic quyết định được chỉ định trong tham số AdSelectionConfig cho API lựa chọn quảng cáo. JavaScript được trả về phải bao gồm các hàm sau:

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

Tham số đầu vào:

• ad: đối tượng JSON có định dạng var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: Các đối tượng JSON được chỉ định trong đối tượng cấu hình phiên đấu giá

• custom_audience_bidding_signals: đối tượng JSON do nền tảng tạo. Định dạng của đối tượng JSON này là:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  trong đó:

  • owner, buyer và name là chuỗi được lấy từ các thuộc tính có cùng tên của Đối tượng tuỳ chỉnh tham gia vào quá trình lựa chọn quảng cáo
  • activation_time và expiration_time là thời gian kích hoạt và hết hạn của đối tượng tuỳ chỉnh, được biểu thị bằng giây kể từ Thời gian bắt đầu của hệ thống Unix
  • ca_user_bidding_signals là một chuỗi JSON được chỉ định trong trường userBiddingSignals của CustomAudience tại thời điểm tạo
  • trusted_bidding_signals, contextual_signals và user_signals là các đối tượng JSON. Chúng được truyền dưới dạng các đối tượng trống và sẽ được đưa vào các bản phát hành trong tương lai. Định dạng của chúng không được nền tảng thực thi và do công nghệ quảng cáo quản lý.

Kết quả:

• ad: là quảng cáo mà giá thầu đề cập. Tập lệnh được phép trả về bản sao của quảng cáo đã nhận được cùng với siêu dữ liệu khác. Thuộc tính render_url của quảng cáo dự kiến sẽ không bị thay đổi.
• bid: một giá trị số thực biểu thị giá trị giá thầu cho quảng cáo này
• status: một giá trị số nguyên có thể là:
  • 0: đối với trường hợp thực thi thành công
  • 1: (hoặc bất kỳ giá trị nào khác 0) trong trường hợp có bất kỳ tín hiệu đầu vào nào không hợp lệ. Trong trường hợp giá trị khác 0 được trả về bằng cách tạo giá thầu, quá trình đặt giá thầu sẽ không hợp lệ đối với tất cả quảng cáo dành cho CA

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Tham số đầu vào:

• ad: vui lòng xem tài liệu về generateBid
• bid: giá trị giá thầu cho quảng cáo

• ad_selection_config: một đối tượng JSON đại diện cho tham số AdSelectionConfig của API selectAds. Định dạng là:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• seller_signals: Các đối tượng JSON được đọc từ tham số API sellerSignals AdSelectionConfig

• trusted_scoring_signal: đọc từ trường adSelectionSignals trong tham số API AdSelectionConfig

• contextual_signals, user_signals: Đối tượng JSON. Hiện tại, chúng được truyền dưới dạng các đối tượng trống và sẽ được đưa vào các bản phát hành trong tương lai. Định dạng của chúng không được nền tảng thực thi và do công nghệ quảng cáo quản lý.

• per_buyer_signals: Đối tượng JSON được đọc từ bản đồ perBuyerSignal trong tham số API AdSelectionConfig sử dụng làm khoá cho người mua Đối tượng tuỳ chỉnh hiện tại. Để trống nếu bản đồ không chứa bất kỳ mục nhập nào cho người mua cụ thể.

Kết quả:

• score: một giá trị số thực đại diện giá trị điểm số cho quảng cáo này
• status: một giá trị số nguyên có thể là:
  • 0: để thực thi thành công
  • 1: trong trường hợp customAudienceSignals không hợp lệ
  • 2: trong trường hợp AdSelectionConfig không hợp lệ
  • 3: trong trường hợp có bất kỳ tín hiệu nào khác không hợp lệ
  • Bất kỳ giá trị nào khác 0 đều gây ra lỗi xử lý, giá trị này xác định các trường hợp ngoại lệ được gửi

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Tham số đầu vào:

• outcomes: đối tượng JSON {"id": id_string, "bid": bid_double}
• selection_signals: Các đối tượng JSON được chỉ định trong đối tượng định cấu hình đấu giá

Kết quả:

• status: là 0 nếu thành công và khác 0 nếu không thành công
• result: một trong những kết quả được truyền vào hoặc giá trị rỗng

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

Tham số đầu vào:

• ad_selection_config: vui lòng xem tài liệu scoreAds
• render_url: URL hiển thị của quảng cáo giành chiến thắng
• bid: giá thầu được cung cấp cho quảng cáo giành chiến thắng
• contextual_signals: vui lòng xem tài liệu generateBid

Kết quả:

• status: 0 cho trạng thái thành công và khác 0 cho trạng thái không thành công
• results: đối tượng JSON chứa:
  • signals_for_buyer: đối tượng JSON được truyền đến hàm reportWin
  • reporting_url: URL được nền tảng sử dụng để thông báo về lượt hiển thị cho người mua

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

Tham số đầu vào:

• ad_selection_signals, per_buyer_signals: vui lòng xem tài liệu cho scoreAd
• signals_for_buyer: đối tượng JSON do reportResult trả về
• contextual_signals, custom_audience_signals: vui lòng xem tài liệu generateBid

Kết quả:

• status: 0 cho trạng thái thành công và khác 0 cho trạng thái không thành công
• results: đối tượng JSON chứa:
  • reporting_url: URL được nền tảng sử dụng để thông báo về lượt hiển thị cho người bán

registerAdBeacon()

function registerAdBeacon(
  interaction_key,
  reporting_uri
)

Tham số đầu vào:

• interaction_key: Chuỗi đại diện cho sự kiện. Nền tảng sẽ sử dụng khoá này sau vào thời điểm báo cáo các lượt tương tác với sự kiện để tra cứu reporting_uri cần được thông báo. Khoá này phải khớp giữa nội dung mà người mua hoặc người bán đang đăng ký và nội dung mà người bán đang báo cáo.
• reporting_uri: URI để nhận báo cáo sự kiện. URI này phải dành riêng cho loại sự kiện đang được báo cáo. URI này phải chấp nhận yêu cầu POST để xử lý mọi dữ liệu được báo cáo cùng với sự kiện.

URI dựng sẵn cho lựa chọn quảng cáo

URI dựng sẵn mang lại cho công nghệ quảng cáo khả năng chỉ định các hàm JavaScript cho logic quyết định lựa chọn quảng cáo trong các lớp AdSelectionConfig và AdSelectionFromOutcomesConfig. URI dựng sẵn không yêu cầu gọi mạng để tải JavaScript tương ứng xuống. Công nghệ quảng cáo có thể dùng các URI dựng sẵn mà không cần thiết lập miền đăng ký để lưu trữ JavaScript.

URI dựng sẵn được thiết kế theo định dạng sau:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

Nền tảng Hộp cát về quyền riêng tư dùng thông tin từ URI này trong thời gian chạy để cung cấp JavaScript.

Hệ thống sẽ gửi một IllegalArgumentException nếu:

• thiếu bất kỳ tham số bắt buộc nào trong URI
• có tham số không nhận dạng được trong URI

Tên và trường hợp sử dụng được hỗ trợ của URI dựng sẵn

Trường hợp sử dụng 1: ad-selection

Các URI dựng sẵn trong trường hợp sử dụng ad-selection được hỗ trợ trong quy trình selectAds(AdSelectionConfig).

Tên URI dựng sẵn: highest-bid-wins

URI dựng sẵn này cung cấp một JavaScript chọn quảng cáo có giá thầu cao nhất sau khi đặt giá thầu. URI này cũng cung cấp chức năng báo cáo cơ bản để báo cáo render_uri và bid của quảng cáo chiến thắng.

Tham số bắt buộc

reportingUrl: URL báo cáo cơ bản được tham số hoá bằng render_uri và bid của quảng cáo chiến thắng:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

Tác dụng

Nếu URL báo cáo cơ bản của bạn là https://www.ssp.com/reporting thì URI dựng sẵn sẽ là:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Trường hợp sử dụng 2: ad-selection-from-outcomes

Các URI dựng sẵn trong trường hợp sử dụng ad-selection-from-outcomes hỗ trợ quy trình công việc selectAds(AdSelectionFromOutcomesConfig).

Tên URI dựng sẵn: waterfall-mediation-truncation

URI dựng sẵn waterfall-mediation-truncation cung cấp JavaScript triển khai logic cắt bớt dàn xếp kiểu thác nước, trong đó JavaScript trả về quảng cáo của bên thứ nhất nếu bid cao hơn hoặc bằng bid floor, còn nếu không sẽ trả về null.

Tham số bắt buộc

bidFloor: Khoá của giá trị giá thầu tối thiểu đã chuyển trong getSelectionSignals() được so sánh với quảng cáo của SDK dàn xếp.

Tác dụng

Nếu tín hiệu lựa chọn quảng cáo của bạn có dạng {"bid_floor": 10} thì URI dựng sẵn sẽ là:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

Kiểm thử

Để giúp bạn bắt đầu làm quen với Protected Audience API, chúng tôi đã tạo các ứng dụng mẫu trong Kotlin và Java, có thể tìm thấy trên GitHub.

Điều kiện tiên quyết

Protected Audience API yêu cầu một số JavaScript trong quá trình lựa chọn quảng cáo và báo cáo số lượt hiển thị. Có 2 phương thức để cung cấp JavaScript này trong môi trường thử nghiệm:

• Chạy máy chủ với các điểm cuối HTTPS bắt buộc trả về JavaScript
• Ghi đè tính năng tìm nạp từ xa bằng cách cung cấp mã cần thiết từ một nguồn cục bộ

Một trong hai cách tiếp cận đều yêu cầu thiết lập một điểm cuối HTTPS để xử lý báo cáo lượt hiển thị.

Điểm cuối HTTPS

Để kiểm thử lựa chọn quảng cáo và báo cáo lượt hiển thị, bạn cần lập 7 điểm cuối HTTPS mà thiết bị kiểm thử hoặc trình mô phỏng có thể truy cập:

1. Điểm cuối của người mua phân phát JavaScript logic đặt giá thầu.
2. Một điểm cuối phân phát các tín hiệu đặt giá thầu.
3. Điểm cuối của người bán phân phát JavaScript logic quyết định.
4. Một điểm cuối phân phát tín hiệu tính điểm.
5. Điểm cuối báo cáo lượt hiển thị của người mua giành được quyền mua.
6. Điểm cuối báo cáo lượt hiển thị của người bán.
7. Một điểm cuối phân phát các bản cập nhật hằng ngày cho đối tượng tuỳ chỉnh.

Để thuận tiện, kho lưu trữ GitHub cung cấp mã JavaScript cơ bản cho mục đích kiểm thử. Phiên bản này cũng bao gồm các định nghĩa dịch vụ OpenAPI có thể được triển khai cho các nền tảng mô phỏng hoặc nền tảng vi dịch vụ được hỗ trợ. Để biết thêm thông tin chi tiết, vui lòng tham khảo phần README của dự án.

Ghi đè tính năng tìm nạp từ xa của JavaScript

Bạn có thể dùng tính năng này để thử nghiệm một cách toàn diện. Để ghi đè tính năng tìm nạp từ xa, ứng dụng của bạn phải chạy ở chế độ gỡ lỗi và bật các tuỳ chọn cho nhà phát triển.

Để bật chế độ gỡ lỗi cho ứng dụng của bạn, hãy thêm dòng sau vào thuộc tính ứng dụng trong AndroidManifest.xml:

<application
  android:debuggable="true">

Để xem ví dụ về cách sử dụng các cơ chế ghi đè này, vui lòng xem ứng dụng mẫu của Protected Audience API trên GitHub.

Bạn cần thêm JavaScript tuỳ chỉnh của riêng mình để xử lý các quy trình lựa chọn quảng cáo, chẳng hạn như chiến lược đặt giá thầu, quyết định về cách tính điểm và hoạt động báo cáo. Bạn có thể tìm thấy các ví dụ về mã JavaScript cơ bản giúp xử lý tất cả các yêu cầu bắt buộc trong kho lưu trữ GitHub. Ứng dụng mẫu của Protected Audience API minh hoạ cách đọc mã từ tệp đó và chuẩn bị mã để sử dụng làm cơ chế ghi đè.

Bạn có thể ghi đè phương thức tìm nạp JavaScript bên bán và bên mua một cách độc lập, mặc dù bạn cần có một điểm cuối HTTPS để phân phát bất kỳ JavaScript nào mà bạn không cung cấp cơ chế ghi đè. Vui lòng xem phần README để biết thông tin về cách thiết lập máy chủ giúp xử lý các trường hợp này.

Bạn chỉ có thể ghi đè phương thức tìm nạp JavaScript cho các đối tượng tuỳ chỉnh thuộc gói của mình.

Ghi đè JavaScript bên bán

Để thiết lập cơ chế ghi đè cho JavaScript bên bán, hãy thực hiện giống phần được minh hoạ trong ví dụ về mã sau:

1. Khởi động một đối tượng AdSelectionManager.
2. Tạo một tham chiếu đến TestAdSelectionManager từ đối tượng AdSelectionManager.
3. Tạo một đối tượng AdSelectionConfig.
4. Tạo AddAdSelectionOverrideRequest với đối tượng AdSelectionConfig và một String đại diện cho JavaScript mà bạn định dùng để ghi đè.
5. Gọi phương thức overrideAdSelectionConfigRemoteInfo() không đồng bộ bằng đối tượng AddAdSelectionOverrideRequest cũng như các đối tượng Executor và OutcomeReceiver có liên quan.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

Vui lòng xem phần Chạy quá trình lựa chọn quảng cáo để biết thêm thông tin về nội dung đại diện của từng trường trong AdSelectionConfig. Điểm khác biệt chính là decisionLogicUrl có thể được đặt thành giá trị phần giữ chỗ vì hệ thống sẽ bỏ qua giá trị này.

Để ghi đè JavaScript dùng trong quá trình lựa chọn quảng cáo, decisionLogicJs phải chứa các chữ ký hàm thích hợp của bên bán. Để xem ví dụ về cách đọc tệp JavaScript dưới dạng chuỗi, hãy tham khảo ứng dụng mẫu của Protected Audience API trên GitHub.

Phương thức overrideAdSelectionConfigRemoteInfo() không đồng bộ sử dụng đối tượng OutcomeReceiver để ra hiệu về kết quả của lệnh gọi API.

Lệnh gọi lại onResult() cho biết thao tác ghi đè đã được áp dụng thành công. Các lệnh gọi trong tương lai đến selectAds() sẽ sử dụng bất kỳ quyết định và logic báo cáo nào mà bạn đã truyền vào làm thông tin ghi đè.

Lệnh gọi lại onError() biểu thị hai điều kiện có thể xảy ra:

• Nếu bạn cố gắng ghi đè các đối số không hợp lệ, thì AdServiceException sẽ cho biết nguyên nhân là IllegalArgumentException.
• Nếu bạn cố gắng ghi đè một ứng dụng không chạy ở chế độ gỡ lỗi khi đã bật các tuỳ chọn cho nhà phát triển, thì AdServiceException sẽ cho biết nguyên nhân là IllegalStateException.

Đặt lại tuỳ chọn ghi đè bên bán

Phần này giả định bạn đã ghi đè JavaScript bên bán, đồng thời bạn có tham chiếu đến TestAdSelectionManager và AdSelectionConfig được sử dụng trong phần trước.

Để đặt lại thông tin ghi đè cho tất cả các đối tượng AdSelectionConfigs:

1. Hãy gọi phương thức resetAllAdSelectionConfigRemoteOverrides() không đồng bộ bằng đối tượng OutcomeReceiver có liên quan.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

Sau khi bạn đặt lại cơ chế ghi đè bên bán, các lệnh gọi đến selectAds() sẽ sử dụng bất kỳ decisionLogicUrl nào được lưu trữ trong AdSelectionConfig để cố tìm nạp JavaScript cần thiết.

Nếu lệnh gọi đến resetAllAdSelectionConfigRemoteOverrides() không thành công, lệnh gọi lại OutComeReceiver.onError() sẽ cung cấp một AdServiceException. Nếu bạn cố gắng xoá nội dung ghi đè khi ứng dụng không chạy ở chế độ gỡ lỗi có bật tuỳ chọn dành cho nhà phát triển, thì AdServiceException sẽ cho biết nguyên nhân là IllegalStateException.

Ghi đè JavaScript bên mua

1. Làm theo các bước để tham gia vào một đối tượng tuỳ chỉnh
2. Tạo AddCustomAudienceOverrideRequest với người mua và tên của đối tượng tuỳ chỉnh mà bạn muốn ghi đè, ngoài logic đặt giá thầu và dữ liệu mà bạn muốn sử dụng làm cơ chế ghi đè
3. Gọi phương thức overrideCustomAudienceRemoteInfo() không đồng bộ bằng đối tượng AddCustomAudienceOverrideRequest cũng như các đối tượng Executor và OutcomeReceiver có liên quan.

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

Giá trị biểu thị người mua và tên là các giá trị giống nhau, dùng để tạo đối tượng tuỳ chỉnh. Tìm hiểu thêm về các trường này.

Ngoài ra, bạn có thể chỉ định hai tham số bổ sung:

• biddingLogicJs: JavaScript chứa logic của người mua được sử dụng trong quá trình lựa chọn quảng cáo. Xem các chữ ký hàm bắt buộc trong JavaScript này.
• trustedBiddingSignals: Các tín hiệu đặt giá thầu sẽ được sử dụng trong quá trình lựa chọn quảng cáo. Đối với mục đích thử nghiệm, đây có thể là một chuỗi trống.

Phương thức overrideCustomAudienceRemoteInfo() không đồng bộ sử dụng đối tượng OutcomeReceiver để cho biết kết quả của lệnh gọi API.

Lệnh gọi lại onResult() cho biết thao tác ghi đè đã được áp dụng thành công. Các lệnh gọi tiếp theo tới selectAds() sẽ sử dụng bất kỳ logic báo cáo và đặt giá thầu nào mà bạn đã truyền vào làm thông tin ghi đè.

Lệnh gọi lại onError() biểu thị 2 điều kiện có thể xảy ra.

• Nếu bạn cố gắng ghi đè các đối số không hợp lệ, thì AdServiceException sẽ cho biết nguyên nhân là IllegalArgumentException.
• Nếu bạn cố gắng ghi đè một ứng dụng không chạy ở chế độ gỡ lỗi khi đã bật các tuỳ chọn cho nhà phát triển, thì AdServiceException sẽ cho biết nguyên nhân là IllegalStateException.

Đặt lại cơ chế ghi đè bên mua

Phần này giả định bạn đã ghi đè JavaScript bên mua, đồng thời bạn có tham chiếu đến TestCustomAudienceManager được sử dụng trong phần trước.

Cách đặt lại cơ chế ghi đè cho tất cả các đối tượng tuỳ chỉnh:

1. Hãy gọi phương thức resetAllCustomAudienceOverrides() không đồng bộ với các đối tượng Executor và OutcomeReceiver có liên quan.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

Sau khi bạn đặt lại cơ chế ghi đè bên mua, các lệnh gọi tiếp theo tới selectAds() sẽ sử dụng bất kỳ biddingLogicUrl và trustedBiddingData nào được lưu trữ trong CustomAudience để cố tìm nạp JavaScript cần thiết.

Nếu lệnh gọi đến resetCustomAudienceRemoteInfoOverride() không thành công, lệnh gọi lại OutComeReceiver.onError() sẽ cung cấp một AdServiceException. Nếu bạn cố gắng xoá nội dung ghi đè khi ứng dụng không chạy ở chế độ gỡ lỗi có bật tuỳ chọn dành cho nhà phát triển, thì AdServiceException sẽ cho biết nguyên nhân là IllegalStateException.

Thiết lập máy chủ báo cáo

Khi sử dụng tính năng ghi đè tìm nạp từ xa, bạn vẫn cần thiết lập một máy chủ mà thiết bị hoặc trình mô phỏng của bạn có thể truy cập để phản hồi các sự kiện báo cáo. Một điểm cuối đơn giản có thể trả về 200 mã phản hồi là đủ để thử nghiệm. Kho lưu trữ GitHub bao gồm các định nghĩa dịch vụ OpenAPI có thể được triển khai cho một nền tảng mô phỏng hoặc nền tảng dịch vụ vi mô được hỗ trợ. Để biết thêm thông tin chi tiết, vui lòng tham khảo phần README của dự án.

Khi tìm các định nghĩa OpenAPI, hãy tìm tệp reporting-server.json. Tệp này chứa một điểm cuối đơn giản có thể trả về 200 mã, đại diện cho mã phản hồi HTTP. Điểm cuối này được dùng trong selectAds() và ra tín hiệu cho Protected Audience API rằng việc báo cáo lượt hiển thị đã hoàn tất thành công.

Chức năng cần kiểm thử

• Thực hiện việc tham gia hoặc rời khỏi và thiết lập đối tượng tuỳ chỉnh dựa trên các thao tác trước đó của người dùng.
• Thực hiện việc bắt đầu lựa chọn quảng cáo trên thiết bị thông qua JavaScript được lưu trữ từ xa.
• Quan sát cách ứng dụng liên kết với các chế độ cài đặt đối tượng tuỳ chỉnh có thể ảnh hưởng đến kết quả chọn quảng cáo.
• Thực hiện việc báo cáo hiển thị sau khi lựa chọn quảng cáo.

Các điểm hạn chế

Bảng sau đây liệt kê các điểm hạn chế khi xử lý Protected Audience API. Các điểm hạn chế đã trình bày có thể thay đổi dựa trên phản hồi. Để biết các tính năng đang được phát triển, hãy đọc 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 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.