API การนำเสนอ UI รันไทม์ของ SDK

รันไทม์ของ SDK ช่วยให้ SDK โฆษณาทำงานในสภาพแวดล้อมที่มีแซนด์บ็อกซ์ ซึ่งทำให้ไม่สามารถเข้าถึงลำดับชั้นการแสดงผลของผู้เผยแพร่โฆษณาได้ เพื่อแสดงโฆษณา แพลตฟอร์มจะแสดง API SandboxedSdkProvider.getView แก่ SDK เพื่อรับการดูโฆษณา และจัดแพ็กเกจเป็น SurfacePackage เพื่อส่งผ่าน IPC (การสื่อสารระหว่างกระบวนการ) ไปยังแอปพลิเคชันไคลเอ็นต์ กรณีนี้มีการดึงเงินคืนหลายรายการ ซึ่งจะกล่าวถึงด้านล่าง จากนั้นเอกสารนี้จะแสดงไลบรารี Jetpack ที่เสนอ ซึ่งกำลังสร้างขึ้นเพื่อรับมือกับความท้าทายเหล่านี้

ความสำคัญของการเพิ่ม API ของแพลตฟอร์ม

โดย API ของเฟรมเวิร์กออกแบบมาเพื่อความยืดหยุ่น โดยให้ไม่ต้องสร้างช่องทางด้านข้างระหว่างการนำเสนอ UI ไปจนถึงแอปและ SDK ช่องด้านข้างจะทำสิ่งต่อไปนี้

  1. ให้ SDK จัดการการดูโฆษณาหลายครั้งตลอดอายุการใช้งานและทำความเข้าใจสิ่งที่จะเกิดขึ้นกับ UI ของโฆษณาเมื่อ SDK สร้างขึ้น
  2. แยกการสร้างมุมมองและการเชื่อมโยงเนื้อหา การใช้แชแนลด้านข้างจะช่วยให้ SDK สามารถแสดงออบเจ็กต์ที่สอดคล้องกับคำขอโฆษณาไปยังแอป (เนื้อหา) ซึ่งสามารถเชื่อมโยงกับคอนเทนเนอร์โฆษณาได้ทุกเมื่อที่แอปเห็นว่าเหมาะสม
  3. แยกโครงสร้างของแพลตฟอร์มพื้นฐานที่ใช้แสดง UI ในกระบวนการ (แพลตฟอร์มใช้ SurfaceControlViewhost และสร้าง SurfacePackage อยู่)
  4. เปิดใช้ SDK โฆษณาในรันไทม์ของ SDK เพื่อรับการแจ้งเตือนโดยอัตโนมัติเมื่อ UI ของคอนเทนเนอร์โฆษณามีการเปลี่ยนแปลง หากผู้เผยแพร่โฆษณาเปลี่ยนเลย์เอาต์ของคอนเทนเนอร์โฆษณา SDK จะยังคงไม่ทราบถึงการเปลี่ยนแปลงเหล่านี้ เว้นแต่ผู้เผยแพร่โฆษณาจะเรียกใช้ API เพื่อแจ้งให้ทราบอย่างชัดแจ้ง
  5. ซิงค์การปรับขนาด UI โฆษณาและคอนเทนเนอร์โฆษณาโดยไม่รบกวนผู้ใช้
  6. จัดการความเข้ากันได้แบบย้อนหลังโดยอัตโนมัติ SurfacePackage ไม่พร้อมใช้งานก่อน API ระดับ 30 นอกจากนี้ ในอุปกรณ์ที่ไม่มีรันไทม์ของ SDK และผู้เผยแพร่โฆษณาใช้ SDK เอง จึงสร้าง SurfacePackage สำหรับโฆษณาได้ในกรณีที่รับการดูได้จาก SDK โดยตรง แชแนลด้านข้างจะแยกความซับซ้อนนี้ออกจาก SDK และโค้ดของนักพัฒนาแอป
  7. ทำให้ UI ของโฆษณาผสานรวมกับ Composable ได้อย่างราบรื่น นักพัฒนาซอฟต์แวร์ใน Jetpack Compose ที่ไม่ได้ใช้ข้อมูลพร็อพเพอร์ตี้จะยังโฮสต์ UI ที่นักพัฒนา SDK สร้างขึ้น และยังรองรับการดูอยู่ต่อไป

