คู่มือนักพัฒนาซอฟต์แวร์สำหรับสัญญาณแอปที่มีการป้องกัน

เพื่อช่วยให้นักพัฒนาแอปเริ่มทดลองใช้ Protected App Signals API เอกสารนี้จะอธิบาย API ทั้งหมดภายในแพลตฟอร์ม API, รายละเอียดวิธีการ ตั้งค่าสภาพแวดล้อมการทดสอบ และแสดงตัวอย่างของการกำหนดค่าและ สคริปต์

หมายเหตุ: สัญญาณแอปที่มีการป้องกันต้องใช้เซิร์ฟเวอร์การประมูลและการเสนอราคาที่ใช้งานได้ ในการใช้งาน คุณต้องทําตามขั้นตอนเพื่อติดตั้งใช้งานการเสนอราคาและการประมูล AWS หรือ Google Cloud

ประวัติเวอร์ชัน

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 ซึ่งประกอบด้วย
  • อัปเดต Signals API
  • API การเข้ารหัสสัญญาณ
  • API การสนับสนุนการประมูลที่ได้รับการป้องกัน: SDK จะใช้ในการเรียกใช้การป้องกัน การประมูลในเซิร์ฟเวอร์การเสนอราคาและการประมูล (B&A) ที่ใช้แอปที่มีการป้องกัน สัญญาณ
• API ฝั่งเซิร์ฟเวอร์:
  • API การประมูลที่มีการป้องกัน: ชุดสคริปต์ JS ที่ทำงานในการเสนอราคาและ เซิร์ฟเวอร์การประมูล API นี้ช่วยให้ผู้ขายและผู้ซื้อสามารถเขียนตรรกะ ใช้การประมูลที่ได้รับการคุ้มครอง
  • Ad Retrieval API: รับผิดชอบในการระบุรายการโฆษณาที่เสนอตัวเลือก ข้อมูลบริบทและข้อมูลผู้ใช้ที่พร้อมใช้ในการเสนอราคาของผู้ซื้อ เซิร์ฟเวอร์

ไคลเอ็นต์ Android

ในฝั่งไคลเอ็นต์ แพลตฟอร์มสัญญาณแอปที่มีการป้องกันประกอบด้วย API ต่างๆ ได้แก่

• อัปเดตสัญญาณ: Android System API เพื่อเปิดใช้การดูแลจัดการสัญญาณใน อุปกรณ์
• การเข้ารหัสสัญญาณ: JavaScript API สำหรับเตรียมสัญญาณที่จะส่งไปยัง เซิร์ฟเวอร์ในระหว่างการประมูล
• การสนับสนุนการประมูลที่มีการคุ้มครอง: API ที่สนับสนุนการดำเนินการของ การประมูลในเซิร์ฟเวอร์การเสนอราคาและการประมูล API นี้ไม่ได้เฉพาะเจาะจงสำหรับ สัญญาณแอปที่มีการป้องกันและยังใช้เพื่อสนับสนุนการประมูลสำหรับ Audience API

หมายเหตุ: ขณะทดสอบกับสัญญาณของแอปที่มีการป้องกันในตัวอย่างสำหรับนักพัฒนาแอป แนะนำให้คุณใช้โปรแกรมจำลอง เพราะมีหลายสถานการณ์ใน ซึ่งวิธีที่ดีที่สุดในการแก้ปัญหาในการตั้งค่าก็คือการล้างข้อมูลอุปกรณ์

อัปเดต 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 ต้องตรงกับคำสั่ง 1 ใน 5 ข้อต่อไปนี้

