תמיכה בטירגוט לפי קהל בהתאמה אישית באמצעות Protected Audience API

עדכונים אחרונים

• נוסף מידע על תזמון עדכונים של קהלים בהתאמה אישית
• נוספה אינטגרציה של דוחות שיוך (Attribution) עם Protected Audiences
• פרסמנו ציר זמן של תכונות Protected Audience.
• השם של FLEDGE שונה ל-Protected Audience API.
• נוספה הצעה להענקת הרשאה לניהול קהלים בהתאמה אישית.
• הסרנו את הדרישה ל-k-anonymity עבור כתובת ה-URL של העדכון היומי.

התכונה Protected Audience נמצאת בגרסת בטא וזמינה לפיתוח.

בעזרת קהלים מוגנים, אתם יכולים:

• ניהול קהלים בהתאמה אישית שמבוססים על פעולות קודמות של משתמשים.
• להפעיל במכשיר מכרזים עם תמיכה בתהליך בחירת רשת (Mediation) של מוכר יחיד או של רשתות מפל.
• הפעלת דיווח על חשיפות אחרי בחירת המודעה.

כדי להתחיל, כדאי לקרוא את המדריך למפתחים בנושא Protected Audience API. אנחנו ממשיכים לפתח את Protected Audience, לכן נשמח לקבל ממך משוב.

ציר הזמן

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

סקירה כללית

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

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

‫Protected Audience API ב-Android (לשעבר FLEDGE) כולל את ממשקי ה-API הבאים לפלטפורמות פרסום דיגיטלי ולמפרסמים, כדי לתמוך בתרחישי שימוש נפוצים שמבוססים על אינטראקציות, באופן שמגביל את השיתוף של מזהים בין אפליקציות ושל נתוני האינטראקציות של המשתמש עם האפליקציות עם צדדים שלישיים:

1. ‫Custom Audience API: ה-API הזה מתמקד בהפשטה של 'קהל בהתאמה אישית', שמייצגת קהל שהמפרסם הגדיר עם כוונות משותפות. פרטי הקהל מאוחסנים במכשיר ויכולים להיות משויכים למודעות רלוונטיות פוטנציאליות לקהל ולמטא-נתונים שרירותיים, כמו אותות בידינג. אפשר להשתמש במידע הזה כדי לשפר את הצעות המחיר של המפרסמים, את סינון המודעות ואת העיבוד שלהן.
2. ‫Ad Selection API: ממשק ה-API הזה מספק מסגרת שמתזמנת את תהליכי העבודה של פלטפורמות טכנולוגיות פרסום שמשתמשות באותות במכשיר כדי לקבוע איזו מודעה היא ה"מנצחת". הוא עושה זאת על ידי בחינת מודעות מועמדות שמאוחסנות באופן מקומי וביצוע עיבוד נוסף של מודעות מועמדות שפלטפורמת טכנולוגיית פרסום מחזירה למכשיר.

באופן כללי, השילוב פועל כך:

1. האפליקציה SportingGoodsApp רוצה להזכיר למשתמשים לרכוש פריטי מרצ'נדייז שהם השאירו בעגלת הקניות אם הם לא השלימו את הרכישה תוך יומיים. אפליקציית SportingGoodsApp משתמשת ב-Custom Audience API כדי להוסיף את המשתמש לרשימת הקהלים 'מוצרים בעגלת הקניות'. הפלטפורמה מנהלת את רשימת קהלים הזו ושומרת אותה במכשיר, וכך מצמצמת את השיתוף עם צדדים שלישיים. האפליקציה SportingGoodsApp משתפת פעולה עם פלטפורמת טכנולוגיית פרסום כדי להציג מודעות למשתמשים ברשימת הקהלים שלה. פלטפורמת טכנולוגיית הפרסום מנהלת מטא-נתונים של רשימות קהלים ומספקת מודעות מועמדות, שזמינות לתהליך העבודה של בחירת המודעות לצורך בדיקה. אפשר להגדיר את הפלטפורמה כך שתאחזר באופן תקופתי מודעות מעודכנות שמבוססות על קהלים ברקע. כך רשימת המודעות המועמדות שמבוססות על קהלים נשארת עדכנית ולא קשורה לבקשות שנשלחות לשרתי מודעות של צד שלישי במהלך ההזדמנות להצגת מודעה (כלומר, בקשה להצגת מודעה בהקשר).

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

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