ไลบรารี UI

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

ไลบรารี UI มี 3 รายการ ได้แก่ core, client และ provider ไลบรารีหลักมีอินเทอร์เฟซที่ใช้โดยไลบรารีของไคลเอ็นต์และไลบรารีของผู้ให้บริการ ผู้ให้บริการ UI (โดยทั่วไปคือ SDK) จะขึ้นอยู่กับไลบรารีของผู้ให้บริการ และผู้ใช้ของ UI (โดยทั่วไปคือผู้เผยแพร่โฆษณา) จะขึ้นอยู่กับไลบรารีของไคลเอ็นต์ ไลบรารีของไคลเอ็นต์และผู้ให้บริการจะสร้างช่องทางด้านข้างซึ่งจำเป็นสำหรับการสร้างและรักษาเซสชัน UI ไว้ด้วยกัน

API

API สำหรับการนำเสนอ UI รันไทม์ของ SDK มีดังนี้

SandboxedUiAdapter: สร้างโดย SDK ซึ่งเป็นช่องทางให้ได้รับเนื้อหาเพื่อแสดงใน UI ของผู้เผยแพร่โฆษณา

SandboxedSdkView: คอนเทนเนอร์นี้สร้างขึ้นโดยผู้เผยแพร่โฆษณา ซึ่งใช้เก็บเนื้อหาที่ได้จาก SandboxedUiAdapter

Session: สร้างโดย SDK เพื่อตอบสนองต่อ SandboxedUiAdapter.openSession() แสดงการเรียกใช้ UI 1 เซสชัน การดำเนินการนี้จะสร้างจุดสิ้นสุดของ SDK ของช่องทางการสื่อสารระหว่าง SDK กับผู้เผยแพร่โฆษณา และจะได้รับการแจ้งเตือนเกี่ยวกับการเปลี่ยนแปลงใน SandboxedSdkView เช่น การปลดหน้าต่าง การปรับขนาด หรือการเปลี่ยนแปลงการกำหนดค่า

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

SandboxedSdkUiSessionStateChangedListener: สร้างโดยผู้เผยแพร่โฆษณา ตัวฟังสำหรับการเปลี่ยนแปลงสถานะของเซสชัน UI ที่เชื่อมโยงกับ SandboxedSdkView

ภาพประกอบแสดงความสัมพันธ์ของ API การนำเสนอ UI ของรันไทม์ของ SDK
ความสัมพันธ์ระหว่าง API การนำเสนอ UI รันไทม์ของ SDK

อ่านรายละเอียดเพิ่มเติมเกี่ยวกับ API เหล่านี้ได้ในเอกสารอ้างอิง Privacysandbox-ui

ขั้นตอนการควบคุม

แผนภาพต่อไปนี้แสดงการโต้ตอบระหว่างไลบรารีของไคลเอ็นต์และ UI ของผู้ให้บริการในสถานการณ์ต่างๆ

แผนภาพก่อนหน้าแสดงวิธีที่ผู้เผยแพร่โฆษณาสามารถสร้าง SandboxedSdkView แบบเป็นโปรแกรมหรือผ่าน XML และแนบไว้กับ SdkSandboxUiAdapter ที่ได้จาก SDK ผ่าน API ที่ SDK กำหนด หากต้องการดูการเปลี่ยนแปลงสถานะ UI ทั้งหมด ผู้เผยแพร่โฆษณาควรเพิ่ม SandboxedSdkUiSessionStateChangedListener ลงใน SandboxedSdkView ก่อนแนบ SdkSandboxUiAdapter

