Là người mua quảng cáo (DSP và nhà quảng cáo), bạn có thể quan tâm đến việc tham gia phiên đấu giá quảng cáo sử dụng Protected Audience API trên trang web của nhà xuất bản để nhắm quảng cáo đến nhóm đối tượng có cùng mối quan tâm mà bạn đã xác định trên trang web của nhà quảng cáo. Khi tham gia phiên đấu giá sử dụng Protected Audience API, bạn có thể tiếp cận những khách hàng đã xác định được trên các trang web khác theo cách bảo đảm quyền riêng tư.
Trong phiên đấu giá sử dụng Protected Audience API, bạn cung cấp logic để tạo giá thầu và trình duyệt sẽ tính toán giá thầu bằng cách sử dụng logic đó. Điều này trái ngược với các cấu trúc đấu giá khác, trong đó bạn gửi giá thầu trực tiếp thay vì cung cấp logic.
Bạn cung cấp logic tạo giá thầu trong hàm JavaScript generateBid() và tệp này được lưu trữ trên máy chủ của bạn. Khi bạn thêm người dùng vào một nhóm mối quan tâm, vị trí của tệp này sẽ được chuyển vào cấu hình nhóm mối quan tâm dưới dạng biddingLogicUrl.
Trong phiên đấu giá, trình duyệt sẽ tìm nạp logic đặt giá thầu được chỉ định trong trường biddingLogicUrl, rồi thực thi hàm generateBid() cho từng nhóm mối quan tâm trong một môi trường riêng biệt bảo mật, bị hạn chế khả năng giao tiếp với ngữ cảnh bên ngoài. Khi generateBid() được thực thi, trình duyệt sẽ truyền các tín hiệu đến hàm dưới dạng đối số. Các tín hiệu này chứa nhiều thông tin từ nhiều nguồn, chẳng hạn như dữ liệu bên thứ nhất của nhà xuất bản, dữ liệu của người bán, dữ liệu theo thời gian thực, v.v. Bạn có thể sử dụng các tín hiệu này để tính toán giá thầu và giá trị được trả về từ lệnh gọi generateBid(). Sau khi giá thầu được gửi, trình duyệt sẽ thực thi logic chấm điểm của người bán trên từng giá thầu để tính điểm số mong muốn của người bán.
generateBid()
Phần sau đây mô tả các đối số của hàm generateBid() và cấu trúc của giá thầu được hàm trả về:
generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals, directFromSellerSignals) {
return {
ad: adObject,
adCost: optionalAdCost,
bid: bidValue,
bidCurrency: 'USD',
render: {
url: renderURL,
width: renderWidth,
height: renderHeight
},
adComponents: [
{url: adComponent1, width: componentWidth1, height: componentHeight1},
{url: adComponent2, width: componentWidth2, height: componentHeight2},
// ...
],
allowComponentAuction: false,
modelingSignals: 123 // 0-4095 integer (12-bits)
};
}
Đối số
generateBid() nhận các đối số sau:
| Đối số | Vai trò |
|---|---|
|
Đối tượng được người mua quảng cáo chuyển đến. Bạn có thể cập nhật nhóm đối tượng có cùng mối quan tâm bằng dailyUpdateUrl. |
|
Một tài sản của đối số Cấu hình phiên đấu giá được người bán truyền cho navigator.runAdAuction(). Mục này cung cấp thông tin về bối cảnh của trang (chẳng hạn như kích thước quảng cáo và mã nhà xuất bản), loại phiên đấu giá (giá đầu tiên hoặc giá thứ hai) và siêu dữ liệu khác. |
|
Một tài sản của đối số cấu hình phiên đấu giá do người bán chuyển. Tính năng này có thể cung cấp tín hiệu bối cảnh từ máy chủ của người mua về trang, nếu người bán là SSP thực hiện lệnh gọi đặt giá thầu theo thời gian thực đến máy chủ của người mua và chuyển lại phản hồi, hoặc nếu trang của nhà xuất bản liên hệ trực tiếp với máy chủ của người mua. Nếu có, người mua nên kiểm tra chữ ký mã hoá của các tín hiệu đó bên trong generateBid() để tránh hành vi can thiệp. |
|
Một đối tượng có khoá là trustedBiddingSignalsKeys cho nhóm mối quan tâm và có giá trị được trả về trong yêu cầu trustedBiddingSignals. |
|
Một đối tượng do trình duyệt tạo ra, có thể bao gồm thông tin về bối cảnh của trang (chẳng hạn như hostname của trang hiện tại mà người bán có thể giả mạo) và dữ liệu cho chính nhóm đối tượng có cùng mối quan tâm (chẳng hạn như bản ghi về thời điểm trước đó nhóm này đã thắng phiên đấu giá, để cho phép giới hạn tần suất trên thiết bị). |
|
Các tín hiệu được đảm bảo đến từ một người bán cụ thể, không giống như auctionSignals và sellerSignals có thể đến từ bất kỳ người tham gia nào có mặt trong bối cảnh runAdAuction được thực thi. |
Tín hiệu của trình duyệt
Đối tượng browserSignals có các thuộc tính sau:
{
topWindowHostname: 'publisher.example',
seller: 'https://ssp.example',
topLevelSeller: 'https://www.top-level-ssp.com',
requestedSize: {width: 100, height: 200}, /* if specified in auction config */
joinCount: 3,
recency: 3600000,
bidCount: 17,
prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
wasmHelper: ...
dataVersion: 1,
adComponentsLimit: 40
}
| Thuộc tính | Mô tả |
|---|---|
|
Tên máy chủ nơi thực hiện lệnh gọi runAdAuction(). |
|
Người bán nhận giá thầu. Trong phiên đấu giá thành phần, giá trị này là người bán thành phần. |
|
Người bán cấp cao nhất trong phiên đấu giá thành phần và chỉ xuất hiện trong phiên đấu giá thành phần. |
|
Tài sản requestedSize đề xuất kích thước khung hình cho phiên đấu giá. Người bán đặt kích thước được yêu cầu trong cấu hình đấu giá và giá trị này sẽ được cung cấp cho bên đặt giá thầu trong generateBid(). Bên đặt giá thầu trong phiên đấu giá có thể chọn một kích thước nội dung khác cho quảng cáo và kích thước thu được sẽ được điều chỉnh theo tỷ lệ một cách trực quan cho vừa với kích thước vùng chứa của phần tử. |
|
Trường joinCount là số lần thiết bị này tham gia nhóm đối tượng có cùng mối quan tâm này trong 30 ngày qua khi nhóm đối tượng có cùng mối quan tâm này liên tục được lưu trữ (tức là không có khoảng trống trong việc lưu trữ nhóm đối tượng có cùng mối quan tâm trên thiết bị do nhóm đối tượng này đã rời khỏi hoặc gói thành viên hết hạn). |
|
Trường recency là khoảng thời gian (tính bằng phút) kể từ khi thiết bị này tham gia nhóm mối quan tâm này cho đến bây giờ |
|
Số lần nhóm quan tâm đó đã gửi giá thầu. |
|
Trường prevWinMs chứa quảng cáo chiến thắng của nhóm đối tượng có cùng mối quan tâm và thời gian kể từ khi các quảng cáo đó giành chiến thắng trước đó tính bằng mili giây. Lưu ý rằng đối tượng quảng cáo ở đây chỉ chứa các trường renderURL và siêu dữ liệu. |
|
đối tượng WebAssembly.Module dựa trên biddingWasmHelperURL của nhóm mối quan tâm. |
|
Giá trị phiên bản dữ liệu từ(các) phản hồi dịch vụ Khoá/Giá trị của người mua. |
|
Số lượng thành phần quảng cáo tối đa generateBid() có thể trả về |
Tính toán giá thầu
Để tính toán giá trị giá thầu, mã trong generateBid() có thể sử dụng các thuộc tính của các tham số của hàm.
Ví dụ:
function generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
return {
// ...
bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
// ...
}
}
Trả về một giá thầu
generateBid() trả về một đối tượng có các thuộc tính sau:
| Thuộc tính | Vai trò |
|---|---|
ad |
Siêu dữ liệu tuỳ ý về quảng cáo, chẳng hạn như thông tin mà người bán muốn tìm hiểu về giá thầu hoặc mẫu quảng cáo này. Người bán sử dụng thông tin này theo logic đấu giá và quyết định. |
adCost |
Một giá trị bằng số được dùng để chuyển chi phí lượt nhấp hoặc lượt chuyển đổi của nhà quảng cáo báo cáo từ generateBid đến reportWin. Độ chính xác của số này được giới hạn ở phần định trị 8 bit và số mũ 8 bit, với bất kỳ phép làm tròn nào được thực hiện ngẫu nhiên. |
adComponents |
Danh sách (không bắt buộc) gồm tối đa 20 thành phần cho quảng cáo gồm nhiều phần, được lấy từ thuộc tính adComponents của đối số nhóm mối quan tâm được chuyển đến navigator.joinAdInterestGroup(). |
allowComponentAuction |
Giá trị boolean cho biết liệu giá thầu này có thể dùng trong phiên đấu giá thành phần hay không. Giá trị mặc định là "false" nếu không được chỉ định. |
bid |
Giá thầu bằng số sẽ tham gia phiên đấu giá. Người bán phải có vị trí để so sánh giá thầu từ những người mua khác nhau, do đó, giá thầu phải theo một số đơn vị do người bán chọn (chẳng hạn như "USD trên một nghìn"). Nếu giá thầu bằng 0 hoặc âm, thì nhóm mối quan tâm này sẽ hoàn toàn không tham gia vào phiên đấu giá của người bán. Với cơ chế này, người mua có thể triển khai mọi quy tắc dành cho nhà quảng cáo đối với vị trí mà quảng cáo của họ có thể xuất hiện hoặc không xuất hiện. |
bidCurrency |
Đơn vị tiền tệ của giá thầu, dùng để currency-checking. |
render |
Từ điển mô tả mẫu quảng cáo sẽ được hiển thị nếu giá thầu này thắng phiên đấu giá. Trong đó có:
|
|
Số nguyên 0-4095 (12 bit) được truyền đến reportWin() có gây nhiễu, như mô tả trong sơ đồ gây nhiễu và phân giỏ. Các giá trị không hợp lệ (chẳng hạn như giá trị âm, vô hạn và NaN) sẽ bị bỏ qua và không được chuyển. Chỉ 12 bit thấp nhất sẽ được truyền. Người mua có thể sử dụng các tín hiệu có sẵn trong hàm generateBid(), bao gồm cả dữ liệu từ người mua bên thứ nhất, thu thập tại thời điểm tạo Nhóm mối quan tâm ở userBiddingSignals, để lấy giá trị nào đó được truyền đến chức năng báo cáo giành chiến thắng của người mua để có thể huấn luyện mô hình học máy. |