ממשקי API להצגת ממשק משתמש בזמן ריצה של SDK

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

זמן הריצה ל-SDK מאפשר להריץ ערכות SDK להצגת מודעות בסביבת ארגז חול, וכך למנוע מהן גישה להיררכיית התצוגה של בעלי האפליקציות. כדי להציג מודעות, הפלטפורמה חושפת ממשק API מסוג SandboxedSdkProvider.getView ל-SDK כדי לקבל תצוגת מודעה, ומארזת אותה כ-SurfacePackage כדי לשלוח אותה דרך IPC (תקשורת בין תהליכים) לאפליקציית הלקוח. יש לכך כמה חסרונות, שמפורטים בהמשך. לאחר מכן נסביר על ספריית Jetpack שאנחנו מפתחים כדי להתמודד עם האתגרים האלה.

הסיבה להוספת ממשקי ה-API של הפלטפורמה

ממשקי ה-API של המסגרת נועדו לספק גמישות, והם משאירים את המשימה של בניית ערוץ צדדי להצגת ממשק המשתמש לאפליקציה ול-SDK. הערוץ המשני הזה מבצע את הפעולות הבאות:

1. מאפשרת ל-SDK לנהל כמה תצוגות של מודעות במהלך מחזור החיים שלהן ולהבין מה קורה לממשק המשתמש של המודעה אחרי שהוא נוצר על ידי ה-SDK.
2. מפריד בין יצירת תצוגה לבין קישור התוכן. השימוש בערוץ הצדדי מאפשר ל-SDK להחזיר לאפליקציה אובייקט שתואם לבקשת המודעה (התוכן), שאפשר לקשר לקונטיינר המודעות בכל שלב שהאפליקציה תמצא לנכון.
3. יצירת אבסוקציה של המבנים הבסיסיים של הפלטפורמה שמשמשים להצגת ממשק המשתמש בתהליכים שונים. (הפלטפורמה משתמשת כרגע ב-SurfaceControlViewhost ומפיקה ממנו SurfacePackage).
4. מאפשרת ל-SDK להצגת מודעות בסביבת זמן הריצה של ה-SDK לקבל התראות באופן אוטומטי כשממשק המשתמש של מאגר המודעות משתנה. אם בעל תוכן דיגיטלי משנה את הפריסה של מאגר המודעות, ה-SDK לא יהיה מודע לשינויים האלה, אלא אם בעל התוכן הדיגיטלי יפעיל באופן מפורש ממשק API כדי להודיע על כך.
5. סנכרון של שינוי הגודל של ממשק המשתמש של המודעה ושל מאגר המודעות, בלי שינויים גלויים למשתמש.
6. ניהול אוטומטי של תאימות לאחור. SurfacePackage לא זמין לפני רמת API 30. בנוסף, במכשירים שבהם אין זמן ריצה ל-SDK ו-SDK הוא תהליך מקומי לבעלי האפליקציה, לא כדאי ליצור SurfacePackage למודעה כשאפשר לקבל צפייה ישירות מ-SDK. הערוץ הצדדי מסיר את המורכבות הזו מה-SDK ומקוד מפתחי האפליקציה.
7. מאפשרת לממשק המשתמש של המודעות להשתלב בצורה חלקה עם נכסי Composables. מפתחי Jetpack Compose שלא עובדים עם תצוגות יכולים גם להמשיך לארח ממשק משתמש שנוצר על ידי מפתח ה-SDK שעדיין עובד עם תצוגות.

ספריות UI

ספריות ממשק המשתמש מסננות את המורכבות שמפורטת למעלה ומספקות את הערוץ הצדדי שבו בעל התוכן הדיגיטלי ו-SDK יכולים להשתמש כדי להציג את ממשק המשתמש בתהליכים שונים, ולעדכן אותו כשהמשתמש מבצע איתו אינטראקציה ועם המכשיר.

יש שלוש ספריות של ממשק משתמש: core,‏ client ו-provider. ספריית הליבה מספקת את הממשקים שבהם משתמשות ספריות הלקוח והספק. ספק ממשק המשתמש (בדרך כלל ה-SDK) תלוי בספריית הספק, והצרכן של ממשק המשתמש (בדרך כלל בעל התוכן הדיגיטלי) תלוי בספריית הלקוח. יחד, ספריות הלקוח והספק יוצרות את הערוץ הצדדי שנחוץ ליצירה ולתחזוקה של סשן של ממשק משתמש.

ממשקי ה-API

ממשקי ה-API להצגת ממשק המשתמש של SDK Runtime הם:

SandboxedUiAdapter: נוצר על ידי ה-SDK ומספק דרך לקבל תוכן שיוצג בממשק המשתמש של בעל האפליקציה.

