תמיכה בטירגוט לפי קהל בהתאמה אישית באמצעות 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 באפליקציות צריכים לשתף פעולה עם ספקי טכנולוגיית פרסום שיש להם נוכחות במכשיר, כמו שותפי מדידה לנייד (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 אל fetchUri בכותרת מיוחדת X-CUSTOM-AUDIENCE-DATA. הגודל של הטופס הסדרתי של הנתונים שצוינו עבור הקהל המותאם אישית מוגבל ל-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.

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

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

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

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

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

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

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

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

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

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

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

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

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

ההצעה הזו נועדה לשפר את הפרטיות באמצעות Ad Selection API (ממשק 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().
• הצעת מחיר: סכום הצעת המחיר שמוחזר מהפונקציה generateBid().
• ‫Auction config: פרמטר קלט לשיטה selectAds().
• אותות מהימנים לדירוג: פלטפורמות פרסום דיגיטלי מסתמכות על נתונים בזמן אמת כדי לסנן ולדרג מודעות. לדוגמה, בעל אפליקציה יכול לחסום קמפיין פרסום מסוים כך שהמודעות שלו לא יוצגו באפליקציה. הנתונים האלה נשלפים מפרמטר כתובת ה-URL של אותות מהימנים לדירוג, שמוגדר בהגדרות המכרז. השרת שמציג את הבקשה הזו צריך להיות שרת מהימן שמנוהל על ידי ספק טכנולוגיית פרסום.
• אותות הקשריים: יכול להיות שהם יכללו חותמת זמן גסה או מידע משוער על מיקום.
• אותות מהמשתמש: יכולים לכלול מידע כמו חנות האפליקציות שממנה התחילה ההתקנה של האפליקציה.
• אות לזיהוי קהל בהתאמה אישית: אם המודעה שמקבלת ציון מגיעה מקהל בהתאמה אישית במכשיר, הפרמטר הזה יכיל מידע כמו הקורא והשם של הקהל בהתאמה אישית.

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

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

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

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

שפת תכנות

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

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

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

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

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

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

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

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

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

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

registerAdBeacon(beacons)

קלט:

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

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

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

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

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 של מקור הרישום.

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

תהליך עבודה דומה חל על מוֹכר שצריך גישה לנתוני שיוך (Attribution), והמוֹכר יכול גם להשתמש במזהה ייחודי כדי לשלוח עם 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 ובאינטרנט.