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

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

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

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

התמיכה במודעות שמתווכות על ידי זמן הריצה ל-SDK זמינה מ-AGP 8.5 ומגרסאות ה-SDK Runtime Jetpack libraries הבאות:

ספריית 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 Runtime:

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

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

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

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

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

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

אתחול

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

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

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

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

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

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

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

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

RE Mediatee

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

מתאמי גישור צריכים להיות באותו תהליך כמו המתווך שאיתו הם יוצרים אינטראקציה, ולכן הם גם יצטרכו לעבור אל SDK Runtime.

אתחול

כשמתייחסים לאתחול, לגילוי ולתקשורת של רכיב mediator ו-mediatee שמופעלים בזמן ריצה, התהליך יכלול את השלבים הבאים:

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

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

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

RE Mediatee banner ads

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

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

מידע נוסף על השימוש ב-SandboxedUiAdapter וב-SDK Runtime UI Library

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

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

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

RE Mediatee full-screen ads

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

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

מידע נוסף על תמיכה בפעילות במודעות במסך מלא ב-SDK Runtime

In-app Mediatee

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

אתחול

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

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

כשמביאים בחשבון את ההפעלה, הגילוי והתקשורת של SDK של רשת תיווך ושל SDKs של רשתות תיווך באפליקציה, התהליך יתבצע לפי השלבים הבאים:

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

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

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

בקטע הבא מוסבר איך לטעון מודעות באנר ומודעות במסך מלא מתוך אפליקציה שמשמשת כפלטפורמה לבחירת רשת (Mediation).

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

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

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

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

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

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

אינטראקציה ושיתוף משוב

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