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

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

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

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

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

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

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

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

ציר הזמן

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

שילוב עם Attribution Reporting API

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

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

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

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

• כתובת ה-URL שמשמש לדיווח על האינטראקציות עם האירועים האלה באמצעות 'קהל מוגן' תספק לקונה את הנתונים הנדרשים לצורך רישום צפייה או קליק כמקור מתאים באמצעות 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() ולהעביר את הנתונים ברמת האירוע. הפלטפורמה תשלח הודעה (ping) לכתובת ה-URL של משואת המודעות הרשומה של הקונה, שתואמת ל-reportEvent() שהופעל.
3. הקונה ירשום את המודעה ב-Attribution Reporting API על ידי מענה לבקשות של משואת המודעות באמצעות הכותרת Attribution-Reporting-Register-Source. כדי לשייך אותות מכרז לאירוע המרה, מגדירים את auctionId ב-Register source 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 ובאינטרנט.