คีย์	คำอธิบาย
put	เพิ่มสัญญาณใหม่ โดยเขียนทับสัญญาณที่มีอยู่ด้วยคีย์เดียวกัน ค่า นี่เป็นออบเจ็กต์ JSON ซึ่งมีคีย์เป็นสตริงฐาน 64 ที่สอดคล้องกับคีย์ที่จะใส่ และค่าจะเป็นสตริงฐาน 64 ที่สอดคล้องกับค่าที่จะใส่
append	เพิ่มสัญญาณ/สัญญาณใหม่ต่อท้ายอนุกรมเวลาของสัญญาณ โดยนำสัญญาณที่เก่าที่สุดออก เพื่อเพิ่มพื้นที่ว่างสำหรับรายการใหม่ ถ้าขนาดของชุดหนังสือเกินขนาดสูงสุดที่กำหนด ค่าสำหรับกรณีนี้เป็นออบเจ็กต์ JSON ซึ่งมีคีย์เป็นสตริงฐาน 64 ที่สอดคล้องกับคีย์ที่จะต่อท้าย และค่าเป็นออบเจ็กต์ที่มี 2 ช่อง: "values" และ "maxSignals" "values": รายการสตริงฐาน 64 สตริงที่ตรงกับค่าสัญญาณที่จะต่อท้ายอนุกรมเวลา "maxSignals": จำนวนค่าสูงสุดที่ใช้ได้ในอนุกรมเวลานี้ หาก จำนวนสัญญาณปัจจุบันที่เชื่อมโยงกับคีย์เกิน maxSignals สัญญาณที่เก่าที่สุดจะถูกนำออก โปรดทราบว่าคุณสามารถเพิ่มคีย์ที่เพิ่มด้วยคำว่า "put" ได้ โปรดทราบว่าการเพิ่มค่ามากกว่าจำนวนสูงสุดจะทำให้ดำเนินการไม่สำเร็จ
put_if_not_present	เพิ่มสัญญาณใหม่เฉพาะกรณีที่ไม่มีสัญญาณที่มีคีย์เดียวกันอยู่แล้ว ค่าสำหรับกรณีนี้เป็นออบเจ็กต์ JSON ซึ่งคีย์เป็นสตริงฐาน 64 ที่สอดคล้องกับคีย์ที่จะใส่ และค่าจะเป็นสตริงฐาน 64 ที่สอดคล้องกับค่าที่จะใส่
remove	นำสัญญาณของคีย์ออก ค่าของสตริงนี้คือรายการสตริงฐาน 64 ที่ตรงกับคีย์สัญญาณที่ควรลบ
update_encoder	มีการดำเนินการเพื่ออัปเดตปลายทางและ URI ที่สามารถใช้ได้ เพื่อเรียกตรรกะการเข้ารหัส คีย์ย่อยสำหรับระบุการดำเนินการอัปเดตคือ "action" และ ค่าที่รองรับในขณะนี้คือ "REGISTER" เท่านั้น ซึ่งจะลงทะเบียนอุปกรณ์ปลายทางของโปรแกรมเปลี่ยนไฟล์หากมีการให้เป็นครั้งแรก หรือเขียนทับอุปกรณ์ที่มีอยู่ด้วยอุปกรณ์ปลายทางที่ระบุใหม่ ต้องระบุปลายทางสำหรับ "REGISTER" action คีย์ย่อยสำหรับการระบุปลายทางโปรแกรมเปลี่ยนไฟล์คือ "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 กระบวนการปลดออก จะทำให้ใช้งานเกินโควต้าเล็กน้อยในช่วงเวลาสั้นๆ ใน เพื่อลดความถี่ในการปลดออก

API การเข้ารหัสสัญญาณ

ผู้ซื้อจะต้องให้ฟังก์ชันของ Java Script ที่จะใช้ในการเข้ารหัส สัญญาณที่จัดเก็บไว้ในอุปกรณ์ซึ่งจะส่งไปยังเซิร์ฟเวอร์ในระหว่างการป้องกัน การประมูล ผู้ซื้อสามารถระบุสคริปต์นี้โดยเพิ่ม 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 ไปยังรายการออบเจ็กต์สัญญาณแอปที่มีการป้องกัน ออบเจ็กต์สัญญาณแอปที่มีการป้องกันแต่ละรายการมี 3 ฟิลด์ ดังนี้

• signal_value: UInt8Array ที่แทนค่าของสัญญาณ
• creation_time: ตัวเลขที่แสดงเวลาที่สร้างสัญญาณใน Epoch ในหน่วยวินาที
• package_name: สตริงที่มีชื่อแพ็กเกจที่สร้างขึ้น สัญญาณ

พารามิเตอร์ maxSize คือตัวเลขที่อธิบายขนาดอาร์เรย์ที่ใหญ่ที่สุดที่อนุญาต สำหรับเอาต์พุต