SandboxedSdkView: קונטיינר שנוצר על ידי בעל התוכן הדיגיטלי, שמכיל תוכן שהתקבל דרך SandboxedUiAdapter.

Session: נוצר על ידי ה-SDK בתגובה ל-SandboxedUiAdapter.openSession(). מייצג קריאה אחת של UI session. הקוד הזה מהווה את הקצה של מנהרת התקשורת בין ה-SDK לבעלי האפליקציה, ומקבל התראות על שינויים ב-SandboxedSdkView, כמו ניתוק חלונות, שינוי גודל או שינויים בהגדרות.

SessionClient: הספרייה הזו נוצרת על ידי ספריית הלקוח, והיא מהווה את הקצה של בעל התוכן הדיגיטלי במנהרה התקשורת בין ה-SDK לבין בעל התוכן הדיגיטלי.

SandboxedSdkUiSessionStateChangedListener: נוצר על ידי בעל התוכן הדיגיטלי. מאזין לשינויים במצב של סשן ממשק המשתמש שמשויך ל-SandboxedSdkView.

מידע נוסף על ממשקי ה-API האלה זמין במאמרי העזרה של privacysandbox-ui.

בקרת זרימה

בתרשימים הבאים מוצגת האינטראקציה בין ספריות ממשק המשתמש של הלקוח לבין ספריות ממשק המשתמש של הספק בתרחישים שונים:

בתרשים הקודם מוצג איך בעלי האפליקציה יכולים ליצור SandboxedSdkView באופן פרוגרמטי או דרך ה-XML שלהם, ולצרף אותו ל-SdkSandboxUiAdapter שהתקבל מה-SDK דרך ממשק API שהוגדר על ידי ה-SDK. כדי לעקוב אחרי כל השינויים במצב של ממשק המשתמש, בעל האפליקציה צריך להוסיף SandboxedSdkUiSessionStateChangedListener ל-SandboxedSdkView לפני שמצרפים את SdkSandboxUiAdapter.

בתרשים הזה מוצג איך, אם הפעילות של בעל התוכן הדיגיטלי מטפלת בשינויים בהגדרות, ספריית הלקוח מטפלת בהעברת שינוי ההגדרות ל-SDK, כדי שתהיה אפשרות לעדכן את ממשק המשתמש בהתאם. לדוגמה, התהליך הזה יכול להתרחש כשהמשתמש מסובב את המכשיר, והמפרסם מצהיר על טיפול בשינויים בהגדרות הפעילות שלו על ידי הגדרת android:configChanges=["orientation"].

בתרשים הזה מוצג איך ערכת ה-SDK יכולה לבקש שינוי בקונטיינר המודעות באמצעות שיטות ב-SessionClient. ה-API הזה מופעל כשמערכת ה-SDK רוצה לשנות את גודל המודעה, ובעל התוכן הדיגיטלי צריך לשנות את גודל מאגר המודעות כך שיתאים למימדים החדשים. זה יכול לקרות בתגובה לאינטראקציה של משתמש, כמו mraid.resize().

בתרשים הזה מוצג איך הסשן נסגר כשה-SandboxedSdkView מנותק מהחלון. אפשר גם לסגור את הסשן בכל שלב (למשל, כשהמשתמש מאבד את החיבור לרשת) באמצעות ה-SDK, על ידי קריאה ל-SessionClient.onSessionError().

סדר Z

ספריית ממשק המשתמש של הלקוח משתמשת ב-SurfaceView באופן פנימי כדי לארח את ממשק המשתמש של ה-SDK. SurfaceView יכול להשתמש בסדר Z כדי להציג את ממשק המשתמש שלו מעל החלון של בעל התוכן הדיגיטלי או מתחתיו. האפשרות הזו נשלטת על ידי השיטה SandboxedSdkView.orderProviderUiAboveClientUi(), שמקבלת את הערך הבוליאני setOnTop.

כשהערך של setOnTop הוא true, כל android.view.MotionEvent ב-SandboxedSdkView נשלח ל-SDK. כשהערך של false הוא 1, הנתונים האלה נשלחים לבעלי התוכן הדיגיטלי. כברירת מחדל, אירועי תנועה נשלחים ל-SDK.

בדרך כלל, בעלי תוכן דיגיטלי לא צריכים לשנות את ברירת המחדל של סדר הצפיות במודעות. עם זאת, כשמציגים ממשק משתמש שמכסה מודעה, כמו תפריט נפתח, צריך להפוך את סדר Z באופן זמני מברירת המחדל, ואז לשחזר אותו כשמבטלים את רכיב ממשק המשתמש שמכסה את המודעה. אנחנו בוחנים דרכים להפוך את התהליך הזה לאוטומטי בספריית ממשק המשתמש של הלקוח.

