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

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

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

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

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

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

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

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

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

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

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

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

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

  • ספריית הליבה מספקת את הממשקים שמשמשים את אפליקציות הלקוח ואת ספריות הספקים.
  • ספריית הספקים מספקת ממשקי 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) ב-handler של הפעילות (SdkSandboxActivityHandler.onActivityCreated(Activity)).
  5. ערכת ה-SDK משתמשת בפעילות כדי לאכלס אותה במודעה.

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

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

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

ניראות

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

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

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

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

מחזור חיים

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

ניווט חזרה

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