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

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

ההצדקה להרחבת ממשקי ה-API של הפלטפורמה

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

1. ה-SDK מאפשר לנהל כמה תצוגות של מודעות במהלך חייו ולהבין מה קורה לממשק המשתמש של המודעה אחרי שהוא נוצר על ידי ה-SDK.
2. מפריד בין יצירת התצוגה לבין שיוך התוכן. השימוש בערוץ הצדדי מאפשר ל-SDK להחזיר לאפליקציה אובייקט שתואם לבקשה להצגת מודעה (התוכן), שאפשר לקשר אותו למאגר המודעות בכל פעם שהאפליקציה רואה לנכון.
3. הוא מסתיר את מבני הפלטפורמה הבסיסיים שמשמשים להצגת ממשק המשתמש בתהליכים. (הפלטפורמה משתמשת כרגע ב-SurfaceControlViewhost ומפיקה ממנו SurfacePackage).
4. ההרשאה מאפשרת ל-SDK להצגת מודעות ב-SDK Runtime לקבל באופן אוטומטי התראות כשממשק המשתמש של מאגר המודעות משתנה. אם בעל האתר משנה את הפריסה של מאגר המודעות, ה-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(). מייצג שיחה אחת בממשק המשתמש. החלק הזה מהווה את קצה ה-SDK של מנהרת התקשורת בין ה-SDK לבין בעל האתר, ומקבל התראות על שינויים ב-SandboxedSdkView, כמו ניתוקים, שינויי גודל או שינויים בהגדרות של חלון.

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

‫SandboxedSdkUiSessionStateChangedListener: נוצר על ידי המוציא לאור. רכיב listener לשינויים במצב של סשן ממשק המשתמש שמשויך ל-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, הנתונים האלה נשלחים אל בעל התוכן הדיגיטלי. כברירת מחדל, אירועי תנועה נשלחים אל ה-SDK.

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

גלילה

כשממשק המשתמש של המודעה ממוקם מעל חלון האפליקציה של בעל האפליקציה, MotionEvents מממשק המשתמש של המודעה נשלחים אל ה-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. האם הצבת ממשק משתמש של מודעות שניתן לגלול בו במאגר של אתר חדשות שאפשר לגלול בו היא תרחיש שימוש נפוץ עבורך? מה כיוון הגלילה בממשק המשתמש של המודעה ובמאגר במקרה הזה? איזו התנהגות צפויה כשמשתמש מתחיל לגלול בממשק המשתמש של המודעה?