Hướng dẫn dành cho nhà phát triển về Tín hiệu ứng dụng được bảo vệ

Để giúp nhà phát triển bắt đầu thử nghiệm với Protected App Signals API, tài liệu này mô tả tất cả các API trong nền tảng API, trình bày chi tiết cách thiết lập một môi trường thử nghiệm, đồng thời đưa ra ví dụ về các cấu hình và tập lệnh.

Nhật ký phiên bản

Tháng 1 năm 2024

Bản phát hành đầu tiên của hướng dẫn dành cho nhà phát triển hỗ trợ bản phát hành MVP của PAS

Tháng 3/2024

Các thay đổi trong API để hỗ trợ bản phát hành M-2024-05 của API Android và Bản phát hành tháng 4 năm 2024 của các thành phần phía máy chủ. Những thay đổi đáng chú ý nhất:

  • Bổ sung thông tin chi tiết về những quyền cần thiết đối với API trên thiết bị
  • Thêm thông tin chi tiết về việc quản lý hạn mức tín hiệu trên thiết bị
  • Cập nhật chữ ký generateBid có các thay đổi liên quan đến ngữ cảnh hỗ trợ truy xuất và xuất quảng cáo
  • Cập nhật tài liệu về reportWin, bao gồm cả tính năng hỗ trợ đầu ra
  • Cập nhật tài liệu về API truy xuất quảng cáo để ngừng hỗ trợ việc truy xuất quảng cáo BYOS và ghi lại UDF truy xuất quảng cáo

Tổng quan về API

Nền tảng Protected Signals API bao gồm nhiều nhóm nhỏ API trên nhiều hệ thống:

  • Các API của Android:
    • Signal Curation API, bao gồm:
    • Update Signals API
    • Signals Encoding API
    • Protected Auction Support API: Được SDK dùng để chạy phiên đấu giá được bảo vệ trên Máy chủ đặt giá thầu và phiên đấu giá (B&A) bằng Protected App Signals.
  • Các API ở phía máy chủ:
    • Protected Auction API: Một loạt tập lệnh JS đang chạy trong Máy chủ đặt giá thầu và Máy chủ phiên đấu giá. API này giúp người bán và người mua viết logic để triển khai phiên đấu giá được bảo vệ.
    • Ad Retrieval API: Chịu trách nhiệm cung cấp danh sách quảng cáo đề xuất dựa trên bối cảnh và thông tin người dùng được cung cấp cho máy chủ đặt giá thầu của người mua.

Ứng dụng Android

Ở phía máy khách, giao diện Protected App Signals (Tín hiệu của ứng dụng được bảo vệ) bao gồm 3 API khác nhau:

  • Update Signals: Một API của Hệ thống Android giúp tuyển chọn các tín hiệu trên thiết bị.
  • Signals Encoding: Một API của JavaScript giúp chuẩn bị các tín hiệu cần gửi đến máy chủ trong phiên đấu giá.
  • Protected Auction Support: Một API hỗ trợ việc thực thi Phiên đấu giá được bảo vệ trên các Máy chủ đặt giá thầu và Máy chủ phiên đấu giá. API này không dành riêng cho Protected App Signals và cũng dùng để hỗ trợ các phiên đấu giá cho Protected Audience API.

Update Signals API

Update Signals API cung cấp cho các công nghệ quảng cáo khả năng thay mặt người mua đăng ký các tín hiệu liên quan đến người dùng và ứng dụng. API hoạt động theo một mô hình uỷ quyền. Phương thức gọi cung cấp một URI mà từ đó khung sẽ tìm nạp các logic và tín hiệu tương ứng để mã hoá những tín hiệu được dùng trong phiên đấu giá.

API yêu cầu android.permission.ACCESS_ADSERVICES_PROTECTED_SIGNALS quyền.

API updateSignals() sẽ truy xuất đối tượng JSON từ URI mô tả tín hiệu cần thêm hoặc xoá và cách chuẩn bị những tín hiệu đó cho phiên đấu giá.

Executor executor = Executors.newCachedThreadPool();
ProtectedSignalsManager protectedSignalsManager
     =  ProtectedSignalsManager.get(context);

// Initialize a UpdateSignalsRequest
UpdateSignalsRequest updateSignalsRequest = new
  UpdateSignalsRequest.Builder(Uri.parse("https://example-adtech1.com/signals"))
      .build();