גלילה

כשמיקום ממשק המשתמש של המודעה הוא Z-above בחלון של בעל האפליקציה, הערכים של MotionEvents מ-UI של המודעה נשלחים ל-SDK. תנועות גלילה וזריחה שמתחילות בממשק המשתמש של המודעה מקבלות טיפול מיוחד:

1. תנועות של גלילה אנכית וזריקת תוכן נשלחות לקונטיינר של בעל התוכן הדיגיטלי, שם הן מטופלות. כך אפשר ליהנות מחוויית משתמש טובה כשאפשר לגלול אנכית בקונטיינר של בעל התוכן הדיגיטלי שבו ממוקם ממשק המשתמש של המודעה. לא נדרשת פעולה נוספת מצידכם או מציד ה-SDK של בעלי התוכן הדיגיטלי.
2. תנועות גלילה אופקית וזריקת נתונים נשלחות ל-SDK ומטופלות על ידו. כך אפשר ליהנות מחוויית משתמש טובה כשממשק המשתמש של המודעה עצמו ניתן לגלילה אופקית (למשל, קרוסלה של מודעות).

מדריך הטמעה

ה-SDK צריך לכלול את הרכיבים הבאים:

• SandboxedUiAdapter: הערך הזה מוחזר לבעלי האפליקציה בתגובה ל-API שהוגדר ב-SDK, כמו loadAd. צריך להשתמש בשיטה openSession() בהטמעה הזו כדי לשלוח בקשה להצגת מודעה לשרתים של ה-SDK ולהכין תצוגה של מודעה עבור הבקשה הזו.
• Session**: הערך הזה מוחזר בתגובה לקריאה SandboxedUiAdapter.openSession. הוא מספק דרך לספריית הלקוח לקבל את ממשק המשתמש של המודעה ולהודיע ל-SDK על שינויים בממשק ה-API הזה. כאן צריך להטמיע את כל השיטות של Session.

המוציא לאור צריך לבצע את הפעולות הבאות:

1. יוצרים SandboxedSdkView באמצעות XML או באופן פרוגרמטי.
2. מחברים SandboxedSdkUiSessionStateChangedListener ל-SandboxedSdkView כדי לראות את השינויים בממשק המשתמש.
3. מצרפים את ה-SDK שסופק על ידי SandboxedUiAdapter אל SandboxedSdkView.
4. מוסיפים את SandboxedSdkView לחלון כרגיל, ומאפשרים לספריית הלקוח ליצור ולנהל את סשן ממשק המשתמש באמצעות ה-SDK.
5. בתזמונים מתאימים, להגיב לשינויים במצב שמדווח על ידי SandboxedSdkUiSessionChangedListener. לדוגמה, אם ה-SDK סוגר את הסשן באופן בלתי צפוי, בעל התוכן הדיגיטלי יכול להחליף את SandboxedSdkView בתמונה סטטית או להסיר אותו מהיררכיית התצוגה שלו.
6. כשמבצעים מעברים שעשויים לכסות את ממשק המשתמש של המודעה, כמו תפריט נפתח, צריך להגדיר את orderProviderUiAboveClientUi ל-false באופן זמני כדי למקם את ממשק המשתמש של המודעה מתחת לחלון של בעל התוכן הדיגיטלי. אחרי שהתפריט הנפתח נסגר, מקישים על orderProviderUiAboveClientUi עד true.

העתיד של ממשקי ה-API של הפלטפורמה

אחרי שספריות ממשק המשתמש יעברו לגרסת בטא, אנחנו מתכננים להוציא משימוש את ממשקי ה-API של פלטפורמת זמן הריצה של ה-SDK שקשורים להצגת ממשק המשתמש, כלומר SdkSandboxManager.requestSurfacePackage() ו-SandbxedSdkProvider.getView().

שאלות פתוחות

1. האם יש תרחישים נפוצים נוספים של ממשק משתמש במודעות שספריות ממשק המשתמש צריכות לטפל בהם באופן אוטומטי?
2. באילו מסגרות ממשק משתמש אתם משתמשים כדי להציג את ממשק המשתמש של המודעות? האם צפויות בעיות בשילוב של ספריות ממשק המשתמש עם המסגרות האלה?
3. האם אתם משתמשים בתרחיש נפוץ שבו ממשק המשתמש של מודעה שאפשר לגלול בה ממוקם במאגר של בעל תוכן דיגיטלי שאפשר לגלול בו? מה כיוון הגלילה של ממשק המשתמש של המודעה והקונטיינר במקרה הזה? איזו התנהגות אתם מצפים למשתמש כשהוא מתחיל לגלול בממשק המשתמש של המודעה?