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

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

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

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

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

ממשקי ה-API

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

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

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

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

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

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

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

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

גלילה

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

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

מדריך הטמעה

ב-SDK צריך להטמיע את הרכיבים הבאים:

  • SandboxedUiAdapter: הערך הזה מוחזר לבעלי האפליקציה בתגובה ל-API שהוגדר ב-SDK, כמו loadAd. ה-method 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 של הפלטפורמה

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

שאלות פתוחות

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