OutcomeReceiver<Object, Exception> outcomeReceiver = new OutcomeReceiver<Object, Exception>() {
  @Override
  public void onResult(Object o) {
    //Post-success actions
  }

  @Override
  public void onError(Exception error) {
    //Post-failure actions
  };

// Call updateSignals
protectedSignalsManager.updateSignals(updateSignalsRequest,
    executor,
    outcomeReceiver);

Nền tảng này gửi một yêu cầu https đến URI được cung cấp trong yêu cầu để tìm nạp thông tin cập nhật tín hiệu. Cùng với thông tin cập nhật tín hiệu, phản hồi có thể bao gồm một điểm cuối lưu trữ logic mã hoá để chuyển đổi các tín hiệu thô thành tải trọng được mã hoá. thông tin cập nhật tín hiệu dự kiến sẽ ở dạng JSON và có thể có các khoá sau:

Các khoá cấp cao nhất cho đối tượng JSON phải tương ứng với một trong 5 lệnh:

key

Mô tả

put

Thêm tín hiệu mới, ghi đè mọi tín hiệu hiện có bằng cùng một khoá. Giá trị

cho tín hiệu này là đối tượng JSON trong đó các khoá là chuỗi cơ sở 64 tương ứng với khoá cần đặt và các giá trị là chuỗi cơ sở 64 tương ứng với giá trị cần đặt.

append

Thêm một tín hiệu/các tín hiệu mới vào một chuỗi tín hiệu thời gian, xoá tín hiệu cũ nhất

để tạo chỗ trống cho các tín hiệu mới nếu kích cỡ của chuỗi vượt quá mức tối đa đã cho. Giá trị cho tín hiệu này là đối tượng JSON, trong đó khoá là chuỗi cơ sở 64 tương ứng với khoá cần nối và giá trị là các đối tượng có 2 trường: "values" và "maxSignals".

"values": Danh sách gồm các chuỗi cơ sở 64 tương ứng với các giá trị tín hiệu cần thêm vào chuỗi thời gian.

"maxSignals": Số lượng giá trị tối đa được phép trong chuỗi thời gian này. Nếu

số lượng tín hiệu hiện tại được liên kết với khoá vượt quá maxSignals, thì các tín hiệu cũ nhất sẽ bị xoá. Xin lưu ý rằng bạn có thể nối vào khoá được thêm bằng cách đặt. Lưu ý rằng việc nối nhiều hơn số lượng giá trị tối đa sẽ gây ra lỗi.

put_if_not_present

Chỉ thêm một tín hiệu mới khi không có tín hiệu nào có cùng khoá. Giá trị cho tín hiệu này là một đối tượng JSON, trong đó các khoá là các chuỗi cơ sở 64 tương ứng với khoá cần đặt và các giá trị là chuỗi cơ sở 64 tương ứng với giá trị cần đặt.

remove

Xoá tín hiệu của một khoá. Giá trị của tín hiệu này là danh sách gồm các chuỗi cơ sở 64 tương ứng với các khoá của tín hiệu cần xoá.

update_encoder

Cung cấp một thao tác để cập nhật điểm cuối và URI có thể dùng

để truy xuất một logic mã hoá. Khoá phụ để cung cấp hành động cập nhật là "action" và

các giá trị hiện được hỗ trợ chỉ là "REGISTER". Tính năng này sẽ đăng ký điểm cuối bộ mã hoá nếu được cung cấp lần đầu tiên hoặc ghi đè điểm cuối hiện có bằng điểm cuối mới được cung cấp. Bạn cần cung cấp điểm cuối thì mới thực hiện được thao tác "REGISTER". Khoá phụ để cung cấp điểm cuối của bộ mã hoá là "endpoint" và giá trị là chuỗi URI

cho điểm cuối.

Yêu cầu JSON mẫu sẽ có dạng như sau:

{
    "put": {
        "AAAAAQ==": "AAAAZQ==",
        "AAAAAg==": "AAAAZg=="
    },
    "append": {
        "AAAAAw==": {
            "values": [
                "AAAAZw=="
            ],
            "max_signals": 3
        }
    },
    "put_if_not_present": {
        "AAAABA==": "AAAAaQ==",
        "AAAABQ==": "AAAAag=="
    },
    "update_encoder": {
        "action": "REGISTER",
        "endpoint": "https://adtech1.com/Protected App Signals_encode_script.js"
    }
}

Các tín hiệu sẽ có một hạn mức trên thiết bị theo thứ tự từ 10 đến 15 Kb. Sau khi hạn mức bị vượt quá. PPAPI sẽ loại bỏ tín hiệu bằng cách sử dụng chiến lược FIFO. Quy trình loại trừ sẽ cho phép vượt quá hạn mức một chút trong khoảng thời gian ngắn trong để giảm tần suất bị trục xuất.

Signals Encoding API

Người mua bắt buộc phải cung cấp hàm Java Script dùng để mã hoá các tín hiệu được lưu trữ trên thiết bị mà sẽ được gửi đến máy chủ trong Phiên đấu giá được bảo vệ. Người mua có thể cung cấp tập lệnh này bằng cách thêm URL mà ở đó có thể tìm nạp tập lệnh bằng khoá "update_encoder" trong mọi phản hồi cho yêu cầu UpdateSignal API. Tập lệnh sẽ có chữ ký sau:

function encodeSignals(signals, maxSize) {
  let result = new Uint8Array(maxSize);
  // first entry will contain the total size
  let size = 1;
  let keys = 0;
  
  for (const [key, values] of signals.entries()) {
    keys++;
    // In this encoding we only care about the first byte
    console.log("key " + keys + " is " + key)
    result[size++] = key[0];
    result[size++] = values.length;
    for(const value of values) {
      result[size++] = value.signal_value[0];
    }
  }
  result[0] = keys;
  
  return { 'status': 0, 'results': result.subarray(0, size)};
}

Tham số signals là một bản đồ từ các khoá ở dạng UInt8Arrays có kích thước 4 đến danh sách đối tượng Protected App Signals. Mỗi đối tượng Protected App Signals có 3 trường:

  • signal_value: Một UInt8Array biểu thị giá trị của tín hiệu.
  • creation_time: Một số biểu thị thời gian tạo tín hiệu theo thời gian bắt đầu của hệ thống (giây)
  • package_name: Một chuỗi biểu thị tên của gói đã tạo tín hiệu.

Tham số maxSize là một số mô tả kích thước mảng lớn nhất được phép cho đầu ra.

Hàm sẽ xuất một đối tượng có 2 trường:

  • status: Phải là 0 nếu tập lệnh chạy thành công.
  • results: Phải là UInt8Array có độ dài nhỏ hơn hoặc bằng maxSize. Mảng này sẽ được gửi đến máy chủ trong các phiên đấu giá và được tập lệnh prepareDataForAdRetrieval chuẩn bị.

Việc mã hoá cung cấp cho các công nghệ quảng cáo giai đoạn ban đầu của kỹ thuật trích xuất tính chất, trong đó chúng có thể thực hiện các biến đổi như nén tín hiệu thô thành các phiên bản được nối dựa trên logic tuỳ chỉnh riêng. Lưu ý rằng trong Phiên đấu giá được bảo vệ chạy trong Môi trường thực thi đáng tin cậy (TEE), logic tuỳ chỉnh của công nghệ quảng cáo sẽ có quyền đọc các tải trọng tín hiệu do phương thức mã hoá tạo ra. Logic tuỳ chỉnh, còn gọi là Hàm do người dùng xác định (UDF), chạy trong TEE B&A của Người mua sẽ có quyền đọc các tín hiệu được mã hoá và các tín hiệu theo bối cảnh khác do ứng dụng của nhà xuất bản cung cấp để thực hiện việc lựa chọn quảng cáo (truy xuất và đặt giá thầu quảng cáo).

Mã hoá tín hiệu

Mỗi giờ, những người mua đã cung cấp logic mã hoá với các tín hiệu đã đăng ký sẽ được mã hoá các tín hiệu đó thành một tải trọng phiên đấu giá. Mảng byte cho tải trọng phiên đấu giá sẽ được duy trì trên thiết bị, sau đó được mã hoá và sẽ được người bán thu thập như một phần của dữ liệu Lựa chọn quảng cáo để đưa vào như một phần của một Phiên đấu giá được bảo vệ. Để thử nghiệm, bạn có thể kích hoạt phương thức mã hoá này ngoài quy trình theo giờ bằng cách chạy lệnh sau:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 29
Tạo phiên bản logic bộ mã hoá

Khi có yêu cầu tải logic bộ mã hoá tuỳ chỉnh cho công nghệ quảng cáo xuống, điểm cuối của công nghệ quảng cáo có thể phản hồi bằng số phiên bản trong các tiêu đề phản hồi. Phiên bản này vẫn tồn tại cùng với logic bộ mã hoá trên thiết bị. Khi các tín hiệu thô được mã hoá, tải trọng đã mã hoá sẽ được duy trì cùng với phiên bản được dùng để mã hoá. Phiên bản này cũng được gửi đến máy chủ B&A trong một Phiên đấu giá được bảo vệ để các công nghệ quảng cáo có thể điều chỉnh logic đặt giá thầu và mã hoá dựa trên phiên bản.

Response header for providing encoder version : X_ENCODER_VERSION

Protected Auction Support API

Về phía thiết bị, việc chạy phiên đấu giá cho Protected App Signals cũng tương tự như việc chạy phiên đấu giá cho các đối tượng được bảo vệ.

Dịch vụ Đặt giá thầu và phiên đấu giá

API phía máy chủ bao gồm:

  • Protected Auction API: Một loạt hàm JS hoặc UDF mà người mua và người bán có thể triển khai trên các thành phần B&A mà họ sở hữu để xác định logic đặt giá thầu và đấu giá.
  • Protected Auction API: Người mua có thể triển khai API này bằng cách triển khai Điểm cuối REST sẽ chịu trách nhiệm cung cấp tập hợp các quảng cáo đề xuất cho phiên đấu giá Protected App Signal.

Protected Auction API

Protected Auction API bao gồm API JS hoặc UDF mà người mua và người bán có thể dùng để triển khai logic đấu giá và đặt giá thầu.

UDF công nghệ quảng cáo của người mua
UDF prepareDataForAdRetrieval

Trước khi có thể sử dụng Protected App Signals để tìm nạp các đề xuất quảng cáo từ TEE Dịch vụ truy xuất quảng cáo, người mua phải giải mã và chuẩn bị Protected App Signals và dữ liệu khác do người bán cung cấp. Đầu ra UDF của prepareDataForAdRetrieval của người mua được chuyển đến dịch vụ truy xuất quảng cáo để truy xuất k quảng cáo đề xuất hàng đầu để đặt giá thầu.

// Inputs
// ------
// encodedOnDeviceSignals: A Uint8Array of bytes from the device.
// encodedOnDeviceSignalsVersion: An integer representing the encoded
//   version of the signals.
// sellerAuctionSignals: Information about auction (ad format, size) derived
//                       contextually.
// contextualSignals: Additional contextual signals that could help in
//                    generating bids.
//
// Outputs
// -------
// Returns a JSON structure to be used for retrieval.
// The structure of this object is left to the adtech.
function prepareDataForAdRetrieval(encodedOnDeviceSignals,encodedOnDeviceSignalsVersion,sellerAuctionSignals,contextualSignals) {
   return {};
}
UDF generateBid

Sau khi hệ thống trả về k quảng cáo đề xuất hàng đầu, các đề xuất quảng cáo đó sẽ được chuyển đến logic đặt giá thầu tuỳ chỉnh của người mua, generateBid UDF:

// Inputs
// ------
// ads: Data string returned by the ads retrieval service. This can include Protected App Signals
//   ads and related ads metadata.
// sellerAuctionSignals: Information about the auction (ad format, size),
//                       derived contextually
// buyerSignals: Any additional contextual information provided by the buyer
// preprocessedDataForRetrieval: This is the output of this UDF.
function generateBid(ads, sellerAuctionSignals, buyerSignals,
                    preprocessedDataForRetrieval,
                    rawSignals, rawSignalsVersion) {
    return { "ad": <ad Value Object>,
             "bid": <float>,
             "render": <render URL string>,
             'adCost': <optional float ad cost>,
             "egressPayload": <limitedEgressPayload>,
             "temporaryUnlimitedEgressPayload": <temporaryUnlimitedEgressPayload>
    };
}

Kết quả của hàm này là một giá thầu duy nhất cho một đề xuất quảng cáo, được đại diện dưới dạng JSON tương đương với ProtectedAppSignalsAdWithBidMetadata. Hàm này cũng có thể trả về 2 mảng mà sau đó sẽ được truyền đến reportWin để cho phép huấn luyện mô hình (để biết thêm thông tin chi tiết về lượng dữ liệu đầu ra và huấn luyện mô hình hãy tham khảo phần báo cáo trong tài liệu giải thích PAS)

UDF reportWin

Khi phiên đấu giá kết thúc, dịch vụ đấu giá sẽ tạo URL báo cáo cho người mua và đăng ký beacon bằng UDF reportWin (Điều này tương tự Hàm reportWin dùng cho Đối tượng được bảo vệ). Thiết bị sẽ ping hàm này sau khi Quảng cáo đã được ứng dụng hiển thị. Chữ ký của phương thức này gần giống với Protected Audience version ngoại trừ hai thông số bổ sung egressPayload và temporaryUnlimitedEgressPayload dùng để cho phép huấn luyện mô hình và điền sẵn kết quả từ generateBid.

// Inputs / Outputs
// ----------------
// See detailed documentation here.
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
                   buyerReportingSignals,
                   egressPayload, temporaryUnlimitedEgressPayload) {
  // ...
}
UDF công nghệ quảng cáo của người bán
UDF scoreAd