4. הפלטפורמה מאפשרת לדווח על חשיפות ועל תוצאות של בחירת מודעות. יכולת הדיווח הזו משלימה את Attribution Reporting API. פלטפורמות טכנולוגיות פרסום יכולות להתאים אישית את ההגדרות בהתאם לצרכים שלהן בדיווח.

קבלת גישה אל Protected Audience API ב-Android

פלטפורמות של טכנולוגיות פרסום צריכות להירשם כדי לקבל גישה אל Protected Audience API. מידע נוסף זמין במאמר בנושא הרשמה לחשבון בארגז החול לפרטיות.

ניהול קהלים בהתאמה אישית

קהל בהתאמה אישית

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

אפליקציה של מפרסם או SDK משולב יכולים להצטרף לקהל מותאם אישית או לצאת ממנו, למשל על סמך האינטראקציה של המשתמש עם האפליקציה.

מטא-נתונים של קהלים בהתאמה אישית

כל קהל בהתאמה אישית מכיל את המטא-נתונים הבאים:

• בעלים: שם החבילה של אפליקציית הבעלים. הערך הזה מוגדר באופן מרומז לשם החבילה של האפליקציה שקוראת לפונקציה.
• קונה: רשת מודעות של קונה שמנהלת מודעות עבור הקהל הזה בהתאמה אישית. הקונה מייצג גם את הצד שיכול לגשת לקהל המותאם אישית ולאחזר מידע רלוונטי על המודעות. הקונה מצוין בפורמט eTLD+1.
• שם: שם שרירותי או מזהה של הקהל המותאם אישית, כמו משתמש שנטש את עגלת הקניות. לדוגמה, אפשר להשתמש במאפיין הזה כאחד מקריטריוני הטירגוט בקמפיינים הפרסומיים של המפרסם, או כמחרוזת שאילתה בכתובת ה-URL לאחזור קוד הצעת המחיר.
• זמן ההפעלה וזמן התפוגה: בשדות האלה מוגדר חלון הזמן שבו הקהל המותאם אישית הזה יהיה פעיל. הפלטפורמה משתמשת במידע הזה כדי להסיר משתמשים מקהל בהתאמה אישית. זמן התפוגה לא יכול לחרוג מחלון משך הזמן המקסימלי כדי להגביל את משך החיים של קהל מותאם אישית.
• כתובת URL לעדכון יומי: כתובת ה-URL שהפלטפורמה משתמשת בה כדי לאחזר מודעות פוטנציאליות ומטא-נתונים אחרים שמוגדרים בשדות User bidding signals (אותות בידינג למשתמש) ו-Trusted bidding signals (אותות בידינג מהימנים) על בסיס חוזר. פרטים נוספים זמינים בקטע על אחזור מודעות שמתאימות לקהלים מותאמים אישית.
• אותות בידינג של משתמשים: אותות ספציפיים לפלטפורמות טכנולוגיות פרסום שקשורים לכל בידינג של מודעות רימרקטינג. דוגמאות לאותות: המיקום המשוער של המשתמש או הלוקאל המועדף.
• נתוני בידינג מהימנים: פלטפורמות פרסום דיגיטלי מסתמכות על נתונים בזמן אמת כדי לקבל החלטות לגבי אחזור מודעות ודירוג שלהן. לדוגמה, יכול להיות שהתקציב של מודעה מסוימת ימוצה ויהיה צורך להפסיק את הצגתה באופן מיידי. טכנולוגיית פרסום יכולה להגדיר נקודת קצה של כתובת URL שממנה אפשר לאחזר את הנתונים בזמן אמת, ואת מערך המפתחות שצריך לבצע עבורם את החיפוש בזמן אמת. השרת שמטפל בבקשה הזו הוא שרת מהימן שמנוהל על ידי פלטפורמת הטכנולוגיה הפרסומית.
• כתובת URL של לוגיקת הבידינג: כתובת ה-URL שהפלטפורמה משתמשת בה כדי לאחזר קוד בידינג מפלטפורמת הביקוש. הפלטפורמה מבצעת את השלב הזה כשמתחיל מכרז על מודעה.
• מודעות: רשימה של מודעות שמועמדות להיכלל בקהל המותאם אישית. המידע הזה כולל מטא-נתונים של מודעות שספציפיים לפלטפורמות טכנולוגיות פרסום וכתובת URL להצגת המודעה. כשמתחיל מכרז לקהל המותאם אישית, המערכת מתייחסת לרשימה הזו של מטא-נתונים של מודעות. רשימת המודעות הזו תתעדכן באמצעות נקודת הקצה של כתובת ה-URL לעדכון יומי, כשזה אפשרי. בגלל מגבלות משאבים במכשירים ניידים, יש הגבלה על מספר המודעות שאפשר לשמור בקהל מותאם אישית.

