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

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

פירוט הנימוקים להרחבת ממשקי ה-API של הפלטפורמה

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

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

ספריות ממשק משתמש

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

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

ממשקי ה-API

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

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

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

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

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

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

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

לפרטים נוספים על ממשקי ה-API האלה, קראו את מסמכי העזר בנושא privacysandbox-ui.

שליטה בתהליך

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

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

קבל את ממשק המשתמש מ-SDK.

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

שינוי בממשק המשתמש ביוזמת בעל האפליקציה.

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

שינוי בממשק המשתמש ביוזמת SDK.

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

סגירת הסשן של ממשק המשתמש.

סדר Z

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

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

בדרך כלל בעלי אתרים לא צריכים לשנות את סדר ה-Z שמוגדר כברירת מחדל עבור תצוגות המודעות. עם זאת, כשמציגים ממשק משתמש שמכסה מודעה, למשל תפריט נפתח, צריך להפוך באופן זמני את סידור ה-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. צריך לצרף ל-SandboxedSdkView ערכת SDK שסופקה SandboxedUiAdapter.
4. מוסיפים את SandboxedSdkView לחלון כרגיל, וספריית הלקוח תטפל ביצירה ובתחזוקה של הסשן של ממשק המשתמש עם ה-SDK.
5. חשוב להגיב לשינויים במצב שדווח על ידי SandboxedSdkUiSessionChangedListener, בתזמון המתאים. לדוגמה, אם ה-SDK סוגר את הסשן באופן בלתי צפוי, בעל האתר יכול להחליף את SandboxedSdkView בתמונה סטטית או להסיר אותה מהיררכיית התצוגות שלו.
6. כשמבצעים מעברים שעשויים לכסות את ממשק המשתמש של המודעה, כמו תפריט נפתח, orderProviderUiAboveClientUi ל-FALSE באופן זמני כדי למקם את ממשק המשתמש של המודעה מתחת לחלון של בעל האתר. אחרי שסוגרים את התפריט הנפתח, קוראים למספר orderProviderUiAboveClientUi אל true.

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

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

שאלות פתוחות

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