תמיכה בתהליך בחירת הרשת (Mediation) בסביבת זמן הריצה של ה-SDK

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

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

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

התמיכה במודעות בתהליך בחירת הרשת (Mediated Ads) בזמן הריצה של ה-SDK זמינה מ-AGP 8.5 ומהגרסאות הבאות של ספריות Jetpack בזמן הריצה של ה-SDK:

ספריית Androidx	גרסה
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

מילון מונחים

המונחים הבאים הם המפתח להבנת תהליך בחירת הרשת בסביבת זמן הריצה של ה-SDK:

• SDK שתומך בסביבת זמן ריצה (RE SDK): SDK שנועד לפעול בסביבת זמן הריצה של ה-SDK ולתקשר עם האפליקציה באמצעות תקשורת בין תהליכים (IPC).
• SDK עם תמיכה בסביבת זמן ריצה (RA SDK): ערכת SDK שלא תומכת בסביבת זמן ריצה, שמקושרת לאפליקציה באופן סטטי ועשויה להכיל את קוד ה-SDK הקיים וגם קוד חדש לקריאה ל-SDK שתומך בסביבת זמן ריצה.
• SDK מובנה באפליקציה: ערכת SDK שפועלת באופן סטטי כחלק מהאפליקציה, ללא מודעוּת לזמן הריצה של ה-SDK. יכול להיות שמדובר ברשת מודעות שלא עברה ל-SDK Runtime, או במתאם מותאם אישית של בעל אפליקציה.
• Mediator: ערכת SDK לבחירת רשת להצגת מודעות שמספקת שירות בחירת רשת במכשיר באמצעות אינטראקציה עם ערכות SDK אחרות של רשתות פרסום.
• Mediatee: ערכת SDK של רשת מודעות שמפעיל המתווך כדי לספק מודעה ולעבד אותה.
• מתאם בחירת הרשת: ערכות SDK שמשמשות את Mediator SDK כדי לספק תרגום של ממשק ה-API לצורך פעולה הדדית עם ערכות SDK שונות של צדדים נבחרים, בדרך כלל מסופקות על ידי הגורם המתווך. הן יכולות להיות מודעות מודעות לסביבת זמן הריצה או לא מודעות לסביבת זמן הריצה.

תהליכי בחירת רשת (Mediation) אופייניים

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

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

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

• הפעלה (כולל זיהוי רשתות מודעות ותקשורת)
• מצגת של ממשק המשתמש (UI) של מודעות

אתחול

התרשים הבא מייצג את תהליך האיפוס, זיהוי רשתות המודעות ותהליך התקשורת הרגילים:

1. אפליקציית הלקוח מפעילה את המתווך
2. המתווך מאתר ומפעיל את הגורמים הרלוונטיים (mediates) והמתאמים (adapters)
3. המתווך משתמש במתאמים שלו כדי לתקשר עם כל צד ב-Mediated
4. אפליקציית הלקוח מבקשת מהמתווך לטעון מודעה
5. אפליקציית הלקוח מבקשת מהמתווך להציג את המודעה הזו

הערה: בתהליך הזה, אנחנו מניחים שאפליקציית הלקוח תלויה ב-SDK של ה-Mediator, ב-SDK של ספקי ה-Mediation ובמתאמי ה-Mediation, והיא נוצרה באמצעותם.

הצגת ממשק המשתמש של מודעות

כשמדובר ברינדור של המודעה אחרי הבקשה האחרונה בשלב הקודם, התהליך תלוי בסוג המודעה:

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

תהליכי בחירת הרשת בזמן הריצה של ה-SDK

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

• גם הגורם המתווך וגם הגורם המתווך אליו מתבצעת העברה נמצאים בזמן הריצה של ה-SDK: RE mediatee
• המתווך נמצא בזמן הריצה ל-SDK, והצד המתווך נמצא באפליקציה: צד מתווך באפליקציה

RE Mediatee

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

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

איור 1. גם הגורם המתווך וגם הגורם המתווך דרך הגורם המתווך הם ערכות SDK של RE.

אתחול

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

1. האפליקציה (או ה-RA SDK) טוענת ומפעילה את ה-SDK של המתווך באמצעות SdkSandboxManager#loadSdk.
2. במהלך האתחול, ה-SDK של המתווך טוען ומאתחלל את כל הרכיבים הנדרשים לצורך תהליך בחירת הרשת (Mediation) בסביבת זמן הריצה של ה-SDK באמצעות SdkSandboxController#loadSdk.
3. אפשר למצוא את כל ערכות ה-SDK שהועמסו בסביבת זמן הריצה באמצעות קריאה ל-SdkSandboxController#getSandboxedSdks.

איור 2. תהליך לאינטליקציה של צד שלישי (RE) שמתווך.

הערה: כדי לוודא שערכת ה-SDK שתואמת לזמן הריצה תואמת לאחור, צריך להשתמש בקטגוריות של מנהל Runtime ושל בקר *Compat.

הצגת ממשק המשתמש של מודעות

בקטע הבא מוסבר איך לטעון מודעות באנר ומודעות במסך מלא מ-REmedeiatee.

RE Mediatee banner ads

כשמתקבלת מהאפליקציה בקשה לטעון מודעת באנר, תהליך השלמת העיבוד הוא:

1. המודיעין בוחר את הצד הזוכה בתהליך בחירת הרשת של המודעה הזו.
2. המתווך מקבל מSandboxedUiAdapter של הצד בהליך גישור.
3. המתווך מעביר את UiAdapter לאפליקציה.