הענקת הרשאה לניהול קהלים בהתאמה אישית

הגישה המקובלת להגדרה ולתצורה של קהלים מותאמים אישית מסתמכת בדרך כלל על טכנולוגיות בצד השרת ועל שילובים שמבוססים על טכנולוגיות פרסום בשיתוף עם סוכנויות, מפרסמים ושותפים. ‫Protected Audience API מאפשר להגדיר קהלים מותאמים אישית ולהגדיר את ההגדרות שלהם תוך שמירה על פרטיות המשתמשים. כדי להצטרף לקהל מותאם אישית, ספקי טכנולוגיית פרסום (ATP) של קונים שאין להם SDK באפליקציות צריכים לשתף פעולה עם ספקי ATP שיש להם נוכחות במכשיר, כמו שותפי מדידה לנייד (MMP) ופלטפורמות לספקים (SSP). המטרה של Protected Audience API היא לתמוך בערכות ה-SDK האלה באמצעות פתרונות גמישים לניהול קהלים בהתאמה אישית. ה-API מאפשר למי שמבצע קריאות במכשיר להפעיל יצירה של קהלים בהתאמה אישית בשם הקונים. התהליך הזה נקרא העברת הרשאה לקהל מותאם אישית. כדי להגדיר העברת הרשאה לקהלים בהתאמה אישית:

הצטרפות לקהל בהתאמה אישית

יש שתי דרכים להצטרף לקהל מותאם אישית:

joinCustomAudience()

אפליקציה או SDK יכולים לשלוח בקשה להצטרפות לקהל מותאם אישית באמצעות קריאה ל-joinCustomAudience() אחרי יצירת מופע של האובייקט CustomAudience עם הפרמטרים הצפויים. דוגמה לקטע קוד להמחשה:

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

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

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

נקודת הקצה של כתובת ה-URL, שנמצאת בבעלות הקונה, מחזירה אובייקט CustomAudience JSON בגוף התגובה. השדות buyer (קונה) ו-owner (בעלים) של הקהל בהתאמה אישית מוזנחים (ומתמלאים אוטומטית על ידי ה-API). בנוסף, ה-API מוודא שכתובת ה-URL של העדכון היומי תתאים גם ל-eTLD+1 של הקונה.

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

‫fetchAndJoinCustomAudience() API קובע את זהות הקונה מ-eTLD+1 של fetchUri. CustomAudience הזהות של הקונה משמשת לביצוע אותן בדיקות של הרשמה והרשאת אפליקציה שמבוצעות על ידי joinCustomAudience(), ואי אפשר לשנות אותה בתגובת האחזור. הבעלים של CustomAudience הוא שם החבילה של האפליקציה שקוראת לפונקציה. אין אימות אחר של fetchUri מלבד בדיקת eTLD+1, ובפרט, אין בדיקת k-anon. ‫fetchAndJoinCustomAudience() API שולח בקשת HTTP GET אל fetchUri ומצפה לקבל אובייקט JSON שמייצג את קהל היעד המותאם אישית. אותם אילוצים של חובה, אילוצים אופציונליים וערכי ברירת מחדל של שדות אובייקט של קהל מותאם אישית חלים על התגובה. במדריך למפתחים אפשר לקרוא על הדרישות והמגבלות העדכניות.

כל תגובת שגיאה של HTTP מהקונה גורמת לfetchAndJoinCustomAudience להיכשל. בפרט, תגובת סטטוס HTTP‏ 429 (יותר מדי בקשות) חוסמת בקשות מהאפליקציה הנוכחית למשך תקופה שתיקבע. הקריאה ל-API נכשלת גם אם התגובה מהקונה שגויה. הדיווח על כשלים מועבר למי שקורא ל-API, שאחראי לנסות שוב בגלל כשלים זמניים (כמו מצב שבו השרת לא מגיב) או לטפל בכשלים קבועים (כמו כשלים באימות נתונים או שגיאות אחרות לא זמניות בתקשורת עם השרת).