ภาพแสดงกระบวนการเซสชันแบบเปิด
รับ UI จาก SDK

แผนภาพนี้แสดงวิธีที่กิจกรรมของผู้เผยแพร่โฆษณาจัดการกับการเปลี่ยนแปลงการกําหนดค่า ไลบรารีของไคลเอ็นต์จะส่งต่อการเปลี่ยนแปลงการกําหนดค่าไปยัง SDK เพื่อให้อัปเดต UI ให้สอดคล้องกันได้ เช่น ขั้นตอนนี้อาจทริกเกอร์ได้เมื่อผู้ใช้หมุนอุปกรณ์ และผู้เผยแพร่โฆษณาประกาศว่ามีการเปลี่ยนแปลงการจัดการการกำหนดค่าในกิจกรรมด้วยการตั้งค่า android:configChanges=["orientation"]

การเปลี่ยนแปลง UI ที่ผู้เผยแพร่โฆษณาเป็นผู้เริ่ม

แผนภาพนี้แสดงให้เห็นว่า SDK จะขอการเปลี่ยนแปลงในคอนเทนเนอร์โฆษณาโดยใช้เมธอดใน SessionClient ได้อย่างไร ระบบจะทริกเกอร์ API นี้เมื่อ SDK ต้องการปรับขนาดโฆษณา และต้องการให้ผู้เผยแพร่โฆษณาปรับขนาดคอนเทนเนอร์โฆษณาให้เหมาะสมกับมิติข้อมูลใหม่ กรณีนี้อาจเกิดขึ้นเพื่อตอบสนองต่อการโต้ตอบของผู้ใช้ เช่น mraid.resize()

การเปลี่ยนแปลง UI ที่เริ่มต้นโดย SDK

แผนภาพนี้แสดงวิธีปิดเซสชันเมื่อถอด SandboxedSdkView ออกจากหน้าต่าง SDK นี้อาจปิดเซสชันได้ทุกเมื่อ (เช่น เมื่อผู้ใช้ขาดการเชื่อมต่อเครือข่าย) โดยเรียกใช้ SessionClient.onSessionError()

การปิดเซสชัน UI

ลำดับ Z

ไลบรารี UI ของไคลเอ็นต์ใช้ SurfaceView เป็นการภายในเพื่อโฮสต์ UI ของ SDK SurfaceView สามารถใช้ลำดับ Z เพื่อแสดง UI ที่ด้านบนของหน้าต่างของผู้เผยแพร่โฆษณาหรือด้านล่างก็ได้ รายการนี้ควบคุมโดยเมธอด SandboxedSdkView.orderProviderUiAboveClientUi() ซึ่งยอมรับบูลีน setOnTop

เมื่อsetOnTopคือtrue ระบบจะส่งทุกๆ android.view.MotionEvent ใน SandboxedSdkView ไปยัง SDK เมื่อ false ระบบจะส่งข้อมูลเหล่านี้ให้ผู้เผยแพร่โฆษณา โดยค่าเริ่มต้น ระบบจะส่งเหตุการณ์การเคลื่อนไหวไปยัง SDK

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

การเลื่อน

เมื่อ UI ของโฆษณาเรียงลำดับแบบ Z เหนือหน้าต่างผู้เผยแพร่โฆษณา ระบบจะส่ง MotionEvents จาก UI ของโฆษณาไปยัง SDK ท่าทางสัมผัสการเลื่อนที่เริ่มต้นใน UI ของโฆษณาจะได้รับการดูแลเป็นพิเศษ ดังนี้

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

คู่มือการติดตั้ง

