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

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

เหตุผลในการเพิ่ม API ของแพลตฟอร์ม

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

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

ไลบรารี UI

ไลบรารี UI จะซ่อนความซับซ้อนที่อธิบายไว้ข้างต้น และจัดเตรียม ช่องทางด้านข้างที่ผู้เผยแพร่โฆษณาและ SDK สามารถใช้เพื่อแสดง UI ในกระบวนการต่างๆ และ อัปเดต 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 รายการเดียว ซึ่งจะเป็นส่วนปลายทางของ SDK ในช่องทางการสื่อสารระหว่าง SDK กับผู้เผยแพร่โฆษณา และ รับการแจ้งเตือนเกี่ยวกับการเปลี่ยนแปลงใน SandboxedSdkView เช่น การแยกหน้าต่าง การปรับขนาด หรือการเปลี่ยนแปลงการกำหนดค่า

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

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

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

ควบคุมโฟลว์

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

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

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

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

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

ลำดับ Z

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

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

โดยปกติแล้วผู้เผยแพร่โฆษณาไม่จำเป็นต้องเปลี่ยนลำดับ Z เริ่มต้นของมุมมองโฆษณา อย่างไรก็ตาม เมื่อแสดง UI ที่ครอบคลุมโฆษณา เช่น เมนูแบบเลื่อนลง คุณควรเปลี่ยนลำดับ Z จากค่าเริ่มต้นชั่วคราว แล้วคืนค่าเมื่อ องค์ประกอบ 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 เป็น false ชั่วคราวเพื่อวางตำแหน่ง UI โฆษณา ใต้หน้าต่างของผู้เผยแพร่โฆษณา เมื่อปิดเมนูแบบเลื่อนลงแล้ว ให้โทรหา orderProviderUiAboveClientUi ถึง true

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

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

คำถามเปิด

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