אובייקט CustomAudienceFetchRequest מאפשר למתקשר ל-API להגדיר מידע מסוים לגבי הקהל בהתאמה אישית באמצעות המאפיינים האופציונליים שמוצגים בדוגמה. אם הערכים האלה מוגדרים בבקשה, הפלטפורמה לא יכולה לשנות אותם בתשובה של הקונה, ו-Protected Audience API מתעלם מהשדות בתשובה. אם הם לא מוגדרים בבקשה, צריך להגדיר אותם בתגובה, כי השדות האלה נדרשים ליצירת קהל בהתאמה אישית. ייצוג JSON של התוכן של CustomAudience, כפי שהוגדר באופן חלקי על ידי המתקשר ל-API, נכלל בבקשת ה-GET אל CustomAudience בכותרת מיוחדת X-CUSTOM-AUDIENCE-DATA.fetchUri הגודל של הטופס הסדרתי של הנתונים שצוינו עבור הקהל המותאם אישית מוגבל ל-8KB. אם הגודל חורג מהמגבלה, הקריאה ל-API fetchAndJoinCustomAudience נכשלת.

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

הערה לגבי הגדרה ואחסון של טוקן אימות

• הטוקן לא משמש לשום מטרה ב-Protected Audience API והוא אופציונלי.

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

יציאה מקהל בהתאמה אישית

הבעלים של קהל בהתאמה אישית יכול לבחור לעזוב על ידי קריאה ל-leaveCustomAudience(), כמו שמוצג בקטע הקוד הבא:

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

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

שליטת משתמשים

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

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

עדכונים מתוזמנים

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

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

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

ScheduleCustomAudienceUpdateRequest

public final class ScheduleCustomAudienceUpdateRequest {
  // Required Field
  @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

  // Required Field
  @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

  //  Required Field
  @NonNull public List<PartialCustomAudience> getPartialCustomAudienceList() {
    return mPartialCustomAudiences;
  }

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

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

• ‫UpdateUri: נקודת קצה של URI שאליה תישלח קריאת GET כדי לאחזר את העדכון. זהות הקונה נגזרת באופן מהותי מ-eTLD+1 ואין צורך לספק אותה באופן מפורש, ואי אפשר לשנות אותה בתגובת העדכון. בקשת ה-GET מצפה לקבל בחזרה אובייקט JSON שמכיל רשימה של אובייקטים מסוג customAudience.
• ‫DelayTime: הזמן שמציין את העיכוב מהזמן שבו מתבצעת קריאת ה-API של scheduleCustomAudienceUpdate() לתזמון העדכון.

• ‫PartialCustomAudience: ממשק ה-API מאפשר גם ל-SDK במכשיר לשלוח רשימה של קהלים בהתאמה אישית שנבנו באופן חלקי. כך ערכות ה-SDK באפליקציה יכולות למלא תפקיד כפול, משליטה מלאה ועד שליטה חלקית בניהול קהלים בהתאמה אישית, בהתאם לשותפות שלהן עם פלטפורמות DSP.

