תמיכה בפעילות במודעות במסך מלא

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

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

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

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

הפעילות שסופקת על ידי הפלטפורמה היא android.app.Activity רגילה, שמופעל כחלק מהמשימה של אפליקציית הלקוח.

יצירת פעילות בסביבת זמן הריצה של ה-SDK

יש שתי שיטות עיקריות ליצירת פעילויות: שימוש בספריות הפעילות המשופרות של Jetpack או אינטראקציה ישירה עם ממשקי ה-API של הפלטפורמה.

מומלץ להשתמש בספריות פעילויות, כי הן מפשטות את יצירת הפעילויות על ידי הסרת המורכבות הבסיסית.

ספריות פעילויות

ספריות פעילויות מספקות כמה יתרונות:

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

יש שלוש ספריות פעילות: ליבה, לקוח וספקי.

  • הספרייה core מספקת את הממשקים שבהם משתמשות אפליקציות הלקוח וספריות הספקים.
  • ספריית provider מספקת ממשקי API ל-SDK כדי להפעיל פעילויות.
  • ספריית הלקוח מספקת ממשקי API לאפליקציות לקוח כדי ליצור מרכז הפעלה של פעילויות. ערכות SDK יכולות להשתמש במרכז ההפעלה הזה כדי לבקש מאפליקציות להפעיל פעילויות.

הספריות האלה כוללות את ממשקי ה-API הבאים:

  • SdkActivityLauncher: מרכז האפליקציות מאפשר לערכות SDK לטפל בהפעלת פעילויות מאפליקציית הלקוח. אפליקציות לקוח צריכות ליצור מרכז אפליקציות ולהעביר אותו כפרמטר לממשקי ה-API של ה-SDK שמפעילים את הפעילויות.
  • <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): פונקציית תוסף שאפליקציית הלקוח יכולה להפעיל מהפעילויות שלה כדי ליצור מרכזי אפליקציות.
  • SdkActivityLauncher.launchSdkActivity(IBinder): שיטה שבה ה-SDK משתמש כדי לבקש מהאפליקציה להפעיל פעילויות.

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

  1. ה-SDK מוסיף פרמטר מסוג SdkActivityLauncher לכל ממשקי ה-API שיפעילו פעילויות.
  2. אפליקציית הלקוח קוראת ל-createSdkActivityLauncher באחת מהפעילויות שלה כדי ליצור מרכז אפליקציות שאפשר להעביר ל-SDK בקריאות ל-API.
  3. ה-SDK קורא ל-SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) ומאחזר את אסימון המזהה.
  4. ערכת ה-SDK קוראת ל-launchSdkActivity כדי להפעיל את הפעילות.

בתרשים הבא מוצג התהליך במקרה של שימוש בספריות פעילות.

דיאגרמת רצף של ספריית פעילויות
תרשים רצף שבו מוצג התהליך של הפעלת פעילות באמצעות ספריות פעילות.

ממשקי API של פלטפורמות

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

כדי להתחיל פעילות באמצעות ממשקי ה-API של הפלטפורמה, ערכות ה-SDK צריכות לפעול לפי התהליך הבא:

  1. ה-SDK רושם בורר פעילויות באמצעות ממשקי ה-API שסופקו ומקבל מזהה.
  2. ה-SDK משתף את המזהה הזה עם אפליקציית הלקוח שלו.
  3. אפליקציית הלקוח קוראת לשיטה להפעלת פעילות בסביבת זמן הריצה של ה-SDK באמצעות ממשק ה-API של הפלטפורמה startSdkSandboxActivity(Activity, IBinder), ומעבירה כפרמטרים את הפעילות ההתחלתית שנבחרה לפעילות החדשה הזו ואת המזהה של טיפול האירועים.
  4. הפלטפורמה מפעילה פעילות ומעדכנת את ה-SDK באמצעות קריאה חוזרת (callback) ב-Activity Handler‏ (SdkSandboxActivityHandler.onActivityCreated(Activity)).
  5. ערכת ה-SDK משתמשת בפעילות כדי לאכלס אותה במודעה.

כשמשתמשים בממשקי API של פלטפורמה, ה-SDK אחראי לשתף את המזהה של SdkSandboxActivityHandler עם אפליקציית הלקוח דרך ממשקי ה-API שלו בזמן המתאים, ולהנחות את אפליקציות הלקוח איך להשתמש בו.

בתרשים התהליך הבא, ל-SDK לדוגמה יש שיטה launchActivity(AppCallback) שמצפה להפעלה חוזרת (הגדרה כחלק מ-API של ה-SDK). ה-SDK משתמש בקריאה החוזרת הזו כדי לשתף את המזהה של ה-Activity Handler‏ (SdkSandboxActivityHandler) עם אפליקציית הלקוח.

תרשים רצף של ממשקי API של פלטפורמה
תרשים רצף שבו מוצג תהליך הפעלת פעילות באמצעות ממשקי API של פלטפורמות.

ניראות

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

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

לעומת זאת, הפעילות שסופקת על ידי הפלטפורמה פועלת באופן מקורי בתהליך של זמן הריצה ל-SDK, ומבטלת את הצורך בערוצים צדדיים ומאפשרת לערכות SDK להשתמש בממשקי ה-API הרגילים של Android‏ Activity ו-View.

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

מחזור חיים

הערך של ActivityHolder שמוענק ל-SDK דרך SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) מאפשר להטמיע את LifecycleOwner, וניתן להשתמש בו כדי לקבל מידע על Lifecycle.Event.

ניווט חזרה

השיטה ActivityHolder.getOnBackPressedDispatcher() מחזירה את הערך OnBackPressedDispatcher, שאפשר להשתמש בו כדי לרשום מכונות OnBackPressedCallback לטיפול בניווט לאחור.