UDF này được người bán dùng để chọn những quảng cáo nhận được từ người mua sẽ giành chiến thắng trong phiên đấu giá.

function scoreAd(adMetadata, bid, auctionConfig,
                 trustedScoringSignals, bid_metadata) {
  // ...
  return {desirability: desirabilityScoreForThisAd,
              allowComponentAuction: true_or_false};
}
UDF reportResult

UDF này cho phép người bán (cuối cùng) thực hiện báo cáo ở cấp sự kiện với thông tin liên quan đến quảng cáo giành chiến thắng.

function reportResult(auctionConfig, reporting_metadata) {
  // ...
  registerAdBeacon({"click", clickUrl,"view", viewUrl});
  sendReportTo(reportResultUrl);
  return signalsForWinner;
}

Ad Retrieval API

Trong bản phát hành MVP , dịch vụ truy xuất quảng cáo sẽ do người mua quản lý và lưu trữ và dịch vụ đặt giá thầu sẽ truy xuất các đề xuất quảng cáo từ dịch vụ này. Kể từ tháng 4 năm 2024, máy chủ truy xuất quảng cáo phải chạy trong một Phiên bản đáng tin cậy Môi trường thực thi (TEE) và sẽ hiển thị giao diện GRPC/proto. Các công ty công nghệ quảng cáo phải thiết lập máy chủ này và cung cấp URL của máy chủ đó trong quá trình triển khai ngăn xếp B&A. Hoạt động triển khai dịch vụ này chạy trong TEE có trong Hộp cát về quyền riêng tư trên GitHub và trong phần còn lại của chúng tôi giả định rằng đây là mã được sử dụng trong quá trình triển khai.

