Để 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 PAS MVP
Tháng 3/2024
Các thay đổi trong API để hỗ trợ bản phát hành API Android M-2024-05 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:
- Thêm thông tin chi tiết về các 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để bổ sung các thay đổi liên quan đến khả năng hỗ trợ truy xuất quảng cáo và xuất quảng cáo theo bối cảnh - Cập nhật tài liệu
reportWin, bao gồm cả tính năng hỗ trợ lượng dữ liệu đầu ra - Cập nhật tài liệu về API truy xuất quảng cáo, xoá chế độ hỗ trợ 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:
- 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 này yêu cầu quyền android.permission.ACCESS_ADSERVICES_PROTECTED_SIGNALS.
API updateSignals() sẽ truy xuất đối tượng JSON qua URI mô tả các 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ả |
|
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. |
|
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. |
|
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. |
|
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á. |
|
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"
}
}
Tín hiệu sẽ có hạn mức trên thiết bị từ 10 đến 15 Kb. Sau khi vượt quá hạn mức, PPAPI sẽ loại bỏ các tín hiệu bằng chiến lược FIFO. Quy trình loại bỏ sẽ cho phép vượt quá hạn mức một chút trong khoảng thời gian ngắn để giảm tần suất loại bỏ.
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ệnhprepareDataForAdRetrievalchuẩ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 Tín hiệu ứng dụng được bảo vệ để tìm nạp quảng cáo đề xuất từ dịch vụ Truy xuất quảng cáo TEE, người mua phải giải mã và chuẩn bị Tín hiệu của ứng dụng được bảo vệ cũng như 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 biểu thị dưới dạng JSON tương đương với ProtectedAppSignalsAdWithBidMetadata.
Hàm này cũng có thể trả về 2 mảng. Sau đó, hàm này sẽ được chuyển đến reportWin để bật tính năng huấn luyện mô hình (để biết thêm thông tin chi tiết về hoạt động huấn luyện mô hình và đầu ra, hãy tham khảo phần báo cáo trong phần giải thích của 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 reportWin UDF (Đây cũng là hàm reportWin dùng cho Protected Audience).
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 phiên bản Protected Audience, ngoại trừ 2 tham số bổ sung egressPayload và temporaryUnlimitedEgressPayload dùng để bật quy trình huấn luyện mô hình và được đ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ẽ là một dịch vụ do người mua quản lý và lưu trữ, đồng thời 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ôi trường thực thi đáng tin cậy (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. Cách triển khai dịch vụ này chạy trong TEE có trên GitHub Hộp cát về quyền riêng tư và trong phần còn lại của tài liệu, chúng ta giả định rằng đây là mã được 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 hỗ trợ tính năng truy xuất quảng cáo đường dẫn theo bối cảnh. 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 bối cảnh của phiên đấu giá. Giá trị nhận dạng sẽ được gửi đến máy chủ TEE KV để tìm nạp tất cả thông tin liên quan đến quảng cáo sẽ dùng trong giai đoạn đặt giá thầu (ví dụ: url hiển thị quảng cáo, siêu dữ liệu và các lần nhúng quảng cáo sẽ được sử dụng trong lựa chọn ở trên cùng). Đường dẫn thứ hai này không cần triển khai logic cụ thể nào, vì vậy, chúng tôi sẽ chỉ ghi lại cách định cấu hình trường hợp sử dụng truy xuất quảng cáo dựa trên TEE.
Xử lý yêu cầu UDF
function HandleRequest(requestMetadata, preparedDataForAdRetrieval,
deviceMetadata, contextualSignals) {
return adsMetadataString;
}
Trong trường hợp:
requestMetadata: JSON. Siêu dữ liệu máy chủ theo yêu cầu sang UDF. Hiện đang trống.preparedDataForAdRetrieval: nội dung của trường này phụ thuộc vào chiến lược truy xuất quảng cáo. Trong trường hợp truy xuất quảng cáo theo bối 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ừ dịch vụ đặ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 UDFprepareDataForAdRetrieval. Lưu ý: ở giai đoạn này, Tín hiệu ứng dụng được bảo vệ 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 thông tin chi tiết.X-Accept-Language: ngôn ngữ 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ừ máy chủ đặt giá thầu theo bối cảnh do cùng một DSP điều hành. UDF dự kiến sẽ 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, chẳng hạn như thông tin về phiên bản mô hình học máy cho hoạt động nhúng được bảo vệ được truyền vào bằng Tín hiệu ứng dụng được bảo vệ.
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, sau đó sẽ chuyển chuỗi này đến UDF generateBid. Mặc dù chuỗi có thể chỉ là một chuỗi đơn giản, nhưng nhiều khả năng chuỗi phải là một đối tượng nối tiếp có giản đồ do từng công nghệ quảng cáo xác định riêng.
Không có quy tắc ràng buộc nào trên giản đồ, miễn là logic generateBid của công nghệ quảng cáo có thể nhận dạng 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:
- 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
- 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 ý.
- 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;
- Khởi động lại thiết bị.
- 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 khách hàng đã triển khai Dịch vụ truy xuất quảng cáo TEE riêng (xem phần 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) được 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, generateBidvàreportWincó 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ụ KV và truy xuất quảng cáo
Tuỳ thuộc vào các chiến lược đượ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 thực thể của dịch vụ KV. Chúng tôi sẽ tham chiếu đến thực thể KV được dùng cho việc truy xuất quảng cáo dựa trên TEE là Ad Retrieval Server, và gọi là thực thể để hỗ trợ việc truy xuất dựa trên đường dẫn theo bối cảnh là 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 GitHub của máy chủ KV, sự khác biệt giữa 2 trường hợp là trường hợp tra cứu hoạt động ngay từ đầu mà không có bất kỳ cấu hình bổ sung nào, trong khi quá trình 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 Hướng dẫn bắt đầu sử dụng máy chủ KV. Xin lưu ý rằng B&A dự kiến cả hai dịch vụ đều được triển khai trong 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.