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

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

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

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

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

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

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

ציר זמן

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

סקירה כללית

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

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

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

1. Custom Audience API: ה-API הזה מתמקד במושג המופשט 'קהל בהתאמה אישית', שמייצג קהל שהמפרסם הגדיר עם כוונות רכישה משותפות. פרטי הקהל נשמרים במכשיר, וניתן לשייך אותם למודעות מועמדות רלוונטיות לקהל ולמטא-נתונים שרירותיים, כמו אותות בידינג. אפשר להשתמש במידע הזה כדי להשפיע על הצעות המחיר של המפרסמים, על סינון המודעות ועל העיבוד שלהן.
2. Ad Selection 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 API ב-Chrome, ואי אפשר לשתף אותם בין האינטרנט לאפליקציות. כך אפשר להגביל את שיתוף פרטי המשתמשים.

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

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

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

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

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

הגישה המקובלת להגדרה ולתצורה של קהלים מותאמים אישית מבוססת בדרך כלל על טכנולוגיות ושילובים בצד השרת שמנוהלים על ידי ספקי טכנולוגיות פרסום בשותפות עם לקוחות ושותפים של סוכנויות ומפרסמים. Protected Audience API מאפשר להגדיר ולתעדף קהלים מותאמים אישית תוך שמירה על פרטיות המשתמשים. כדי להצטרף לקהל מותאם אישית, ספקי טכנולוגיית פרסום (ATP) של קונים שאין להם נוכחות של SDK באפליקציות צריכים לשתף פעולה עם ספקי טכנולוגיית פרסום שיש להם נוכחות במכשיר, כמו שותפי מדידה לנייד (MMP) ופלטפורמות לספקים (SSP). המטרה של Protected Audience API היא לתמוך ב-SDKs האלה על ידי מתן פתרונות גמישים לניהול קהלים בהתאמה אישית. ה-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, שבבעלות הקונה, משיבה עם אובייקט JSON מסוג CustomAudience בגוף התגובה. המערכת מתעלמת מהשדות 'קונה' ו'בעלים' של הקהל המותאם אישית (והם יאוכלסו באופן אוטומטי על ידי ה-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", ...
         ]
       }
     }
   },
   ...
 ]
}

ממשק ה-API של fetchAndJoinCustomAudience() קובע את זהות הקונה לפי ה-eTLD+1 של fetchUri. הזהות של הקונה ב-CustomAudience משמשת לביצוע אותן בדיקות של הרשמה והרשאה לאפליקציה שבוצעו על ידי joinCustomAudience(), ואי אפשר לשנות אותה בתגובה לאחזור. הבעלים של CustomAudience הוא שם החבילה של האפליקציה הקוראת. אין אימות אחר של fetchUri מלבד הבדיקה של eTLD+1, ובמיוחד אין בדיקה של k-anon. ה-API של fetchAndJoinCustomAudience() יוצר בקשת 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-anon מאפשר להשתמש ב-fetchUri לאימות הקונה ולשיתוף מידע בין הקונה ל-SDK. כדי לאפשר אימות של קהל מותאם אישית, הקונה יכול לספק אסימון אימות. ה-SDK במכשיר צריך לכלול את האסימון הזה ב-fetchUri כדי ש-endpoint שמתארח אצל הקונה יוכל לאחזר את התוכן של הקהל המותאם אישית ולהשתמש באסימון האימות כדי לוודא שהפעולה 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 לעיבוד: נקודת קצה לעיבוד הקריאייטיב של המודעה.
• סינון: מידע אופציונלי שנחוץ ל-Protected Audience API כדי לסנן מודעות על סמך נתונים במכשיר. פרטים נוספים זמינים בקטע לוגיקה של סינון בצד הקונה.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• מודעה: המודעה שנלקחת בחשבון על ידי קוד הבידינג בצד הקונה. זו תהיה מודעה מקהל בהתאמה אישית שעומד בדרישות
• אותות מכרזים: אותות ספציפיים לפלטפורמה בצד המוכר.
• Per buyer signals: צדדים של ביקוש שמשתתפים במכרז יכולים להשתמש בפרמטר הזה כדי לספק קלט למכרז. לדוגמה, הפרמטר הזה עשוי לכלול מידע מקיף על ההקשר ששימושי לקביעת הצעות המחיר.
• אותות בידינג מהימנים: פלטפורמות פרסום דיגיטלי מסתמכות על נתונים בזמן אמת כדי להחליט אילו מודעות לאחזר ולסמן אותן. לדוגמה, יכול להיות שהתקציב של קמפיין פרסום נגמר וצריך להפסיק את הצגת המודעות בו באופן מיידי. טכנולוגיית הפרסום יכולה להגדיר נקודת קצה של כתובת 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 של לוגיקה של החלטה' של ה-API selectAds() כדי לאחזר את קוד ה-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 לגבי מסגרות מוקפות).

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

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

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

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

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

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

registerAdBeacon(beacons)

קלט:

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

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

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

הפלטפורמה מפעילה את פונקציית ה-JavaScript reportResult() בקוד שסופק על ידי צד ההיצע, שהורדתם מהפרמטר Decision logic 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 הוא הפלט של 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. אם יש התאמה, הפלטפורמה שולחת את הערך של event_data באמצעות POST אל reporting_url המשויך. השדה content type בבקשה הוא טקסט פשוט, והגוף הוא השדה event_data. הבקשה הזו נשלחת כמיטב יכולת, והיא תיכשל ללא הודעה במקרה של שגיאת רשת, תגובה של שגיאת שרת או אם לא נמצאו מפתחות תואמים.

שילוב עם Attribution Reporting API

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

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

• יוצרים מפה של מפתח-ערך של מזהי URI שישמשו גם לדיווח על אינטראקציות עם מודעות וגם לרישום מקורות.
• לכלול את נתוני המכרזים מהמכרז של 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, ה-API של reportEvent() יטפל ב-InputEvent מאומת בפלטפורמה כאירוע קליקים. אם השדה InputEvent חסר, לא חוקי או null, רישום המקור ייחשב בתור תצוגה.

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

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

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

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

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

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

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

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

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

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

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

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

זוהי כתובת 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 ובאינטרנט.