Kể từ tháng 4 năm 2024, các phiên bản B&A sẽ hỗ trợ quảng cáo đường dẫn theo bối cảnh truy xuất. Trong trường hợp này, máy chủ Đặt giá thầu sẽ nhận được danh sách giá trị nhận dạng quảng cáo do máy chủ RTB gửi trong phần theo ngữ cảnh của phiên đấu giá. Giá trị nhận dạng sẽ được gửi đến máy chủ KV TEE để tìm nạp tất cả quảng cáo thông tin liên quan được dùng trong giai đoạn đặt giá thầu (ví dụ: ad-render-url, siêu dữ liệu và các mục nhúng quảng cáo sẽ được sử dụng trong lựa chọn hàng đầu). Đường dẫn thứ hai này không cần bất kỳ logic cụ thể nào nên chúng tôi sẽ chỉ ghi lại ở đây cách định cấu hình TEE trường hợp sử dụng truy xuất quảng cáo.

UDF Xử lý yêu cầu
function HandleRequest(requestMetadata, preparedDataForAdRetrieval,
                      deviceMetadata, contextualSignals) {
    return adsMetadataString;
}

Trong trường hợp:

  • requestMetadata: JSON. Siêu dữ liệu máy chủ theo từng yêu cầu đến UDF. Hiện đang trống.
  • preparedDataForAdRetrieval: nội dung của trường này phụ thuộc vào quảng cáo truy xuất. Trong trường hợp truy xuất quảng cáo theo ngữ cảnh , thông số này sẽ chứa các tín hiệu thô bắt nguồn từ thiết bị và được chuyển từ đặt giá thầu. Trong trường hợp truy xuất quảng cáo TEE bằng Máy chủ truy xuất quảng cáo, tham số này sẽ chứa kết quả của UDF prepareDataForAdRetrieval. Lưu ý: ở giai đoạn này, Protected App Signals sẽ được giải mã và không mã hoá.
  • deviceMetadata: Đối tượng JSON chứa siêu dữ liệu thiết bị do Dịch vụ quảng cáo của Người bán chuyển tiếp. Xem tài liệu về B&A để biết thêm chi tiết.
    • X-Accept-Language: ngôn ngữ được sử dụng trên thiết bị.
    • X-User-Agent: Tác nhân người dùng được sử dụng trên thiết bị.
    • X-BnA-Client-IP: Địa chỉ IP của thiết bị.
  • contextualSignals: chuỗi tuỳ ý bắt nguồn từ tính năng đặt giá thầu theo bối cảnh máy chủ do cùng một DSP vận hành. UDF dự kiến có thể giải mã chuỗi và sử dụng chuỗi đó. Tín hiệu theo bối cảnh có thể chứa bất kỳ thông tin nào như học máy thông tin phiên bản mô hình cho nhúng được bảo vệ được truyền vào bằng Protected App Signals.

