Xác định dữ liệu đối tượng

Đố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.

Bạn có thể sử dụng Protected Audience API của Android để tham gia và rời khỏi đối tượng tuỳ chỉnh trên thiết bị của người dùng. Khi tạo và tham gia một đối tượng tuỳ chỉnh, bạn có thể uỷ quyền cho một máy chủ để tìm nạp một số hoặc tất cả các thuộc tính đối tượng tuỳ chỉnh, hoặc bạn có thể chỉ định thông tin này khi gọi trực tiếp API.

Đối tượng tùy chỉnh

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.

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

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.

Tìm nạp và tham gia một đối tượng tuỳ chỉnh

API fetchAndJoinCustomAudience cho phép người mua uỷ quyền tham gia một đối tượng tuỳ chỉnh bằng cách tận dụng việc đối tác đo lường trên thiết bị di động (MMP) hoặc nền tảng bên cung (SSP) của đối tác hiện diện trên thiết bị.

Để tính năng này hoạt động, phương thức gọi trên thiết bị (cho dù là SDK SSP hay MMP) sẽ tạo một fetchAndJoinCustomAudienceRequest có dạng như sau:

KotlinJava
/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

Lưu ý quan trọng về tất cả các thông số không bắt buộc: Nếu đặt những thông số này bên trong yêu cầu tìm nạp thì không thể ghi đè dữ liệu của thông số bằng dữ liệu trả về từ Người mua. Nhờ vậy, phương thức gọi trên thiết bị có thêm quyền kiểm soát đối với đối tượng tuỳ chỉnh nào được duy trì.

fetchUri phải trỏ đến một điểm cuối máy chủ do Người mua điều hành. Điểm cuối này sẽ trả về một đối tượng JSON của Đối tượng tuỳ chỉnh khớp với định dạng thấy ở đây:

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

Bạn có thể tìm thêm thông tin về cách giải quyết vấn đề này ở phía API trong phần Đề xuất thiết kế cho tính năng uỷ quyền tham gia đối tượng tuỳ chỉnh.

Kiểm thử

Sau khi triển khai lệnh gọi Tìm nạp bên trong mã ứng dụng và thiết lập một điểm cuối ở phía DSP để trả về Dữ liệu đối tượng tuỳ chỉnh, bạn có thể kiểm thử tính năng uỷ quyền tham gia Đối tượng tuỳ chỉnh. Trước khi chạy ứng dụng, bạn cần chạy các lệnh trên trang Testing setup (Thiết lập kiểm thử). Sau khi chạy những lệnh này, bạn có thể bắt đầu thực hiện thành công các lệnh gọi bằng API Tìm nạp.

Để xem ví dụ về quy trình này, chúng tôi đã thêm các lệnh gọi tìm nạp vào kho lưu trữ Mẫu hộp cát về quyền riêng tư trên GitHub.

Tham gia trực tiếp một đối tượng tuỳ chỉnh

Nếu đã có tất cả thông tin cần thiết để tạo và tham gia một đối tượng tuỳ chỉnh, bạn có thể thực hiện việc này ngay bằng cách sử dụng lệnh gọi Protected Audience API không đồng bộ. Để trực tiếp tạo hoặc tham gia một đối tượng tuỳ chỉnh, 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.
KotlinJava
val customAudienceManager: CustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java)

// Minimal initialization of a CustomAudience object
val audience: 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()

// 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);

// Minimal initialization of a CustomAudience object
CustomAudience audience = 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();

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

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

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.

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

KotlinJava
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 bài viết "Tham gia trực tiếp 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.
KotlinJava
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.