  • בנוסף, השינוי הזה שומר על תאימות של ה-API הזה ל-fetchAndJoinCustomAudience() API, שמאפשר שיתוף מידע דומה.

• ‫ShouldReplacePendingUpdates: ערך בוליאני שקובע אם לבטל עדכונים מתוזמנים בהמתנה ולהחליף אותם בעדכון שמפורט ב-ScheduleCustomAudienceUpdateRequest הנוכחי. אם הערך של המאפיין הזה הוא false ויש עדכונים קודמים שהקונה ביקש ועדיין נמצאים בהמתנה באותה אפליקציה, קריאה ל-scheduleCustomAudienceUpdate עם ScheduleCustomAudienceUpdateRequest תיכשל. ברירת המחדל היא false.

הרשאות שניתנות לאפליקציה ושליטה

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

• אפליקציה יכולה לנהל את השיוכים שלה לקהלים בהתאמה אישית.
• אפליקציה יכולה להעניק לפלטפורמות פרסום דיגיטלי של צד שלישי הרשאות לניהול קהלים מותאמים אישית בשמה.

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

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

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

• ספקי טכנולוגיות פרסום נרשמים לארגז החול לפרטיות ומספקים דומיין eTLD+1 שתואם לכל כתובות ה-URL של קהל מותאם אישית.
• ספקי טכנולוגיית פרסום יכולים לשתף פעולה עם אפליקציות או עם ערכות SDK כדי לספק אסימוני אימות שמשמשים לאימות של יצירת קהל מותאם אישית. כשמייפים את התהליך הזה לשותף, אפשר להגדיר שנדרש אישור מטכנולוגיית הפרסום כדי ליצור קהלים בהתאמה אישית.
• ספקי טכנולוגיות פרסום יכולים לבחור להשבית קריאות ל-joinCustomAudience בשם המשתמשים שלהם, ולאפשר רק ל-API של fetchAndJoinCustomAudience להפעיל את כל קהלי המתקשרים בהתאמה אישית. אפשר לעדכן את אמצעי הבקרה במהלך ההרשמה לארגז החול לפרטיות. שימו לב: האפשרות הזו מאפשרת להפעיל את כל הטכנולוגיות לפרסום או לא להפעיל אף אחת מהן. בגלל מגבלות הפלטפורמה, אי אפשר להגדיר הרשאות העברה על בסיס כל טכנולוגיית פרסום.

מודעות של מועמדים ותגובות למטא-נתונים

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

• מטא-נתונים: מטא-נתונים של מודעות ספציפיות לטכנולוגיות פרסום בצד הקונה. לדוגמה, יכול להיות שהמידע יכלול פרטים על הקמפיין הפרסומי וקריטריוני טירגוט כמו מיקום ושפה.
• כתובת URL של רכיב Rendering: נקודת קצה לעיבוד של נכס הקריאייטיב של המודעה.
• מסנן: מידע אופציונלי שנדרש ל-Protected Audience API כדי לסנן מודעות על סמך נתונים במכשיר. פרטים נוספים זמינים בקטע בנושא לוגיקת סינון בצד הקונה.

תהליך הבחירה של מודעות

ההצעה הזו נועדה לשפר את הפרטיות באמצעות Ad Selection API, שמנהל את ביצוע המכרז בפלטפורמות של טכנולוגיות פרסום.

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

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

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

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

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

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

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

אתחול תהליך בחירת המודעות

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

• בית העסק: מזהה של פלטפורמת הפרסום בצד המוכר, בפורמט eTLD+1
• כתובת ה-URL של לוגיקת ההחלטה: כשמתחיל מכרז על מודעה, הפלטפורמה משתמשת בכתובת ה-URL הזו כדי לאחזר קוד JavaScript מפלטפורמת הצד המוכר, כדי לתת ניקוד למודעה הזוכה.
• קונים של קהלים בהתאמה אישית: רשימה של פלטפורמות בצד הקונה עם ביקוש מבוסס-קהל בהתאמה אישית למכרז הזה, בפורמט eTLD+1.
• אותות לבחירת מודעות: מידע על המכרז (גודל המודעה, פורמט המודעה וכו').
• אותות של אתר מכירה: אותות ספציפיים לפלטפורמה בצד ההיצע.
• כתובת URL של אותות מהימנים לדירוג: כתובת URL של נקודת קצה של אות מהימן בצד המוכר, שממנה אפשר לאחזר מידע ספציפי בזמן אמת על נכסי קריאייטיב.
• אותות לכל קונה: פלטפורמות הביקוש שמשתתפות במכרז יכולות להשתמש בפרמטר הזה כדי לספק נתונים למכרז. לדוגמה, הפרמטר הזה יכול לכלול מידע הקשרי מקיף שימושי לקביעת הצעות מחיר.

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

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

הלוגיקה של הבידינג בצד הקונה

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

הפלטפורמה תשתמש במטא-נתונים של קהל בהתאמה אישית מסוג 'כתובת URL של לוגיקת בידינג' כדי לאחזר את קוד ה-JavaScript, שצריך לכלול את חתימת הפונקציה הבאה:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

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

הפונקציה מצפה לפרמטרים הבאים:

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

עלות הפרסום

בנוסף להצעת המחיר, פלטפורמות בצד הקונה יכולות להחזיר את העלות לקליק כחלק מ-generateBid(). לדוגמה:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

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

לוגיקת סינון בצד הקונה

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

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

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

לוגיקה של ניקוד בצד המוכר

הלוגיקה של הניקוד מסופקת בדרך כלל על ידי הפלטפורמה בצד המוכר. מטרת הקוד היא לקבוע מודעה מנצחת על סמך פלט של לוגיקת בידינג. יכול להיות שהמערכת תחיל לוגיקה עסקית נוספת כדי לקבוע את התוצאה. אם יש כמה ספקים של לוגיקת קבלת החלטות, המערכת לא מבטיחה את רצף הביצוע בין הספקים. הפלטפורמה תשתמש בפרמטר הקלט 'כתובת URL של לוגיקת ההחלטה' של selectAds() API כדי לאחזר את קוד ה-JavaScript שצריך לכלול את חתימת הפונקציה הבאה:

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

הפונקציה מצפה לפרמטרים הבאים:

• ‫Ad: המודעה שנבדקת. הפלט של הפונקציה generateBid().
• ‫Bid: סכום הצעת המחיר שמוחזר מהפונקציה generateBid().
• ‫Auction config: פרמטר קלט לשיטה selectAds().
• אותות מהימנים לדירוג: פלטפורמות פרסום דיגיטלי מסתמכות על נתונים בזמן אמת כדי לסנן ולדרג מודעות. לדוגמה, בעל אפליקציה יכול לחסום קמפיין פרסום מסוים כך שהמודעות שלו לא יוצגו באפליקציה. הנתונים האלה נשלפים מפרמטר כתובת ה-URL של אותות מהימנים לדירוג בהגדרות המכרז. השרת שמציג את הבקשה הזו צריך להיות שרת מהימן שמנוהל על ידי ספק טכנולוגיית פרסום.
• אותות הקשריים: יכול להיות שהם יכללו חותמת זמן גסה או מידע משוער על מיקום.
• אותות משתמש: יכול להיות שהאותות האלה יכללו מידע כמו חנות האפליקציות שממנה התחילה ההתקנה של האפליקציה.
• אות לזיהוי קהל בהתאמה אישית: אם המודעה שמקבלת ציון מגיעה מקהל בהתאמה אישית במכשיר, האות יכיל מידע כמו הקורא והשם של הקהל בהתאמה אישית.

זמן הריצה של קוד בחירת המודעות

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

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

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

שפת תכנות

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

רינדור מודעות מנצח

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

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

דיווח על חשיפות ואירועים

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

1. דיווח בצד המוכר.
2. דיווח על צד הקנייה.

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

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

‫Protected Audience מספק מנגנון להרשמה לאירועים עתידיים שקשורים למכרז שזכה, על ידי רישום של משואות. בפונקציית reportResult()JavaScript של מוֹכרים, פלטפורמות בצד המוכר יכולות לרשום משואות באמצעות הפונקציה registerAdBeacon() של הפלטפורמה. באופן דומה, פלטפורמות בצד הקנייה יכולות לקרוא לשיטה registerAdBeacon() מהפונקציה reportWin() JavaScript שלהן.

registerAdBeacon(beacons)

קלט:

• ‫event_key: מחרוזת שמציינת את סוג האינטראקציה שרוצים לרשום. הערך הזה משמש כמפתח לחיפוש נקודת הקצה שהפלטפורמה שולחת אליה פינג בזמן הדיווח על תוצאות המכרז.
• ‫reporting_url: כתובת ה-URL שבבעלות פלטפורמת הטכנולוגיה הפרסומית לטיפול באירוע.

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

דיווח בצד המוכר

הפלטפורמה מפעילה את פונקציית ה-JavaScript‏ reportResult() בקוד שסופק בצד הביקוש והורד מפרמטר כתובת ה-URL של לוגיקת ההחלטה של המוכר עבור API‏ selectAds():

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

פלט: אובייקט JSON שמכיל

• סטטוס: 0 אם הפעולה הצליחה, כל ערך אחר אם היא נכשלה.
• כתובת URL לדיווח: הפלטפורמה מפעילה את כתובת ה-URL הזו שמוחזרת מהפונקציה.
• אותות לקונה: אובייקט JSON שיועבר לreportWinפונקציה של הקונה.

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

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

דיווח בצד הקונים

הפלטפורמה מפעילה את פונקציית JavaScript‏ reportWin() בקוד שסופק בצד הביקוש והורד ממטא-נתוני כתובת ה-URL של לוגיקת הבידינג של הקהל המותאם אישית שמשויך למכרז.

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

קלט:

• הנתונים של auction_signals ושל per_buyer_signals נשלפים מ-AuctionConfig. כל מידע שפלטפורמת הקנייה צריכה להעביר לכתובת ה-URL של הדיווח יכול להגיע מהנתון הזה.
• ‫signals_for_buyer הוא הפלט של sell-side reportResult. כך הפלטפורמה בצד המוכר יכולה לשתף נתונים עם הפלטפורמה בצד הקונה לצורכי דיווח.
• contextual_signals מכיל מידע כמו שם האפליקציה וcustom_audience_signals מכיל את המידע על קהל היעד המותאם אישית. יכול להיות שבעתיד נוסיף עוד מידע.

פלט:

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

דיווח על אירועים

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

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

קלט:

• ‫ad_selection_id צריך להיות AdSelectionId של מכרז שהופעל לאחרונה שנשלף מ-AdSelectionOutcome.
• ‫event_key היא מחרוזת שמוגדרת בצד המוכר ומתארת את אירוע האינטראקציה.
• ‫event_data היא מחרוזת שמייצגת את הנתונים שמשויכים ל-event_key
• ‫reporting_destinations היא מסכת ביטים שמוגדרת באמצעות דגלים שסופקו על ידי הפלטפורמה. הערך יכול להיות FLAG_REPORTING_DESTINATION_SELLER או FLAG_REPORTING_DESTINATION_BUYER, או שניהם.
• ‫input_event (אופציונלי) משמש לשילוב עם Attribution Reporting API. זהו אובייקט InputEvent (לאירוע קליק) או null (לאירוע צפייה). פרטים נוספים על הפרמטר הזה זמינים במאמר בנושא שילוב של Attribution Reporting API.

אחרי ש-SDK בצד המוכר מפעיל את reportEvent, ובהתאם לדגל reporting_destinations, הפלטפורמה מנסה להתאים את event_key למפתחות שרשומים על ידי קונים ומוכרים בפונקציות JavaScript‏ reportWin ו-reportResult שלהם. אם יש התאמה, הפלטפורמה שולחת את ה-POST של event_data אל reporting_url המשויך. ה-content type של הבקשה הוא טקסט פשוט, והתוכן הוא event_data. הבקשה הזו נשלחת כמיטב היכולת, והיא נכשלת ללא הודעה במקרה של שגיאת רשת, תגובה של שגיאת שרת או אם לא נמצאו מפתחות תואמים.

שילוב של Attribution Reporting API

כדי לתמוך בקונים שמשתתפים במכרז בשילוב עם Protected Audience API, אנחנו מספקים פונקציונליות חוצת-API ב-Protected Audience API וב-Attribution Reporting API ‏ (ARA). הפונקציונליות הזו מאפשרת לטכנולוגיות פרסום להעריך את ביצועי השיוך שלהן בטקטיקות שונות של רימרקטינג, כדי להבין אילו סוגים של קהלים מניבים את החזר ה-ROI הגבוה ביותר.

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

• יוצרים מיפוי של מפתחות וערכים של כתובות URI לשימוש ב-1) דיווח על אינטראקציות עם מודעות ו-2) רישום מקורות.
• לכלול נתוני מכרז ממכרז Protected Audience במיפוי המפתחות בצד המקור לצורך דיווח על סיכום מצטבר (באמצעות Attribution Reporting API). מידע נוסף זמין בהצעת התכנון של ARA.