UDF sẽ trả về một chuỗi khi thành công. Chuỗi này được trả về máy chủ đặt giá thầu này, sau đó truyền đến UDF generateBid. Mặc dù chuỗi này có thể chỉ là một chuỗi đơn giản, rất có thể chuỗi này sẽ là một chuỗi đối tượng được chuyển đổi tuần tự có giản đồ do từng công nghệ quảng cáo xác định. Không có quy tắc ràng buộc nào đối với giản đồ này, miễn là generateBid của công nghệ quảng cáo logic có thể nhận ra và sử dụng chuỗi.

Thiết lập hệ thống của bạn cho hoạt động phát triển

Android

Để thiết lập môi trường phát triển Android, bạn cần làm như sau:

  1. Tạo một trình mô phỏng (thường dùng) hoặc thiết bị thực đang chạy hình ảnh Bản dùng thử 10 cho nhà phát triển
  2. Chạy lệnh sau:
adb shell am start -n com.google.android.adservices.api/com.android.adservices.ui.settings.activities.AdServicesSettingsMainActivity

Sau đó, hãy chọn mục cho thấy bạn đồng ý với quảng cáo do ứng dụng gợi ý.

  1. Chạy lệnh sau để bật các API có liên quan. Thỉnh thoảng, bạn có thể cần chạy lại ứng dụng này vì cấu hình mặc định của trạng thái tắt sẽ được đồng bộ hoá định kỳ.