איור 3. תהליך השלמת העיבוד של מודעת באנר שנשלחה מחשבון שמשתתף בתהליך בחירת הרשת (Mediation) של RE.

מידע נוסף על השימוש ב-SandboxedUiAdapter ובספריית ממשק המשתמש בסביבת זמן הריצה של ה-SDK

שכבות-על למודעות באנר

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

1. המתווך יוצר פריסה עם שכבת-העל שלה ועם SandboxedSdkView.
2. המודיעין בוחר את הצד הזוכה בתהליך בחירת הרשת של המודעה הזו.
3. המתווך מקבל מ-Mediatee את SandboxedUiAdapter.
4. המתווך מגדיר את UiAdapter של הצד המתווך ל-SandboxedSdkView.
5. הגורם המתווך משתף את התצוגה המאוכלסת עם האפליקציה.

תהליך להצגת שכבת-על של תצוגה מעל מודעת באנר שהתקבלה מ-RE Mediatee.

RE Mediatee full-screen ads

כשמתקבלת בקשה מהאפליקציה לטעון מודעה במסך מלא, התהליך מתבצע לפי השלבים הבאים:

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

איור 4. תרשים תהליך שמראה איך לטעון מודעה במסך מלא שמנוהלת על ידי צד שלישי מ-RE Mediatee.

הערה: כל אירועי מחזור החיים של הפעילות זמינים לצד השלישי באמצעות המזהה ActivityHolder שבו השתמש בזמן הרישום של הטיפול בפעילות.

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

Mediatee באפליקציה

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

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

אתחול

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

צריכה להיות גישה לרישום הזה באמצעות ה-API של המתווך, אבל פרטי ההטמעה נתונים לשיקול דעתו של כל מתווך. אנחנו קוראים ל-API הזה MediationSandboxedSdk#registerInAppMediatee.

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

1. האפליקציה טוענת ומפעילה את ה-SDK של המתווך שמותאם לסביבת זמן הריצה.
2. ה-SDK של ה-RA של המודד:
   1. הפעלת ה-RE SDK של המתווך באמצעות SdkSandboxManager#loadSdk.
   2. אתחול כל ערכות ה-SDK של צד שלישי לבחירת רשת (Mediated) בתוך האפליקציה.
   3. המערכת מאתרת ומרשמת את ערכות ה-SDK של הגורמים המתווך באפליקציה באמצעות ה-API שסופק על ידי ה-SDK של RE, ‏ MediationSandboxedSdk#registerInAppMediate.

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

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

הצגת ממשק המשתמש של מודעות

בקטע הבא מוסבר איך לטעון מודעות באנר ומודעות במסך מלא מ-Mediatee באפליקציה.

מודעות באנר בתוך האפליקציה שמנוהלות על ידי צד שלישי

כשמתקבלת מהאפליקציה בקשה לטעון מודעת באנר, תהליך השלמת העיבוד הוא:

1. ערכת ה-SDK של המודד שמתאימה לסביבת זמן הריצה מעבירה את הבקשה של האפליקציה ל-SDK שלו שמתאימה לסביבת זמן הריצה.
2. ערכת ה-SDK של ה-RE של המתווך בוחרת את הצד הרלוונטי לגישור.
3. ה-SDK של רשת ה-RE של המודד מאחזר את ההפניה למודד, ומבקש לטעון מודעה דרך ה-SDK של רשת ה-RA.
4. ה-SDK של RA מקבל View מהגורם המתווך באפליקציה.
5. ה-SDK של RA יוצר SandboxedUiAdapter לתצוגה שהוא קיבל.
6. ה-SDK של RA מעביר את UiAdapter ל-SDK של RE.
7. ה-SDK של RE מעביר את UiAdapter לאפליקציה.

זהירות: מכיוון שה-SandboxedUiAdapter הזה מתקבל מהתהליך של האפליקציה, לא מומלץ להוסיף שכבות-על לתצוגה הזו כי זה עלול להוביל לבעיות זמן אחזור, ביצועים והתנהגות.

איור 7. הערה: המתווך לא אמור להוסיף שכבת-על של תצוגות על V1 כשמקבל אותו מגורם מתווך בתוך האפליקציה.

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

כשמתקבלת בקשה מהאפליקציה לטעון מודעה במסך מלא, התהליך מתבצע לפי השלבים הבאים:

1. האפליקציה מעבירה את הערך SdkActivityLauncher ל-RA SDK של המודד עם הבקשה לטעון מודעה.
   1. הלקוח יכול להגביל את היצירה של פעילויות באמצעות תנאי.
2. ה-SDK של הרשת המתווך (RA) מעביר את הבקשה של האפליקציה ל-SDK של הרשת המארחת (RE).
3. ה-SDK של RE של המתווך:
   1. בחירת הצד הרלוונטי לגישור.
   2. אחזור ההפניה לצד השלישי שמופעלת דרכו התקשורת בתוך האפליקציה.
   3. בקשות לטעינת מודעה דרך RA SDK.
4. ה-SDK של רשת ה-RA מבקש מהרשת שמוגדרת בתהליך בחירת הרשת לטעון מודעה.
5. המשתתף בשיחת הווידאו מתחיל את הפעילות ישירות. התנאי של האפליקציה לא יתקבל.

איור 8. המערכת שתתבצע בה תהליך בחירת הרשת באפליקציה תתעלם מהטענה.

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

יצירת מעורבות ושיתוף משוב

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