SDK ควรใช้สิ่งต่อไปนี้

  • SandboxedUiAdapter: ระบบจะส่งข้อมูลนี้คืนให้ผู้เผยแพร่โฆษณาเพื่อตอบสนองต่อ API ที่ SDK กำหนด เช่น loadAd คุณควรใช้วิธีการ openSession() ของการติดตั้งใช้งานนี้เพื่อสร้างคําขอโฆษณาไปยังเซิร์ฟเวอร์ของ SDK และเตรียมการดูโฆษณาสําหรับคําขอนั้น
  • Session**: จะแสดงผลเป็นการตอบกลับการเรียก SandboxedUiAdapter.openSession ช่วยให้ไลบรารีไคลเอ็นต์รับ UI ของโฆษณาและแจ้ง SDK เกี่ยวกับการเปลี่ยนแปลงใน API นี้ ควรใช้เมธอด Session ทั้งหมดที่นี่

ผู้เผยแพร่โฆษณาควรดำเนินการดังนี้

  1. สร้าง SandboxedSdkView ผ่าน XML หรือแบบเป็นโปรแกรม
  2. แนบ SandboxedSdkUiSessionStateChangedListener เข้ากับ SandboxedSdkView เพื่อสังเกตการเปลี่ยนแปลงใน UI
  3. แนบ SDK ที่ให้ไว้ SandboxedUiAdapter ไปยัง SandboxedSdkView
  4. เพิ่ม SandboxedSdkView ลงในหน้าต่างตามปกติและปล่อยให้ไลบรารีของไคลเอ็นต์ดูแลการสร้างและรักษาเซสชัน UI ด้วย SDK
  5. โปรดตอบสนองต่อการเปลี่ยนแปลงสถานะที่รายงานโดย SandboxedSdkUiSessionChangedListener ในเวลาที่เหมาะสม เช่น หาก SDK ปิดเซสชันโดยไม่คาดคิด ผู้เผยแพร่โฆษณาสามารถแทนที่ SandboxedSdkView ด้วยภาพนิ่งหรือนำภาพนิ่งออกจากลำดับชั้นการแสดงผลได้
  6. เมื่อทำการเปลี่ยนที่อาจบดบัง UI ของโฆษณา เช่น เมนูแบบเลื่อนลง ให้ตั้ง orderProviderUiAboveClientUi เป็น "เท็จ" ชั่วคราวเพื่อจัดวาง UI โฆษณาไว้ใต้หน้าต่างของผู้เผยแพร่โฆษณา เมื่อปิดเมนูแบบเลื่อนลงแล้ว ให้โทรหา orderProviderUiAboveClientUi ที่ true

อนาคตของ API ของแพลตฟอร์ม

เมื่อไลบรารี UI เข้าสู่เวอร์ชันเบต้าแล้ว เรามีแผนที่จะเลิกใช้งาน API ของแพลตฟอร์มรันไทม์ SDK ที่เกี่ยวข้องกับการนำเสนอ UI ซึ่งได้แก่ SdkSandboxManager.requestSurfacePackage() และ SandbxedSdkProvider.getView()

คำถามปลายเปิด

  1. มีกรณีการใช้งาน UI โฆษณาที่พบบ่อยที่ไลบรารี UI ควรจัดการโดยอัตโนมัติหรือไม่
  2. คุณใช้เฟรมเวิร์ก UI ใดในการแสดง UI ของโฆษณา คุณคาดว่าจะมีปัญหาในการผสานรวมไลบรารี UI กับเฟรมเวิร์กเหล่านี้ไหม
  3. UI โฆษณาที่เลื่อนได้วางไว้ในคอนเทนเนอร์ของผู้เผยแพร่โฆษณาแบบเลื่อนได้เป็นกรณีการใช้งานทั่วไปสำหรับคุณหรือไม่ ทิศทางการเลื่อนสำหรับ UI โฆษณาและคอนเทนเนอร์ในกรณีนี้คืออะไร คุณคาดหวังพฤติกรรมใดเมื่อผู้ใช้เริ่มเลื่อนบน UI โฆษณา