ฟังก์ชันควรเอาต์พุตออบเจ็กต์ที่มี 2 ช่องดังนี้

• status: ควรเป็น 0 หากสคริปต์ทำงานสำเร็จ
• results: ควรเป็นอาร์เรย์ UInt8A ที่มีความยาวน้อยกว่าหรือเท่ากับ maxSize อาร์เรย์นี้จะถูกส่งไปยังเซิร์ฟเวอร์ในระหว่างการประมูล และจะถูกจัดเตรียมโดย สคริปต์ prepareDataForAdRetrieval

การเข้ารหัสจะทำให้เทคโนโลยีโฆษณามีขั้นตอนเริ่มต้นของวิศวกรรมฟีเจอร์ ซึ่งสามารถเปลี่ยนรูปแบบ เช่น บีบอัดสัญญาณดิบลงใน เวอร์ชันที่เชื่อมต่อตามตรรกะที่กำหนดเอง โปรดทราบว่าในระหว่าง การประมูลที่มีการป้องกันซึ่งทำงานอยู่ในสภาพแวดล้อมการดำเนินการที่เชื่อถือได้ (TEE) และเทคโนโลยีโฆษณา ตรรกะที่กำหนดเองจะมีสิทธิ์อ่านเพย์โหลดสัญญาณที่สร้างโดย การเข้ารหัส ตรรกะที่กำหนดเอง ซึ่งเรียกว่า ฟังก์ชันที่กำหนดโดยผู้ใช้ (UDF) ที่ทำงานใน B&A TEE ของผู้ซื้อ จะมีสิทธิ์อ่านสัญญาณที่เข้ารหัสและสัญญาณบริบทอื่นๆ จากแอปของผู้เผยแพร่โฆษณาให้เลือกโฆษณา (ดึงข้อมูลโฆษณาและ สูงสุด)

การเข้ารหัสสัญญาณ

ทุกๆ ชั่วโมง ผู้ซื้อที่ได้ระบุตรรกะการเข้ารหัสไว้กับโปรแกรมการลงทะเบียน จะมีการเข้ารหัสสัญญาณของสัญญาณเหล่านั้นเป็นเพย์โหลดการประมูล อาร์เรย์สำหรับเพย์โหลดการประมูลจะยังคงอยู่ในอุปกรณ์ และมีการเข้ารหัสและ จะถูกขายโดยผู้ขายเป็นส่วนหนึ่งของข้อมูลการเลือกโฆษณา ของการประมูลที่มีการคุ้มครอง สำหรับการทดสอบ คุณสามารถเรียกใช้การเข้ารหัสนี้นอก เซสชันรายชั่วโมงโดยใช้คำสั่งต่อไปนี้

adb shell cmd jobscheduler run -f com.google.android.adservices.api 29

การกำหนดเวอร์ชันลอจิกของโปรแกรมเปลี่ยนไฟล์

เมื่อมีการขอให้ดาวน์โหลดตรรกะโปรแกรมเปลี่ยนไฟล์ที่กำหนดเองสำหรับเทคโนโลยีโฆษณา เทคโนโลยีโฆษณา ปลายทางตอบกลับด้วยหมายเลขเวอร์ชันในส่วนหัวการตอบกลับได้ เวอร์ชันนี้ จะคงอยู่ร่วมกับตรรกะโปรแกรมเปลี่ยนไฟล์บนอุปกรณ์ เมื่อสัญญาณดิบ มีการเข้ารหัส เพย์โหลดที่เข้ารหัสจะยังคงอยู่พร้อมกับเวอร์ชันที่ใช้สำหรับ การเข้ารหัส เวอร์ชันนี้ถูกส่งไปยังเซิร์ฟเวอร์ B&A ด้วยในระหว่างที่ใช้ Protected การประมูล เพื่อให้เทคโนโลยีโฆษณาปรับตรรกะการเสนอราคาและการเข้ารหัสที่สอดคล้องกัน โดยอิงตาม เวอร์ชัน

Response header for providing encoder version : X_ENCODER_VERSION

API การสนับสนุนการประมูลที่มีการป้องกัน

ในฝั่งอุปกรณ์ การเรียกใช้การประมูลสำหรับสัญญาณของแอปที่มีการป้องกันคือ เหมือนกับการประมูลสำหรับกลุ่มเป้าหมายที่ได้รับการคุ้มครอง