כשמשתמש רואה מודעה או לוחץ עליה:

• כתובת ה-URL שמשמשת לדיווח על האינטראקציות האלה עם האירועים באמצעות Protected Audience תספק לקונה את הנתונים הנדרשים כדי לרשום צפייה או קליק כמקור שעומד בדרישות באמצעות Attribution Reporting API.
• יכול להיות שהטכנולוגיה לפרסום מודעות תעביר את הערך CustomAudience (או מידע רלוונטי אחר על המודעה, כמו מיקום המודעה או משך הצפייה) באמצעות כתובת ה-URL הזו, כדי שהמטא-נתונים האלה יועברו לדוחות סיכום כשהטכנולוגיה לפרסום מודעות תבדוק את הביצועים המצטברים של הקמפיין.

הפעלת רישום של מקורות

‫reportEvent() תקבל פרמטר אופציונלי חדש InputEvent. קונים מנצחים שמפעילים את התכונה 'אותות מודעות' יכולים לבחור אילו דוחות מסוג reportEvent יירשמו באמצעות Attribution Reporting API כמקור רשום. כותרת הבקשה Attribution-Reporting-Eligible תתווסף לכל הבקשות לשליחת דוחות על אירועים מ-reportEvent(). כל התגובות עם כותרות ARA מתאימות ינותחו באותו אופן שבו מנותחת תגובה רגילה אחרת לרישום מקור ARA. במאמר בנושא Attribution Reporting API מוסבר איך לרשום כתובת URL של מקור.

