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

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

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

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

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

การเลื่อน

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