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

bookmark_border จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

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

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

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

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

ไลบรารี UI

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

ไลบรารี UI มี 3 ประเภท ได้แก่ หลัก ไคลเอ็นต์ และ ผู้ให้บริการ ไลบรารีหลักมีอินเทอร์เฟซที่ไลบรารีของไคลเอ็นต์และผู้ให้บริการใช้ ผู้ให้บริการ 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 เหล่านี้ได้ในเอกสารประกอบข้อมูลอ้างอิงของ privacysandbox-ui

ควบคุมโฟลว์

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

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

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

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