บริการเสนอราคาและประมูล

API ฝั่งเซิร์ฟเวอร์ประกอบด้วย

• Protected Sandbox API: ชุดฟังก์ชัน JS หรือ UDF ที่ผู้ซื้อและผู้ขายสามารถนําไปติดตั้งใช้งานในองค์ประกอบ B&A ที่ตนเองเป็นเจ้าของเพื่อกำหนดการเสนอราคาและตรรกะของการประมูล
• API การดึงข้อมูลโฆษณา: ผู้ซื้อสามารถใช้ API นี้โดยการติดตั้งใช้งานปลายทาง REST ซึ่งจะรับผิดชอบในการจัดหาชุดโฆษณาที่ต้องการสำหรับการประมูลสัญญาณแอปที่มีการป้องกัน

API การประมูลที่มีการป้องกัน

Protected Sandbox API ประกอบด้วย JS API หรือ UDF ที่ผู้ซื้อและผู้ขายสามารถ เพื่อนำตรรกะการประมูลและการเสนอราคามาใช้

UDF เทคโนโลยีโฆษณาของผู้ซื้อ

UDF เตรียมข้อมูลสำหรับการดึงโฆษณา

ก่อนที่จะใช้สัญญาณแอปที่มีการป้องกันเพื่อดึงข้อมูลตัวเลือกโฆษณาจาก 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 adtech.
function prepareDataForAdRetrieval(encodedOnDeviceSignals,encodedOnDeviceSignalsVersion,sellerAuctionSignals,contextualSignals) {
   return {};
}

UDF สร้างการเสนอราคา

หลังจากส่งโฆษณาผู้สมัครอันดับสูงสุด 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)

UDF รายงาน Win

เมื่อการประมูลจบลง บริการการประมูลจะสร้าง URL การรายงานสำหรับ ผู้ซื้อและลงทะเบียนบีคอนโดยใช้ reportWin UDF (คือ reportWin ที่ใช้สำหรับ Protected Audience) อุปกรณ์จะใช้คำสั่ง ping นี้เมื่อลูกค้าแสดงโฆษณาแล้ว ลายเซ็นของวิธีการนี้เกือบเหมือนกันกับ Protected Audience version ยกเว้นพารามิเตอร์พิเศษ 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 รายงานผล

UDF นี้ช่วยให้ผู้ขาย (ในท้ายที่สุด) ดำเนินการระดับเหตุการณ์ พร้อมข้อมูลเกี่ยวกับโฆษณาที่ชนะการประมูล

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

API การดึงข้อมูลโฆษณา

ในรุ่น MVP บริการเรียกดูโฆษณาจะเป็นที่ผู้ซื้อจัดการและโฮสต์ไว้ และบริการเสนอราคาจะเรียกตัวเลือกโฆษณาจากบริการนี้ ตั้งแต่เดือนเมษายน 2024 เป็นต้นไป เซิร์ฟเวอร์สำหรับดึงข้อมูลโฆษณาจะต้องทำงานในไฟล์ สภาพแวดล้อมการดำเนินการ (TEE) และจะแสดงอินเทอร์เฟซ GRPC/โปรโต เทคโนโลยีโฆษณา บริษัทต้องตั้งค่าเซิร์ฟเวอร์นี้และระบุ URL ของเซิร์ฟเวอร์เป็นส่วนหนึ่งของ B&A การติดตั้งใช้งานสแต็ก การใช้งานบริการนี้ใน TEE มีอยู่ใน Privacy Sandbox GitHub และในส่วนอื่นๆ ซึ่งเป็นเอกสารที่เราสันนิษฐานว่าข้อมูลนี้เป็นโค้ดที่ใช้ในการทำให้ใช้งานได้