מכיוון ש-ARA ב-Android תומך באירועי צפייה וקליק, נעשה שימוש ב-InputEvents כדי להבחין בין שני הסוגים. בדומה לרישום מקורות ב-ARA, ‏ reportEvent() API יפרש InputEvent שאומת על ידי הפלטפורמה כאירוע קליק. אם הערך של InputEvent חסר, null או לא תקין, הרישום של מקור התנועה ייחשב כצפייה.

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

דוגמה לדיווח על מעורבות והמרות

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

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

תהליך העבודה: לפני תחילת המכרז, הקונה שולח מזהה ייחודי למוכר כחלק מהצעת המחיר שלו בבידינג בזמן אמת (RTB). אפשר להגדיר את המזהה כמשתנה כמו auctionId. המזהה מועבר כ-perBuyerSignals ב-auctionConfig והוא זמין בלוגיקת הבידינג של הקונה.

1. במהלך ההפעלה של reportWin, הקונה יכול לרשום משואה של מודעה שתופעל במהלך זמן העיבוד של המודעה ובאירועי אינטראקציה ספציפיים (registerAdBeacon()). כדי לשייך אותות של מכרז לאירוע של מודעה, צריך להגדיר את auctionId כפרמטר של שאילתה בכתובת ה-URL של המשואה.
2. במהלך זמן העיבוד של המודעה, אפשר להפעיל את משואות ה-Beacon שרשמתם במהלך זמן המכרז או לשפר אותן באמצעות נתונים ברמת האירוע. המוֹכר צריך להפעיל את האירוע reportEvent() ולהעביר את הנתונים ברמת האירוע. הפלטפורמה תשלח פינג לכתובת ה-URL של משואת המודעה הרשומה של הקונה, שמתואמת עם reportEvent() שהופעל.
3. הקונה ירשום את המודעה ב-Attribution Reporting API בתגובה לבקשות של משואות המודעות עם הכותרת Attribution-Reporting-Register-Source. כדי לשייך אותות מכרז לאירוע המרה, מגדירים את auctionId בכתובת ה-URL של מקור הרישום.

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