adb shell device_config put adservices fledge_custom_audience_service_kill_switch false;  adb shell device_config put adservices fledge_select_ads_kill_switch false; adb shell device_config put adservices fledge_on_device_auction_kill_switch false; adb shell device_config put adservices fledge_auction_server_kill_switch false; adb shell "device_config put adservices disable_fledge_enrollment_check true";  adb shell device_config put adservices ppapi_app_allow_list '\*'; adb shell device_config put adservices fledge_auction_server_overall_timeout_ms 60000;
  1. Khởi động lại thiết bị.
  2. Ghi đè khoá đấu giá của thiết bị để trỏ đến máy chủ khoá phiên đấu giá. Bạn phải thực hiện bước này trước khi tìm cách chạy một phiên đấu giá để tránh việc các khoá không chính xác được lưu vào bộ nhớ đệm.

Dịch vụ đặt giá thầu và đấu giá

Để thiết lập máy chủ B&A, hãy tham khảo tài liệu về cách thiết lập tự phục vụ.

Tài liệu này sẽ tập trung vào cách định cấu hình các máy chủ cụ thể của người mua, vì người bán không cần phải thay đổi gì.

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

Trước khi triển khai ngăn xếp dịch vụ B&A, công nghệ quảng cáo của người mua cần:

  • Đảm bảo rằng họ đã triển khai Dịch vụ truy xuất quảng cáo TEE của riêng mình (xem mục có liên quan).
  • Đảm bảo rằng công nghệ quảng cáo có tất cả UDF cần thiết (prepareDataForAdRetrieval, generateBid, reportWin, HandleRequest) xác định và lưu trữ.

Việc hiểu rõ cách phiên đấu giá được bảo vệ với Protected Audience hoạt động với B&A cũng sẽ hữu ích nhưng không bắt buộc.

Cấu hình Terraform

Để sử dụng Protected App Signals, công nghệ quảng cáo phải:

  • Bật tính năng hỗ trợ Protected App Signals trong B&A.
  • Cung cấp các điểm cuối URL mà từ đó các UDF mới cho prepareDataForAdRetrieval, generateBid và reportWin có thể được tìm nạp.

Ngoài ra, hướng dẫn này giả định rằng các công nghệ quảng cáo muốn sử dụng B&A để tái tiếp thị sẽ tiếp tục đặt tất cả cờ cấu hình hiện có cho phiên đấu giá tái tiếp thị như bình thường.

Cấu hình công nghệ quảng cáo của người mua

Lấy tệp minh hoạ này làm ví dụ, người mua cần đặt các cờ sau:

  • Bật Protected App Signals: Bật để thu thập dữ liệu Protected App Signals.
  • URL Protected App Signals: Đặt thành URL của máy chủ Protected App Signals.

Công nghệ quảng cáo phải thay thế URL chính xác trong phần giữ chỗ cho các trường sau:

module "buyer" {
  # ... More config here.

  runtime_flags = {
    # ... More config here.

    ENABLE_PROTECTED_APP_SIGNALS                  = "true"
    PROTECTED_APP_SIGNALS_GENERATE_BID_TIMEOUT_MS = "60000"
    TEE_AD_RETRIEVAL_KV_SERVER_ADDR               = "<service mesh address of the instance>"
    AD_RETRIEVAL_TIMEOUT_MS                       = "60000"
    BUYER_CODE_FETCH_CONFIG                       = <<EOF
    {
        "protectedAppSignalsBiddingJsUrl": "<URL to Protected App Signals generateBid UDF>",
        "urlFetchTimeoutMs": 60001, # This has to be > 1 minute.
        "urlFetchPeriodMs": 13000000,
        "prepareDataForAdsRetrievalJsUrl": "<URL to the UDF>"
    }
    EOF

  }  # runtime_flags

}  # Module "buyer"

Cấu hình công nghệ quảng cáo của người bán

Lấy tệp minh hoạ này làm ví dụ, người bán phải đặt các cờ sau. (Lưu ý: chỉ cấu hình liên quan đến Protected App Signals mới được làm nổi bật tại đây). Công nghệ quảng cáo cần đảm bảo việc thay thế các URL chính xác trong phần giữ chỗ:

module "seller" {
  # ... More config here.

  runtime_flags = {
    # ... More config here.

    ENABLE_PROTECTED_APP_SIGNALS                  = "true"

    SELLER_CODE_FETCH_CONFIG                           = <<EOF
  {
    "urlFetchTimeoutMs": 60001, # This has to be > 1 minute.
    "urlFetchPeriodMs": 13000000,
    "protectedAppSignalsBuyerReportWinJsUrls": {"<Buyer Domain>": "URL to reportWin UDF"}
  }
  EOF

  }  # runtime_flags

}  # Module "seller"

Dịch vụ truy xuất quảng cáo và KV

Tuỳ thuộc vào chiến lược đã chọn để hỗ trợ truy xuất quảng cáo, hệ thống sẽ yêu cầu triển khai một hoặc hai phiên bản của dịch vụ KV. Chúng tôi sẽ đề xuất cho phiên bản KV được dùng cho việc truy xuất quảng cáo dựa trên TEE làm phiên bản Ad Retrieval Server và đến thực thể hỗ trợ đường dẫn theo bối cảnh truy xuất dưới dạng KV Lookup Server.

