ad techproject_path: /_project.yaml book_path: /_book.yaml keywords: api:ProtectedAppSignals, docType:Guide, skill:Beginner, audienceAdBuyer, audienceAdSeller, topicAdAuction, contentTypeFundamental, category:Mobile, apiGroupAds
เอกสารนี้จะอธิบาย API ทั้งหมดภายในพื้นผิว API รายละเอียดวิธี ตั้งค่าสภาพแวดล้อมการทดสอบ และแสดงตัวอย่างการกำหนดค่าและ สคริปต์ เพื่อช่วยให้นักพัฒนาแอปเริ่มทดสอบ Protected App Signals API ได้
ประวัติเวอร์ชัน
Jan 2024
คู่มือนักพัฒนาซอฟต์แวร์ฉบับแรกที่รองรับการเปิดตัว PAS MVP
มีนาคม 2024
การเปลี่ยนแปลงใน API เพื่อรองรับการเปิดตัว Android API เวอร์ชัน M-2024-05 และ การเปิดตัวคอมโพเนนต์ฝั่งเซิร์ฟเวอร์ในเดือนเมษายน 2024 การเปลี่ยนแปลงที่สำคัญที่สุดมีดังนี้
- เพิ่มรายละเอียดเกี่ยวกับสิทธิ์ที่จำเป็นสำหรับ API ในอุปกรณ์
- เพิ่มรายละเอียดเกี่ยวกับการจัดการโควต้าสัญญาณในอุปกรณ์
- อัปเดต
generateBid
ลายเซ็นพร้อมการเปลี่ยนแปลงที่เกี่ยวข้องกับการดึงโฆษณาตามบริบทและการรองรับการส่งออก - อัปเดต
reportWin
เอกสารประกอบ รวมถึงการรองรับการส่งออก - อัปเดตเอกสารประกอบของ Ad Retrieval API โดยนำการรองรับการดึงโฆษณา BYOS ออก และจัดทำเอกสารประกอบของ UDF การดึงโฆษณา
ภาพรวมของ API
พื้นผิวของ Protected Signals API มี API ที่เป็นเซ็ตย่อยต่างๆ ในระบบที่แตกต่างกัน ดังนี้
- API ของ Android
- Signal Curation API ซึ่งประกอบด้วย
- Update Signals API
- Signals Encoding API
- Protected Auction Support API: ใช้โดย SDK เพื่อเรียกใช้การประมูลที่ได้รับการปกป้องในเซิร์ฟเวอร์การเสนอราคาและการประมูล (B&A) โดยใช้สัญญาณแอปที่ได้รับการปกป้อง
- API ฝั่งเซิร์ฟเวอร์
- Protected Auction API: ชุดสคริปต์ JS ที่ทำงานในเซิร์ฟเวอร์การเสนอราคาและการประมูล API นี้ช่วยให้ผู้ขายและผู้ซื้อเขียนตรรกะเพื่อ ใช้การประมูลที่ได้รับการปกป้องได้
- Ad Retrieval API: มีหน้าที่จัดทำรายการโฆษณาที่อาจแสดงโดยอิงตามข้อมูลบริบทและข้อมูลผู้ใช้ที่พร้อมใช้งานสำหรับเซิร์ฟเวอร์การเสนอราคาของผู้ซื้อ
ไคลเอ็นต์ Android
ในฝั่งไคลเอ็นต์ พื้นผิวของ Protected App Signals ประกอบด้วย API ที่แตกต่างกัน 3 รายการ ดังนี้
- สัญญาณการอัปเดต: API ของระบบ Android เพื่อเปิดใช้การดูแลจัดการสัญญาณในอุปกรณ์
- การเข้ารหัสสัญญาณ: API ของ JavaScript เพื่อเตรียมสัญญาณที่จะส่งไปยังเซิร์ฟเวอร์ระหว่างการประมูล
- การรองรับการประมูลที่ได้รับการปกป้อง: API ที่รองรับการดำเนินการประมูลที่ได้รับการปกป้องในเซิร์ฟเวอร์การเสนอราคาและการประมูล API นี้ไม่ได้เจาะจงสำหรับ สัญญาณแอปที่ได้รับการปกป้อง และยังใช้เพื่อรองรับการประมูลสำหรับ Protected Audience API ด้วย
Update Signals API
Update Signals API ช่วยให้เทคโนโลยีโฆษณาสามารถลงทะเบียนสัญญาณที่เกี่ยวข้องกับผู้ใช้และแอปในนามของผู้ซื้อ API ทำงานในรูปแบบการมอบสิทธิ์ ผู้โทรระบุ URI ที่เฟรมเวิร์กจะดึงสัญญาณที่เกี่ยวข้องและตรรกะเพื่อเข้ารหัสสัญญาณเหล่านั้นเพื่อใช้ในการประมูล
API ต้องใช้สิทธิ์ android.permission.ACCESS_ADSERVICES_PROTECTED_SIGNALS
updateSignals()
API จะดึงออบเจ็กต์ JSON
จาก URI ที่อธิบายว่าควรเพิ่มหรือนำสัญญาณใดออก และวิธีเตรียม
สัญญาณเหล่านั้นสำหรับการประมูล
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);
แพลตฟอร์มจะส่งคำขอ https ไปยัง URI ที่ระบุในคำขอเพื่อดึงข้อมูลการอัปเดตสัญญาณ นอกจากการอัปเดตสัญญาณแล้ว การตอบกลับยังอาจมี ปลายทางที่โฮสต์ตรรกะการเข้ารหัสสำหรับการแปลงสัญญาณดิบเป็น เพย์โหลดที่เข้ารหัส การอัปเดตสัญญาณควรอยู่ในรูปแบบ JSON และมีคีย์ต่อไปนี้
คีย์ระดับบนสุดสำหรับออบเจ็กต์ JSON ต้องสอดคล้องกับคำสั่งใดคำสั่งหนึ่งใน 5 คำสั่งต่อไปนี้
คีย์ |
คำอธิบาย |
|
เพิ่มสัญญาณใหม่ โดยเขียนทับสัญญาณที่มีอยู่ซึ่งมีคีย์เดียวกัน ค่า เนื่องจากเป็นออบเจ็กต์ JSON ที่คีย์เป็นสตริง Base64 ที่สอดคล้องกับคีย์ที่จะใส่ และค่าเป็นสตริง Base64 ที่สอดคล้องกับค่าที่จะใส่ |
|
เพิ่มสัญญาณใหม่ลงในอนุกรมเวลาของสัญญาณ โดยนำสัญญาณที่เก่าที่สุดออก เพื่อเพิ่มพื้นที่สำหรับรายการใหม่ หากขนาดของซีรีส์เกินขีดจำกัดสูงสุดที่ระบุ ค่าสำหรับพารามิเตอร์นี้คือออบเจ็กต์ JSON ซึ่งคีย์เป็นสตริง Base64 ที่สอดคล้องกับคีย์ที่จะต่อท้าย และค่าเป็นออบเจ็กต์ที่มี 2 ฟิลด์ ได้แก่ "values" และ "maxSignals" "values": รายการสตริง Base64 ที่สอดคล้องกับค่าสัญญาณที่จะต่อท้ายอนุกรมเวลา "maxSignals": จำนวนค่าสูงสุดที่อนุญาตในอนุกรมเวลา ตามเงื่อนไข จำนวนสัญญาณปัจจุบันที่เชื่อมโยงกับคีย์เกิน maxSignals ระบบจะนำสัญญาณที่เก่าที่สุดออก โปรดทราบว่าคุณสามารถต่อท้ายคีย์ที่เพิ่มโดยใช้ put ได้ โปรดทราบว่าการต่อท้ายค่ามากกว่าจำนวนค่าสูงสุดจะทำให้เกิดข้อผิดพลาด |
|
เพิ่มสัญญาณใหม่เฉพาะในกรณีที่ไม่มีสัญญาณที่มีอยู่ซึ่งมีคีย์เดียวกัน ค่าสำหรับพารามิเตอร์นี้คือออบเจ็กต์ JSON ซึ่งคีย์เป็นสตริง Base64 ที่สอดคล้องกับคีย์ที่จะใส่ และค่าเป็นสตริง Base64 ที่สอดคล้องกับค่าที่จะใส่ |
|
นำสัญญาณสำหรับคีย์ออก ค่าของพารามิเตอร์นี้คือรายการสตริง Base64 ที่สอดคล้องกับคีย์ของสัญญาณที่ควรลบ |
|
ระบุการดำเนินการเพื่ออัปเดตปลายทางและ URI ที่ใช้ได้ เพื่อดึงตรรกะการเข้ารหัส คีย์ย่อยสำหรับการดำเนินการอัปเดตคือ "action" และ ค่าที่รองรับมีเพียง "REGISTER" ซึ่งจะลงทะเบียนปลายทางของตัวเข้ารหัสหากระบุเป็นครั้งแรก หรือเขียนทับค่าที่มีอยู่ด้วยปลายทางที่ระบุใหม่ ต้องระบุปลายทางสำหรับการดำเนินการ "REGISTER" คีย์ย่อยสำหรับการระบุปลายทางของตัวเข้ารหัสคือ "endpoint" และค่าคือ URI สตริงสำหรับปลายทาง |
คำขอ JSON ตัวอย่างจะมีลักษณะดังนี้
{
"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"
}
}
สัญญาณจะมีโควต้าในอุปกรณ์ประมาณ 10-15 KB เมื่อโควต้า เกิน PPAPI จะนำสัญญาณออกโดยใช้กลยุทธ์ FIFO กระบวนการนำออก จะอนุญาตให้โควต้าเกินเล็กน้อยในช่วงเวลาสั้นๆ เพื่อลดความถี่ในการนำออก
Signals Encoding API
ผู้ซื้อต้องระบุฟังก์ชัน JavaScript ที่จะใช้ในการเข้ารหัสสัญญาณที่จัดเก็บไว้ในอุปกรณ์เพื่อส่งไปยังเซิร์ฟเวอร์ในระหว่างการประมูลที่ได้รับการปกป้อง ผู้ซื้อสามารถระบุสคริปต์นี้ได้โดยการเพิ่ม URL ที่สามารถดึงข้อมูลได้โดยใช้คีย์ "update_encoder" ในการตอบกลับคำขอ UpdateSignal API สคริปต์จะมีลายเซ็นต่อไปนี้
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)};
}
พารามิเตอร์ signals
คือแมปจากคีย์ในรูปแบบ UInt8Arrays ขนาด 4
ไปยังรายการของออบเจ็กต์สัญญาณแอปที่ปกป้องความเป็นส่วนตัว ออบเจ็กต์ Protected App Signals แต่ละรายการมี 3 ช่อง ดังนี้
signal_value
: ออบเจ็กต์ UInt8Array ที่แสดงค่าของสัญญาณcreation_time
: ตัวเลขที่แสดงเวลาสร้างของสัญญาณใน หน่วยวินาทีตั้งแต่ Epochpackage_name
: สตริงที่แสดงชื่อของแพ็กเกจที่สร้าง สัญญาณ
พารามิเตอร์ maxSize
คือตัวเลขที่อธิบายขนาดอาร์เรย์สูงสุดที่อนุญาต
สำหรับเอาต์พุต
ฟังก์ชันควรแสดงผลออบเจ็กต์ที่มี 2 ฟิลด์ ดังนี้
status
: ควรเป็น 0 หากสคริปต์ทำงานสำเร็จresults
: ควรเป็น UInt8Array ที่มีความยาวน้อยกว่าหรือเท่ากับ maxSize ระบบจะส่งอาร์เรย์นี้ไปยังเซิร์ฟเวอร์ระหว่างการประมูล และสคริปต์prepareDataForAdRetrieval
จะเป็นผู้เตรียมอาร์เรย์
การเข้ารหัสช่วยให้เทคโนโลยีโฆษณามีขั้นตอนเริ่มต้นในการสร้างฟีเจอร์ ซึ่งสามารถทำการแปลง เช่น การบีบอัดสัญญาณดิบเป็น เวอร์ชันที่ต่อกันตามตรรกะที่กำหนดเอง โปรดทราบว่าในระหว่าง การประมูลที่ได้รับการปกป้องซึ่งทํางานในสภาพแวดล้อมการดำเนินการที่เชื่อถือได้ (TEE) ตรรกะที่กําหนดเองของเทคโนโลยีโฆษณา จะมีสิทธิ์เข้าถึงแบบอ่านเพย์โหลดของสัญญาณที่สร้างขึ้นโดยการ เข้ารหัส ตรรกะที่กำหนดเองซึ่งเรียกว่าฟังก์ชันที่ผู้ใช้กำหนด (UDF) ที่ทำงานใน TEE ของ B&A ของผู้ซื้อ จะมีสิทธิ์เข้าถึงแบบอ่านสำหรับสัญญาณที่เข้ารหัสและสัญญาณตามบริบทอื่นๆ ที่แอปของผู้เผยแพร่โฆษณามอบให้เพื่อทำการเลือกโฆษณา (การดึงข้อมูลโฆษณาและ การเสนอราคา)
การเข้ารหัสสัญญาณ
ทุกๆ ชั่วโมง ผู้ซื้อที่ระบุตรรกะการเข้ารหัสพร้อมสัญญาณที่ลงทะเบียนไว้ จะได้รับการเข้ารหัสสัญญาณลงในเพย์โหลดการประมูล ระบบจะจัดเก็บอาร์เรย์ไบต์ สำหรับเพย์โหลดการประมูลไว้ในอุปกรณ์ จากนั้นจะเข้ารหัสและ ผู้ขายจะรวบรวมเป็นส่วนหนึ่งของข้อมูลการเลือกโฆษณาเพื่อรวมไว้เป็นส่วนหนึ่ง ของการประมูลที่ได้รับการคุ้มครอง สำหรับการทดสอบ คุณสามารถทริกเกอร์การเข้ารหัสนี้ภายนอก รอบการทำงานรายชั่วโมงได้โดยเรียกใช้คำสั่งต่อไปนี้
adb shell cmd jobscheduler run -f com.google.android.adservices.api 29
การกำหนดเวอร์ชันตรรกะของตัวเข้ารหัส
เมื่อมีการส่งคำขอเพื่อดาวน์โหลดตรรกะของเครื่องมือเข้ารหัสที่กำหนดเองของเทคโนโลยีโฆษณา ปลายทางของเทคโนโลยีโฆษณาสามารถตอบกลับด้วยหมายเลขเวอร์ชันในส่วนหัวของการตอบกลับ เวอร์ชันนี้ จะคงอยู่พร้อมกับตรรกะของตัวเข้ารหัสในอุปกรณ์ เมื่อเข้ารหัสสัญญาณดิบ ระบบจะจัดเก็บเพย์โหลดที่เข้ารหัสพร้อมกับเวอร์ชันที่ใช้สำหรับ การเข้ารหัส นอกจากนี้ ระบบยังส่งเวอร์ชันนี้ไปยังเซิร์ฟเวอร์ B&A ในระหว่างการประมูลที่ได้รับการปกป้องด้วย เพื่อให้เทคโนโลยีโฆษณาสามารถปรับตรรกะการเสนอราคาและการเข้ารหัสตามเวอร์ชันได้
Response header for providing encoder version : X_ENCODER_VERSION
Protected Auction Support API
ในฝั่งอุปกรณ์ การเรียกใช้การประมูลสำหรับสัญญาณแอปที่ได้รับการปกป้องจะเหมือนกับการเรียกใช้การประมูลสำหรับกลุ่มเป้าหมายที่ได้รับการปกป้อง
บริการเสนอราคาและประมูล
API ฝั่งเซิร์ฟเวอร์ประกอบด้วย
- Protected Auction API: ชุดฟังก์ชัน JS หรือ UDF ที่ผู้ซื้อและผู้ขายสามารถติดตั้งใช้งานในคอมโพเนนต์ B&A ที่ตนเป็นเจ้าของ เพื่อกำหนดตรรกะการเสนอราคาและการประมูล
- Ad Retrieval API: ผู้ซื้อสามารถใช้ API นี้ได้โดยการใช้ REST Endpoint ซึ่งจะรับผิดชอบในการระบุชุดโฆษณาที่เป็นไปได้สำหรับการประมูลสัญญาณแอปที่ได้รับการปกป้อง
Protected Auction API
Protected Auction API ประกอบด้วย JS API หรือ UDF ที่ผู้ซื้อและผู้ขายสามารถ ใช้เพื่อติดตั้งใช้งานตรรกะการประมูลและการเสนอราคาของตน
UDF เทคโนโลยีโฆษณาของผู้ซื้อ
UDF prepareDataForAdRetrieval
ก่อนที่จะใช้สัญญาณแอปที่ได้รับการปกป้องเพื่อดึงผู้สมัครรับเลือกเป็นโฆษณาจาก TEE
บริการดึงข้อมูลโฆษณา ผู้ซื้อจะต้องถอดรหัสและเตรียมสัญญาณแอปที่ได้รับการปกป้อง
และข้อมูลอื่นๆ ที่ผู้ขายระบุ ระบบจะส่งเอาต์พุต UDF ของผู้ซื้อ prepareDataForAdRetrieval
ไปยังบริการดึงข้อมูลโฆษณาเพื่อดึงโฆษณาผู้สมัครรับเลือก k อันดับแรกสำหรับการเสนอราคา
// 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 ad tech.
function prepareDataForAdRetrieval(encodedOnDeviceSignals,encodedOnDeviceSignalsVersion,sellerAuctionSignals,contextualSignals) {
return {};
}
UDF generateBid
หลังจากแสดงโฆษณาผู้สมัครรับเลือก k อันดับแรกแล้ว ระบบจะส่งผู้สมัครรับเลือกโฆษณาไปยังตรรกะการเสนอราคาที่กำหนดเองของผู้ซื้อ 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>
};
}
เอาต์พุตของฟังก์ชันนี้คือราคาเสนอเดียวสำหรับโฆษณาที่อาจเป็นโฆษณาที่เหมาะสม ซึ่งแสดงเป็น JSON ที่เทียบเท่ากับ ProtectedAppSignalsAdWithBidMetadata
ฟังก์ชันยังแสดงผลอาร์เรย์ 2 รายการได้ด้วย ซึ่งจะส่งไปยัง reportWin
เพื่อเปิดใช้การฝึกโมเดล (ดูรายละเอียดเพิ่มเติมเกี่ยวกับการส่งออกและการฝึกโมเดลได้ที่ส่วนการรายงานในคำอธิบาย PAS)
reportWin UDF
เมื่อการประมูลสิ้นสุดลง บริการการประมูลจะสร้าง URL การรายงานสำหรับ
ผู้ซื้อและลงทะเบียนบีคอนโดยใช้ reportWin
UDF (นี่คือฟังก์ชันreportWin
เดียวกันที่ใช้สำหรับ Protected Audience)
อุปกรณ์จะใช้คำสั่ง ping กับ URL นี้เมื่อไคลเอ็นต์แสดงโฆษณาแล้ว
ลายเซ็นของเมธอดนี้เกือบจะเหมือนกับเวอร์ชันของกลุ่มเป้าหมายที่ปกป้องความเป็นส่วนตัว ยกเว้นพารามิเตอร์เพิ่มเติม 2 รายการ egressPayload
และ
temporaryUnlimitedEgressPayload
ที่ใช้เพื่อเปิดใช้การฝึกโมเดลและจะ
ป้อนข้อมูลผลลัพธ์จาก generateBid
// Inputs / Outputs
// ----------------
// See detailed documentation here.
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
buyerReportingSignals,
egressPayload, temporaryUnlimitedEgressPayload) {
// ...
}
UDF เทคโนโลยีโฆษณาของผู้ขาย
UDF ของ scoreAd
ผู้ขายใช้UDF นี้เพื่อเลือกโฆษณาที่ได้รับจากผู้ซื้อซึ่งจะชนะการประมูล
function scoreAd(adMetadata, bid, auctionConfig,
trustedScoringSignals, bid_metadata) {
// ...
return {desirability: desirabilityScoreForThisAd,
allowComponentAuction: true_or_false};
}
UDF ของ reportResult
UDF นี้ช่วยให้ผู้ขาย (ในที่สุด) ทำการรายงานระดับเหตุการณ์ด้วยข้อมูลเกี่ยวกับโฆษณาที่ชนะได้
function reportResult(auctionConfig, reporting_metadata) {
// ...
registerAdBeacon({"click", clickUrl,"view", viewUrl});
sendReportTo(reportResultUrl);
return signalsForWinner;
}
Ad Retrieval API
ในการเปิดตัว MVP บริการดึงข้อมูลโฆษณาจะเป็นบริการที่ผู้ซื้อจัดการและโฮสต์ และบริการเสนอราคาจะดึงข้อมูลโฆษณาที่อาจเป็นไปได้จากบริการนี้ ตั้งแต่เดือนเมษายน 2024 เป็นต้นไป เซิร์ฟเวอร์การดึงข้อมูลโฆษณาต้องทำงานในสภาพแวดล้อมการดำเนินการที่เชื่อถือได้ (TEE) และจะแสดงอินเทอร์เฟซ GRPC/proto บริษัทเทคโนโลยีโฆษณา ต้องตั้งค่าเซิร์ฟเวอร์นี้และระบุ URL ของเซิร์ฟเวอร์เป็นส่วนหนึ่งของการติดตั้งใช้งานสแต็ก B&A การติดตั้งใช้งานบริการนี้ที่ทำงานใน TEE มีอยู่ใน GitHub ของ Privacy Sandbox และในส่วนที่เหลือของ เอกสารประกอบ เราถือว่านี่คือโค้ดที่ใช้ในการติดตั้งใช้งาน
ตั้งแต่เดือนเมษายน 2024 เป็นต้นไป เวอร์ชัน B&A จะรองรับการดึงโฆษณาเส้นทางตามบริบท ในกรณีนี้ เซิร์ฟเวอร์การเสนอราคาจะได้รับรายการ ตัวระบุโฆษณาที่เซิร์ฟเวอร์ RTB ส่งมาในระหว่างส่วนตามบริบทของการประมูล ระบบจะส่งตัวระบุไปยังเซิร์ฟเวอร์ KV ของ TEE เพื่อดึงข้อมูลทั้งหมดที่เกี่ยวข้องกับโฆษณา เพื่อใช้ในระยะการเสนอราคา (เช่น URL การแสดงโฆษณา ข้อมูลเมตา และการฝังโฆษณาที่จะใช้ในการ เลือก k อันดับแรก) เส้นทางที่ 2 นี้ไม่จำเป็นต้องมีตรรกะเฉพาะใดๆ ในการ ติดตั้งใช้งาน ดังนั้นเราจะบันทึกเฉพาะวิธีตั้งค่า TEE ตาม กรณีการใช้งานการดึงโฆษณาที่นี่
UDF getCandidateAds
function getCandidateAds(requestMetadata, preparedDataForAdRetrieval,
deviceMetadata, contextualSignals, contextualAdIds,) {
return adsMetadataString;
}
สถานที่:
requestMetadata
: JSON ข้อมูลเมตาของเซิร์ฟเวอร์ต่อคำขอไปยัง UDF ยังไม่มีข้อมูลpreparedDataForAdRetrieval
: เนื้อหาของฟิลด์นี้ขึ้นอยู่กับกลยุทธ์การดึงข้อมูลโฆษณา ในกรณีของการดึงโฆษณาตามบริบท พารามิเตอร์นี้ จะมีสัญญาณดิบที่มาจากอุปกรณ์และส่งผ่านจาก บริการเสนอราคา ในกรณีของการดึงโฆษณา TEE โดยใช้เซิร์ฟเวอร์การดึงโฆษณา พารามิเตอร์นี้จะมีผลลัพธ์ของprepareDataForAdRetrieval
UDF หมายเหตุ: ในขั้นตอนนี้ ระบบจะถอดรหัสและยกเลิกการเข้ารหัสสัญญาณของแอปที่ได้รับการปกป้องdeviceMetadata
: ออบเจ็กต์ JSON ที่มีข้อมูลเมตาของอุปกรณ์ซึ่งส่งต่อโดยบริการโฆษณาของผู้ขาย ดูรายละเอียดเพิ่มเติมได้ในเอกสารประกอบของ B&AX-Accept-Language
: ภาษาที่ใช้ในอุปกรณ์X-User-Agent
: User Agent ที่ใช้ในอุปกรณ์X-BnA-Client-IP
: ที่อยู่ IP ของอุปกรณ์
contextualSignals
: สตริงที่กำหนดเองซึ่งมาจากเซิร์ฟเวอร์การเสนอราคาตามบริบท ที่ดำเนินการโดย DSP เดียวกัน คาดว่า UDF จะถอดรหัสสตริงและใช้สตริงได้ สัญญาณตามบริบทอาจมีข้อมูลใดก็ได้ เช่น ข้อมูลเวอร์ชันโมเดล ML สำหรับการฝังที่ได้รับการปกป้องซึ่งส่งผ่านโดยใช้สัญญาณแอปที่ได้รับการปกป้องcontextualAdIds
: ออบเจ็กต์ JSON ที่มีรายการรหัสโฆษณาที่ไม่บังคับ
UDF ควรแสดงผลสตริงเมื่อสำเร็จ ระบบจะส่งคืนสตริงไปยัง
เซิร์ฟเวอร์การเสนอราคา ซึ่งจะส่งต่อไปยัง generateBid
UDF แม้ว่าสตริงจะเป็นสตริงพื้นฐานได้ แต่ส่วนใหญ่แล้วควรเป็นออบเจ็กต์ที่
ซีเรียลไลซ์ซึ่งมีสคีมาที่กำหนดโดยเทคโนโลยีโฆษณาแต่ละรายเอง
ไม่มีข้อจำกัดเกี่ยวกับสคีมาตราบใดที่generateBid
ตรรกะของเทคโนโลยีโฆษณาสามารถจดจำและใช้สตริงได้
ตั้งค่าระบบสำหรับการพัฒนา
Android
หากต้องการตั้งค่าสภาพแวดล้อมในการพัฒนา Android คุณต้องทำดังนี้
- สร้างโปรแกรมจำลอง (แนะนำ) หรืออุปกรณ์จริงที่ใช้รูปภาพ Developer Preview 10
- เรียกใช้คำสั่งต่อไปนี้
adb shell am start -n com.google.android.adservices.api/com.android.adservices.ui.settings.activities.AdServicesSettingsMainActivity
จากนั้นเลือกตัวเลือกที่แสดงเพื่อยินยอมให้ใช้โฆษณาที่แอปแนะนำ
- เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดใช้ API ที่เกี่ยวข้อง คุณอาจต้องเรียกใช้คำสั่งนี้อีกเป็นครั้งคราวเนื่องจากระบบจะซิงค์การกำหนดค่าเริ่มต้นของ "ปิดใช้" เป็นระยะๆ
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;
- รีสตาร์ทอุปกรณ์
- ลบล้างคีย์การประมูลของอุปกรณ์ให้ชี้ไปยังเซิร์ฟเวอร์คีย์การประมูลของคุณ คุณควรทำขั้นตอนนี้ก่อนที่จะพยายามเรียกใช้การประมูลเพื่อป้องกันไม่ให้ระบบแคชคีย์ที่ไม่ถูกต้อง
บริการเสนอราคาและประมูล
หากต้องการตั้งค่าเซิร์ฟเวอร์ B&A โปรดดูเอกสารการตั้งค่าแบบบริการตนเอง
เอกสารนี้จะมุ่งเน้นที่วิธีกำหนดค่าเซิร์ฟเวอร์เฉพาะผู้ซื้อ เนื่องจากผู้ขายไม่จำเป็นต้องทำการเปลี่ยนแปลงใดๆ
ข้อกำหนดเบื้องต้น
ก่อนที่จะติดตั้งใช้งานสแต็กบริการ B&A เทคโนโลยีโฆษณาของผู้ซื้อต้องดำเนินการต่อไปนี้
- ตรวจสอบว่าพาร์ทเนอร์ได้ติดตั้งใช้งานบริการดึงข้อมูลโฆษณา TEE ของตนเองแล้ว (ดูส่วนที่เกี่ยวข้อง)
- ตรวจสอบว่าเทคโนโลยีโฆษณามี UDF ที่จำเป็นทั้งหมด
(
prepareDataForAdRetrieval
,generateBid
,reportWin
,getCandidateAds
) ที่กำหนดและโฮสต์
นอกจากนี้ การทำความเข้าใจวิธีการทำงานของการประมูลที่ได้รับการปกป้องด้วย Protected Audience API กับ B&A ก็จะเป็นประโยชน์เช่นกัน แต่ไม่บังคับ
การกำหนดค่า Terraform
หากต้องการใช้สัญญาณแอปที่ได้รับการปกป้อง เทคโนโลยีโฆษณาต้องมีคุณสมบัติดังนี้
- เปิดใช้การรองรับสัญญาณแอปที่ได้รับการปกป้องใน B&A
- ระบุปลายทาง URL ที่สามารถดึงข้อมูล UDF ใหม่สำหรับ
prepareDataForAdRetrieval, generateBid
และreportWin
ได้
นอกจากนี้ คู่มือนี้ยังถือว่าเทคโนโลยีโฆษณาที่ต้องการใช้ B&A สำหรับ รีมาร์เก็ตติ้งจะยังคงตั้งค่าสถานะการกำหนดค่าที่มีอยู่ทั้งหมดสำหรับการประมูล รีมาร์เก็ตติ้งตามปกติ
การกำหนดค่าเทคโนโลยีโฆษณาของผู้ซื้อ
ผู้ซื้อต้องตั้งค่าสถานะต่อไปนี้โดยใช้ไฟล์เดโมนี้เป็นตัวอย่าง
- เปิดใช้สัญญาณแอปที่ได้รับการปกป้อง: เปิดใช้เพื่อรวบรวมข้อมูลสัญญาณแอปที่ได้รับการปกป้อง
- URL ของสัญญาณแอปที่ได้รับการปกป้อง: ตั้งค่าเป็น URL ของเซิร์ฟเวอร์สัญญาณแอปที่ได้รับการปกป้อง
เทคโนโลยีโฆษณาต้องแทนที่ URL ที่ถูกต้องในตัวยึดตำแหน่งสำหรับฟิลด์ต่อไปนี้
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"
การกำหนดค่าเทคโนโลยีโฆษณาของผู้ขาย
ผู้ขายต้องตั้งค่า Flag ต่อไปนี้โดยใช้ไฟล์การสาธิตนี้เป็นตัวอย่าง (หมายเหตุ: เราไฮไลต์เฉพาะการกำหนดค่าที่เกี่ยวข้องกับสัญญาณของแอปที่ได้รับการปกป้อง ที่นี่) เทคโนโลยีโฆษณาต้องยืนยันว่าได้แทนที่ URL ที่ถูกต้องใน ตัวยึดตำแหน่ง
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"
บริการ KV และการดึงข้อมูลโฆษณา
ระบบจะกำหนดให้ติดตั้งใช้งานอินสแตนซ์ของบริการ KV 1 หรือ 2 รายการ ทั้งนี้ขึ้นอยู่กับกลยุทธ์ที่เลือกเพื่อรองรับการดึงโฆษณา
เราจะอ้างอิง
อินสแตนซ์ KV ที่ใช้สำหรับการดึงโฆษณาที่อิงตาม TEE เป็นAd Retrieval Server
และอ้างอิงอินสแตนซ์ที่รองรับการดึงข้อมูลตามเส้นทางเชิงบริบทเป็นKV Lookup Server
ในทั้ง 2 กรณี การติดตั้งใช้งานเซิร์ฟเวอร์จะเป็นไปตามเอกสารที่มีอยู่ใน GitHub ของเซิร์ฟเวอร์ KV ความแตกต่างระหว่าง 2 กรณีคือ กรณีการค้นหาจะใช้งานได้ทันทีโดยไม่ต้องมีการกำหนดค่าเพิ่มเติม ในขณะที่กรณีการดึงข้อมูลต้องมีการติดตั้งใช้งาน UDF getCandidateAds
เพื่อใช้ตรรกะการดึงข้อมูล ดูรายละเอียดเพิ่มเติมได้ที่คู่มือการเริ่มต้นใช้งานเซิร์ฟเวอร์ KV โปรดทราบว่า B&A คาดหวังให้ทั้ง 2 บริการ
ได้รับการติดตั้งใช้งานใน Service Mesh เดียวกันกับบริการเสนอราคา
ตัวอย่างการตั้งค่า
พิจารณาสถานการณ์ต่อไปนี้ เมื่อใช้ Protected App Signals API เทคโนโลยีโฆษณาจะจัดเก็บสัญญาณที่เกี่ยวข้องตามการใช้แอปของผู้ใช้ ในตัวอย่างของเรา ระบบจะจัดเก็บสัญญาณที่แสดงถึงการซื้อในแอปจากแอปหลายแอป ในระหว่างการประมูล ระบบจะรวบรวมสัญญาณที่เข้ารหัสและส่งไปยังการประมูลที่ได้รับการคุ้มครองซึ่งทำงานใน B&A UDF ของผู้ซื้อที่ทํางานใน B&A จะใช้สัญญาณเพื่อดึงข้อมูลผู้สมัครรับเลือกโฆษณา และคํานวณราคาเสนอ
ตัวอย่างสัญญาณ [ผู้ซื้อ]
เพิ่มสัญญาณที่มีคีย์เป็น 0 และค่าเป็น 1
{
"put": {
"AA==": "AQ=="
},
"update_encoder": {
"action": "REGISTER",
"endpoint": "https://example.com/example_script"
}
}
เพิ่มสัญญาณที่มีคีย์เป็น 1 และค่าเป็น 2
{
"put": {
"AQ==": "Ag=="
},
"update_encoder": {
"action": "REGISTER",
"endpoint": "https://example.com/example_script"
}
}
ตัวอย่าง [ผู้ซื้อ] encodeSignals
เข้ารหัสแต่ละสัญญาณเป็น 2 ไบต์ โดยไบต์แรกคือไบต์แรกของคีย์สัญญาณ และไบต์ที่ 2 คือไบต์แรกของค่าสัญญาณ
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};
}
[ผู้ซื้อ] ตัวอย่าง 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, an 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 ad tech 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;
}
[ผู้ซื้อ] UDF การดึงโฆษณาตัวอย่าง
ในตัวอย่างของเรา เซิร์ฟเวอร์การดึงข้อมูลโฆษณาส่งข้อมูลเมตา (เช่น รหัสของโฆษณาแต่ละรายการใน ตัวอย่างนี้ แต่สามารถมีข้อมูลอื่นๆ สำหรับแต่ละรายการซึ่งอาจเป็นประโยชน์ในการ สร้างราคาเสนอในภายหลัง) สำหรับผู้สมัครรับเลือกเป็นโฆษณา k อันดับแรกแต่ละราย
function getCandidateAds(requestMetadata, protectedSignals, deviceMetadata,
contextualSignals, contextualAdIds,) {
return "[{\"adId\":\"0\"},{\"adId\":\"1\"}]"
ตัวอย่าง [ผู้ซื้อ] 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};
}
[ผู้ซื้อ] รายงานตัวอย่างการชนะ
reportWin
UDF จะรายงานให้ผู้ซื้อทราบว่าชนะการประมูล
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
buyerReportingSignals, directFromSellerSignals,
egressPayload,
temporaryUnlimitedEgressPayload) {
sendReportTo("https://buyer-controlled-domain.com/");
registerAdBeacon({"clickEvent":"https://buyer-controlled-domain.com/clickEvent"});
return;
}
[ผู้ขาย] การตั้งค่าเซิร์ฟเวอร์ KV
ผู้ขายต้องตั้งค่าเซิร์ฟเวอร์ KV ของสัญญาณการให้คะแนนเพื่อให้มีการแมป
จาก URL การแสดงโฆษณาไปยังสัญญาณการให้คะแนนที่เกี่ยวข้อง เช่น
หากผู้ซื้อส่งคืน https:/buyer-domain.com/get-fitness-app
และ
https:/buyer-domain.com/get-fastfood-app
ผู้ขายอาจมีการตอบกลับสัญญาณการให้คะแนนตัวอย่างต่อไปนี้เมื่อ SFE ค้นหาโดยใช้ GET
ใน 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"
]
}
}
ตัวอย่าง [Seller] 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
};
}
ตัวอย่าง [ผู้ขาย] reportResult
function reportResult(auctionConfig, sellerReportingSignals, directFromSellerSignals){
let signalsForWinner = {};
sendReportTo("https://seller-controlled-domain.com");
registerAdBeacon({"clickEvent":
"https://seller-controlled-domain.com/clickEvent"});
return signalsForWinner;
}
แอปตัวอย่าง
เราได้สร้างแอปตัวอย่าง Protected App Signals เพื่อเป็นตัวอย่างวิธีใช้ API ในการสร้างแอปที่ใช้โฟลว์นี้ โดยคุณจะดูแอปตัวอย่างได้ในที่เก็บตัวอย่างนี้