תהליך עבודה דומה חל על מוֹכר שזקוק לגישה לנתוני שיוך, והמוֹכר יכול גם להשתמש במזהה ייחודי כדי לשלוח עם registerAdBeacon(). הקריאה reportEvent() מכילה נכס יעד שאפשר להשתמש בו כדי לשלוח את הדוח גם לקונה וגם למוכר.

שרת מהימן שמנוהל על ידי פלטפורמה של טכנולוגיית פרסום

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

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

צד הקונה: אחרי שצד הקונה מפעיל את לוגיקת הבידינג של צד הקונה, הפלטפורמה מבצעת אחזור HTTP של נתוני בידינג מהימנים מהשרת המהימן. כתובת ה-URL מורכבת מכתובת ה-URL וממפתחות שמופיעים במטא-נתונים של אותות מבידינג מהימן של הקהל המותאם אישית שעובר עיבוד. האחזור הזה מתבצע רק כשמעבדים מודעות מקהלים מותאמים אישית במכשיר. בשלב הזה, הצד הקונה יכול לאכוף תקציבים, לבדוק אם הקמפיין מושהה או לא מושהה, לבצע טירגוט וכו'.

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

https://www.kv-server.example/getvalues?keys=key1,key2

התגובה מהשרת צריכה להיות אובייקט JSON שהמפתחות שלו הם key1,‏ key2 וכו', והערכים שלו יהיו זמינים לפונקציות הבידינג של הקונה.

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

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

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

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

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

• אפשר לסמוך על ערך ההחזרה של השרת לכל מפתח, כי הוא מבוסס רק על המפתח הזה.
• השרת לא מבצע רישום ביומן ברמת האירוע.
• לשרת אין תופעות לוואי אחרות על סמך הבקשות האלה.

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

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