Trong cả hai trường hợp, việc triển khai máy chủ đều tuân theo tài liệu có trong Máy chủ KV GitHub, sự khác biệt giữa 2 trường hợp này là hoạt động tra cứu trường hợp hoạt động tốt mà không cần bất kỳ cấu hình bổ sung nào trong khi phương thức truy xuất yêu cầu triển khai UDF HandleRequest để triển khai. logic truy xuất. Để biết thêm thông tin, hãy xem máy chủ KV hướng dẫn cho người mới tham gia. Xin lưu ý rằng B&A mong muốn cả hai dịch vụ được triển khai trên cùng một lưới dịch vụ như dịch vụ đặt giá thầu.

Thiết lập mẫu

Hãy xem xét trường hợp sau: bằng cách sử dụng Protected App Signals API, một công nghệ quảng cáo lưu trữ các tín hiệu liên quan dựa trên mức sử dụng ứng dụng của người dùng. Trong ví dụ này, các tín hiệu được lưu trữ để thể hiện giao dịch mua hàng trong ứng dụng trong một số ứng dụng. Trong một phiên đấu giá, các tín hiệu đã mã hoá được thu thập và chuyển vào một Phiên đấu giá được bảo vệ đang chạy trong B&A. UDF của người mua đang chạy trong B&A sử dụng các tín hiệu để tìm nạp các đề xuất quảng cáo và tính toán giá thầu.

[Người mua] Ví dụ về tín hiệu

Thêm một tín hiệu có khoá là 0 và giá trị là 1.

{
  "put": {
    "AA==": "AQ=="
  },
  "update_encoder": {
    "action": "REGISTER",
    "endpoint": "https://example.com/example_script"
  }
}

Thêm một tín hiệu với khoá là 1 và giá trị là 2.

{
  "put": {
    "AQ==": "Ag=="
  },
  "update_encoder": {
    "action": "REGISTER",
    "endpoint": "https://example.com/example_script"
  }
}

[Người mua] Ví dụ về encodeSignals

Mã hoá mỗi tín hiệu thành 2 byte, với byte đầu tiên là byte đầu tiên của khoá tín hiệu và byte thứ hai là byte đầu tiên của giá trị tín hiệu.

function encodeSignals(signals, maxSize) {
  // if there are no signals don't write a payload
  if (signals.size === 0) {
      return {};
  }

  let result = new Uint8Array(signals.size * 2);
  let index = 0;
  
  for (const [key, values] of signals.entries()) {
    result[index++] = key[0];
    result[index++] = values[0].signal_value[0];
  }
  
  return { 'status': 0, 'results': result};
}

[Người mua] Ví dụ về prepareDataForAdRetrieval

/**
 * `encodedOnDeviceSignals` is a Uint8Array and would contain
 * the app signals emanating from device. For purpose of the
 * demo, in our sample example, we assume that device is sending
 * the signals with pair of bytes formatted as following:
 * "<id><In app spending>". Where id corresponds to an ad category
 * that user uses on device, and the in app spending is a measure
 * of how much money the user has spent in this app category
 * previously. In our example, id of 0 will correspond to a
 * fitness ad category and a non-zero id will correspond to
 * food app category -- though this info will be useful
 * later in the B&A pipeline.
 *
 * Returns a JSON object indicating what type of ad(s) may be
 * most relevant to the user. In a real setup ad techs might
 * want to decode the signals as part of this script.
 *
 * Note: This example script makes use of only encoded device signals
 * but adtech can take other signals into account as well to prepare
 * the data that will be useful down stream for ad retrieval and
 * bid generation. The max length of the app signals used in this
 * sample example is arbitrarily limited to 4 bytes.
 */
function prepareDataForAdRetrieval(encodedOnDeviceSignals,
                                   encodedOnDeviceSignalsVersion,
                                   sellerAuctionSignals,
                                   contextualSignals) {
  if (encodedOnDeviceSignals.length === 0 || encodedOnDeviceSignals.length > 4 ||
      encodedOnDeviceSignals.length % 2 !== 0) {
     throw "Expected encoded signals length to be an even number in (0, 4]";
  }

  var preparedDataForAdRetrieval = {};
  for (var i = 0; i < encodedOnDeviceSignals.length; i += 2) {
    preparedDataForAdRetrieval[encodedOnDeviceSignals[i]] = encodedOnDeviceSignals[i + 1];
  }
  return preparedDataForAdRetrieval;
}

[Người mua] UDF truy xuất quảng cáo mẫu

Trong ví dụ này, máy chủ truy xuất quảng cáo gửi siêu dữ liệu (tức là mã nhận dạng cho mỗi quảng cáo trong ví dụ này nhưng có thể chứa dữ liệu khác cho từng quảng cáo có thể hữu ích trong việc tạo giá thầu sau này) cho từng quảng cáo trong số k đề xuất quảng cáo hàng đầu.