ตั้งแต่เดือนเมษายน 2024 เป็นต้นไป เวอร์ชัน B&A จะรองรับโฆษณาเส้นทางตามบริบท การดึงข้อมูล ในกรณีนี้ เซิร์ฟเวอร์การเสนอราคาจะได้รับรายการ ad-identifier ที่ส่งโดยเซิร์ฟเวอร์ RTB ระหว่างบริบทของการประมูล ระบบจะส่งตัวระบุไปยังเซิร์ฟเวอร์ TEE KV เพื่อดึงข้อมูลโฆษณาทั้งหมด ข้อมูลที่เกี่ยวข้องที่จะใช้ในระยะการเสนอราคา (ตัวอย่างเช่น URL การแสดงโฆษณา ข้อมูลเมตา และการฝังโฆษณาที่จะใช้ใน ตำแหน่งบนสุด) เส้นทางที่สองนี้ไม่จำเป็นต้องมีตรรกะเฉพาะใดๆ ที่ทำให้ใช้งานได้ ดังนั้นเราจะบันทึกเฉพาะวิธีกำหนดค่า TEE ตาม สำหรับใช้ดึงโฆษณา

UDF ของ HandleRequest

function HandleRequest(requestMetadata, preparedDataForAdRetrieval,
                      deviceMetadata, contextualSignals) {
    return adsMetadataString;
}

สถานที่:

• requestMetadata: JSON ข้อมูลเมตาเซิร์ฟเวอร์แบบส่งคำขอไปยัง UDF เว้นว่างไว้
• preparedDataForAdRetrieval: เนื้อหาของช่องนี้ขึ้นอยู่กับโฆษณา สำหรับการดึงข้อมูล ในกรณีที่มี การเรียกโฆษณาตามบริบท พารามิเตอร์นี้ จะมีสัญญาณดิบที่มีต้นทางมาจากอุปกรณ์ และส่งผ่านจาก บริการเสนอราคา ในกรณีที่มีการดึงโฆษณา TEE โดยใช้เซิร์ฟเวอร์การดึงข้อมูลโฆษณา พารามิเตอร์นี้จะมีผลลัพธ์ของ prepareDataForAdRetrieval UDF หมายเหตุ: ในขั้นตอนนี้ ระบบจะถอดรหัสสัญญาณแอปที่มีการป้องกันและไม่เข้ารหัส
• deviceMetadata: ออบเจ็กต์ JSON ที่มีข้อมูลเมตาของอุปกรณ์ที่ส่งต่อโดยบริการโฆษณาของผู้ขาย ดูรายละเอียดเพิ่มเติมในเอกสารประกอบของ B&A
  • X-Accept-Language: ภาษาที่ใช้ในอุปกรณ์
  • X-User-Agent: User Agent ที่ใช้ในอุปกรณ์
  • X-BnA-Client-IP: ที่อยู่ IP ของอุปกรณ์
• contextualSignals: สตริงที่กำหนดเองที่มาจากการเสนอราคาตามบริบท ที่ดำเนินการโดย DSP เดียวกัน UDF จะสามารถถอดรหัส สตริงเพื่อใช้งาน สัญญาณบริบทอาจมีข้อมูลใดๆ เช่น ML ข้อมูลเวอร์ชันโมเดลสำหรับการฝังที่มีการป้องกันที่ส่งผ่านโดยใช้ สัญญาณแอปที่มีการป้องกัน

UDF ควรแสดงผลสตริงเมื่อสำเร็จ ระบบจะส่งสตริงกลับไปยัง ซึ่งจะส่งไปยัง UDF ของ generateBid แม้ว่า สตริงนี้อาจเป็นสตริงธรรมดา ส่วนใหญ่ก็น่าจะเป็นสตริง ออบเจ็กต์แบบอนุกรมซึ่งมีสคีมาที่กำหนดโดยเทคโนโลยีโฆษณาแต่ละรายการด้วยตัวเอง ไม่มีข้อจำกัดในสคีมาตราบใดที่generateBidของเทคโนโลยีโฆษณา จะรับรู้และใช้สตริงนั้นได้

ตั้งค่าระบบสำหรับการพัฒนา

Android

หากต้องการตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์ Android คุณต้องทำดังนี้

1. สร้างโปรแกรมจำลอง (แนะนำ) หรืออุปกรณ์จริงที่เรียกใช้อิมเมจของ Developer Preview 10
2. เรียกใช้โค้ดต่อไปนี้

adb shell am start -n com.google.android.adservices.api/com.android.adservices.ui.settings.activities.AdServicesSettingsMainActivity

จากนั้นเลือกตัวเลือกที่แสดงเพื่อให้ความยินยอมต่อโฆษณาที่แอปแนะนำ

1. เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดใช้ 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;

1. รีสตาร์ทอุปกรณ์
2. ลบล้างคีย์การประมูลของอุปกรณ์ให้ชี้ไปยังเซิร์ฟเวอร์คีย์การประมูล คุณควรเรียกใช้ขั้นตอนนี้ก่อนที่จะพยายามเรียกใช้การประมูลเพื่อป้องกันไม่ให้ระบบแคชคีย์ที่ไม่ถูกต้อง

การเสนอราคาและ บริการประมูล

หากต้องการตั้งค่าเซิร์ฟเวอร์ B&A โปรดดู เอกสารการตั้งค่าแบบบริการตนเอง

เอกสารนี้จะเน้นวิธีกำหนดค่าเซิร์ฟเวอร์เฉพาะผู้ซื้อ เนื่องจาก ไม่มีการเปลี่ยนแปลงใดๆ สำหรับผู้ขาย

ข้อกำหนดเบื้องต้น

ก่อนทำให้สแต็กบริการ B&A ใช้งานได้ เทคโนโลยีโฆษณาของผู้ซื้อจะต้องดำเนินการต่อไปนี้

• ตรวจสอบว่าลูกค้าได้ใช้บริการดึงโฆษณา TEE ของตนเอง (ดู หัวข้อที่เกี่ยวข้อง)
• ตรวจสอบว่าเทคโนโลยีโฆษณามี UDF ที่จำเป็นทั้งหมด (prepareDataForAdRetrieval, generateBid, reportWin, HandleRequest) ที่กำหนดไว้และโฮสต์

ความเข้าใจเกี่ยวกับวิธีการทํางานของการประมูลที่ใช้ 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"

การกำหนดค่าเทคโนโลยีโฆษณาของผู้ขาย

เมื่อใช้ไฟล์สาธิตนี้เป็นตัวอย่าง ผู้ขายจะต้องตั้งค่า ตามแฟล็กนั้นๆ (หมายเหตุ: ระบบจะไฮไลต์เฉพาะการกำหนดค่าที่เกี่ยวข้องกับสัญญาณแอปที่มีการป้องกันเท่านั้น ที่นี่) เทคโนโลยีโฆษณาจะต้องแทนที่ 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 ของ HandleRequest ตรรกะการดึงข้อมูล ดูรายละเอียดเพิ่มเติมที่เซิร์ฟเวอร์ KV คู่มือการเริ่มต้นใช้งาน โปรดทราบว่า B&A คาดหวังว่าทั้ง 2 บริการ ใช้งานในโครงข่ายบริการเดียวกันกับบริการการเสนอราคา

ตัวอย่างการตั้งค่า

พิจารณาสถานการณ์ต่อไปนี้: การใช้ 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 ของ [Buyer]

เข้ารหัสแต่ละสัญญาณเป็น 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, 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;
}

[ผู้ซื้อ] ตัวอย่าง UDF การเรียกโฆษณา

ในตัวอย่างของเรา เซิร์ฟเวอร์ดึงโฆษณาจะส่งข้อมูลเมตา (เช่น รหัสสำหรับโฆษณาแต่ละรายการใน ตัวอย่างนี้แต่สามารถมีข้อมูลอื่นๆ สำหรับแต่ละรายการที่อาจมีประโยชน์ สร้างราคาเสนอในภายหลัง) สำหรับตัวเลือกโฆษณา k ยอดนิยมแต่ละรายการ

function HandleRequest(requestMetadata, protectedSignals, deviceMetadata,
                      contextualSignals) {
 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 ของ reportWin รายงานให้ผู้ซื้อทราบว่าชนะการประมูลแล้ว

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"
      ]
   }
}

[ผู้ขาย] ตัวอย่าง 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
  };
}

[ผู้ขาย] ตัวอย่าง reportผลลัพธ์

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

แอปตัวอย่าง

ตัวอย่างวิธีการใช้ API เพื่อสร้างแอปที่ใช้ ตามที่อธิบายไว้ข้างต้น เราได้สร้างแอปตัวอย่างสัญญาณแอปที่มีการป้องกันซึ่ง สามารถดูได้ในที่เก็บตัวอย่างนี้