function HandleRequest(requestMetadata, protectedSignals, deviceMetadata,
                      contextualSignals) {
 return "[{\"adId\":\"0\"},{\"adId\":\"1\"}]"

[Người mua] Ví dụ về generateBid

/**
 * This script receives the data returned by the ad retrieval service
 * in the `ads` argument. This argument is supposed to contain all
 * the Protected App Signals related ads and the metadata obtained from the retrieval
 * service.
 *
 * `preparedDataForAdRetrieval` argument contains the data returned
 * from the `prepareDataForAdRetrieval` UDF.
 *
 * This script is responsible for generating bids for the ads
 * collected from the retrieval service and ad techs can decide to
 * run a small inference model as part of this script in order to
 * decide the best bid given all the signals available to them.
 *
 * For the purpose of the demo, this sample script assumes
 * that ad retrieval service has sent us most relevant ads for the
 * user and this scripts decides on the ad render URL as well as
 * what value to bid for each ad based on the previously decoded
 * device signals. For simplicity sake, this script only considers
 * 2 types of app categories i.e. fitness and food.
 *
 * Note: Only one bid is returned among all the
 * input ad candidates.
 */
function generateBid(ads, sellerAuctionSignals, buyerSignals, preparedDataForAdRetrieval) {
  if (ads === null) {
    console.log("No ads obtained from the ad retrieval service")
    return {};
  }     
        
  const kFitnessAd = "0";
  const kFoodAd = "1";
  const kBuyerDomain = "https://buyer-domain.com";
        
  let resultingBid = 0;
  let resultingRender = kBuyerDomain + "/no-ad";
  for (let i = 0 ; i < ads.length; ++i) {
    let render = "";
    let bid = 0;
    switch (ads[i].adId) {
      case kFitnessAd:
        render = kBuyerDomain + "/get-fitness-app";
        bid = preparedDataForAdRetrieval[kFitnessAd];
        break;
      case kFoodAd:
        render = kBuyerDomain + "/get-fastfood-app";
        bid = preparedDataForAdRetrieval[kFoodAd];
        break;
      default:
        console.log("Unknown ad category");
        render = kBuyerDomain + "/no-ad";
        break;
    }
    console.log("Existing bid: " + resultingBid + ", incoming candidate bid: " + bid);
    if (bid > resultingBid) {
      resultingBid = bid;
      resultingRender = render;
    }
  }
  return {"render": resultingRender, "bid": resultingBid};
}

[Người mua] Ví dụ về reportWin

UDF của reportWin báo cáo cho người mua rằng họ đã thắng phiên đấu giá.

function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
                                       buyerReportingSignals, directFromSellerSignals,
                                       egressPayload,
                                       temporaryUnlimitedEgressPayload) {
  sendReportTo("https://buyer-controlled-domain.com/");
  registerAdBeacon({"clickEvent":"https://buyer-controlled-domain.com/clickEvent"});
  return;
}

[Người bán] Thiết lập máy chủ KV

Người bán phải thiết lập máy chủ KV tín hiệu tính điểm để có sẵn mối liên kết từ URL hiển thị quảng cáo đến các tín hiệu tính điểm tương ứng, ví dụ: nếu https:/buyer-domain.com/get-fitness-app và https:/buyer-domain.com/get-fastfood-app được người mua trả về, người bán có thể có phản hồi tín hiệu tính điểm mẫu sau đây khi được SFE truy vấn bằng GET trên https://key-value-server-endpoint.com?client_type=1&renderUrls=<render-url-returned-by-the-buyer>:

{
   "renderUrls" : {
      "https:/buyer-domain.com/get-fitness-app" : [
         "1",
         "2"
      ],
      "https:/buyer-domain.com/get-fastfood-app" : [
         "3",
         "4"
      ]
   }
}

[Người bán] Ví dụ về scoreAd

/**
 * This module generates a random desirability score for the Protected App
 * Signals ad in this example. In a production deployment,
 * however, the sellers would want to use all the available signals to generate
 * a score for the ad.
 */
function getRandomInt(max) {
  return Math.floor(Math.random() * max);
}

function scoreAd(adMetadata, bid, auctionConfig,
                                   trustedScoringSignals, deviceSignals,
                                   directFromSellerSignals) {
  return {
    "desirability": getRandomInt(10000),
    "allowComponentAuction": false
  };
}

[Người bán] Ví dụ về reportResult

function reportResult(auctionConfig, sellerReportingSignals, directFromSellerSignals){
  let signalsForWinner = {};
    sendReportTo("https://seller-controlled-domain.com");
    registerAdBeacon({"clickEvent":
                    "https://seller-controlled-domain.com/clickEvent"});
    return signalsForWinner;
}

Ứng dụng mẫu

Ví dụ về cách dùng API này để tạo một ứng dụng sử dụng một quy trình đơn giản như mô tả ở trên, chúng tôi đã tạo một ứng dụng mẫu về Protected App Signals có trong kho lưu trữ mẫu này.