דף זה תורגם על ידי Cloud Translation API.

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

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

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

Protected Audience נמצא בשלב בטא וזמין לבדיקה במכשירים ציבוריים!

עם Protected Audience אפשר:

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

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

ציר הזמן

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

תכונה	זמין בתצוגה המקדימה למפתחים	זמין בגרסת בטא
דיווח ברמת האירוע	רבעון 1 של שנת 2023	רבעון 3 של שנת 2023
תהליך בחירת הרשת (Mediation) ב-Waterfall	רבעון 1 של שנת 2023	רבעון 4 של שנת 2023
סינון מודעות להתקנת אפליקציות	רבעון 2 בשנת 2023	רבעון 3 של שנת 2023
סינון של מכסת תדירות	רבעון 2 בשנת 2023	רבעון 3 של שנת 2023
העברת מודעות לפי הקשר לתהליך העבודה לבחירת מודעות לצורך סינון	רבעון 2 בשנת 2023	רבעון 3 של שנת 2023
דיווח על אינטראקציות	רבעון 2 בשנת 2023	רבעון 3 של שנת 2023
הצטרפות להענקת גישה לקהלים בהתאמה אישית	רבעון 3 של שנת 2023	רבעון 4 של שנת 2023
חיוב ללא עלות לאלף חשיפות	רבעון 3 של שנת 2023	רבעון 4 של שנת 2023
שילוב שירותי בידינג ומכרזים	רבעון 3 של שנת 2023	רבעון 4 של שנת 2023
דיווח על ניפוי באגים	רבעון 3 של שנת 2023	רבעון 4 של שנת 2023
שילוב של דוחות שיוך (Attribution)	לא רלוונטי	רבעון 4 של שנת 2023
פתיחת תהליך בחירת הרשת (Mediation) בבידינג	רבעון 4 של שנת 2023	רבעון 4 של שנת 2023
ניהול מטבעות	רבעון 1 של שנת 2024	רבעון 2 של שנת 2024
שילוב K-anon	לא רלוונטי	רבעון 2 של שנת 2024
שילוב דוחות מצטבר	רבעון 3 של שנת 2024	רבעון 4 של שנת 2024

סקירה

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

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

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

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

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

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

SportinggoodsApp רוצה להזכיר למשתמשים שלו לרכוש פריטי מרצ'נדייז שנשארו בעגלת הקניות שלהם אם הם לא השלימו את הרכישה בתוך יומיים. Sporting GoodsApp משתמש ב-Custom Audience API כדי להוסיף את המשתמש לרשימת החברים בקהל מסוג 'מוצרים בעגלת הקניות'. הפלטפורמה מנהלת ושומרת את רשימת החברים בקהל במכשיר, ומגבילה את השיתוף עם צדדים שלישיים. SportinggoodsApp עובדת בשיתוף עם פלטפורמה פרסום דיגיטלי כדי להציג את המודעות שלה למשתמשים ברשימת החברים בקהל. פלטפורמת הפרסום הדיגיטלי מנהלת את המטא-נתונים של רשימות הקהלים ומספקת מודעות של מועמדים בבחירות, כך שאפשר יהיה להשתמש בהן בתהליך בחירת המודעות. אפשר להגדיר את הפלטפורמה כך שתתבצע אחזור תקופתי של מודעות מעודכנות שמבוססות על קהל ברקע. כך אפשר לשמור על רשימת המודעות של המועמדים שמבוססות על קהל היעד עדכניות, ללא קשר לבקשות שנשלחות לשרתי מודעות של צד שלישי במהלך ההזדמנות להצגת מודעה (כלומר, בקשה להצגת מודעה לפי הקשר).
כאשר משתמש ישחק במשחק FrisbeeGame באותו מכשיר, הוא עשוי לראות מודעה שמזכירה לו להשלים את רכישת הפריטים שנשארו בעגלת הקניות של SportinggoodsApp. כדי לעשות זאת, חברת FrisbeeGame (עם SDK משולב של מודעות) מפעילה את Ad Selection API כדי לבחור את המודעה הזוכה למשתמש על סמך כל רשימת חברים בקהל שאליה הוא שייך (בדוגמה הזו, הקהל בהתאמה אישית 'מוצרים בעגלת הקניות' שנוצר על ידי Sporting GoodsApp). ניתן להגדיר את תהליך העבודה לבחירת מודעות כדי להביא בחשבון מודעות שאוחזרו מהשרתים של פלטפורמות הפרסום הדיגיטלי, בנוסף למודעות במכשיר שמשויכות לקהלים בהתאמה אישית וגם לאותות אחרים במכשיר. כדי להשיג יעדי פרסום מתאימים, אפשר להתאים אישית את תהליך העבודה גם על ידי ה-SDK של המודעות ופלטפורמת הפרסום ב-Google Ads, כדי להשיג את יעדי הפרסום המתאימים. הגישה הזו מאפשרת למידע על תחומי העניין של המשתמשים או על האינטראקציות של המשתמשים באפליקציה כדי לבחור את המודעות, תוך הגבלת השיתוף של הנתונים האלה עם צדדים שלישיים.
ה-SDK של האפליקציה להצגת המודעות או של פלטפורמת הפרסום הדיגיטלי מעבד את המודעה שנבחרה.
הפלטפורמה מאפשרת דיווח על חשיפות ועל תוצאות של בחירת מודעות. יכולת הדיווח הזו משלימה ל-Attribution Reporting API. יכול להיות שפלטפורמות פרסום דיגיטלי מותאמות אישית על סמך צורכי הדיווח שלהן.

קבלת גישה ל-Protected Audience API דרך ממשקי API של Android

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

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

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

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

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

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

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

בעלים: שם החבילה של אפליקציית הבעלים. הוא מוגדר במרומז לשם החבילה של אפליקציית המתקשר/ת.
קונה: רשת המודעות של קונים שמנהלת מודעות עבור הקהל המותאם אישית הזה. הקונה מייצג גם את הגורם שעשוי לגשת לקהל בהתאמה אישית ולאחזר את פרטי המודעה הרלוונטיים. הקונה מצוין באמצעות הפורמט eTLD+1.
שם: שם או מזהה שרירותיים של הקהל בהתאמה אישית, כמו משתמש ש "נטשו את עגלת הקניות". המאפיין הזה יכול לשמש, למשל, לאחד מקריטריוני הטירגוט בקמפיינים של המפרסם, או למחרוזת שאילתה בכתובת ה-URL לאחזור קוד הבידינג.
מועד ההפעלה ומועד התפוגה: השדות האלה מגדירים את חלון הזמן שבו הקהל בהתאמה אישית ייכנס לתוקף. הפלטפורמה משתמשת במידע הזה כדי לבטל את החברות בקהל מותאם אישית. זמן התפוגה לא יכול לחרוג מחלון משך הזמן המקסימלי, כדי להגביל את משך החיים של קהל בהתאמה אישית.
כתובת URL לעדכון יומי: כתובת ה-URL שהפלטפורמה משתמשת בה כדי לאחזר מודעות של מועמדים ומטא-נתונים אחרים, שמוגדרים בשדות 'אותות של בידינג על ידי משתמשים' ו'אותות של בידינג מהימן' על בסיס קבוע. לפרטים נוספים עיינו בקטע על אחזור מודעות מועמדים לקהלים בהתאמה אישית.
אותות לבידינג של משתמשים: אותות ספציפיים לפלטפורמות של טכנולוגיות הפרסום לכל הצעת מחיר במודעות רימרקטינג. דוגמאות לאותות: המיקום המשוער של המשתמש, הלוקאל המועדף וכן הלאה.
נתונים מהימנות לבידינג: פלטפורמות של טכנולוגיות פרסום מסתמכות על נתונים בזמן אמת כדי לשפר את האחזור והציון של מודעות. לדוגמה, ייתכן שהתקציב של המודעה ייגמר וצריך להפסיק את הצגתה באופן מיידי. טכנולוגיית הפרסום יכולה להגדיר נקודת קצה (endpoint) של כתובת URL שממנה ניתן לאחזר את הנתונים בזמן אמת, ואת קבוצת המפתחות שבשבילה צריך לבצע את החיפוש בזמן אמת. השרת שיטפל בבקשה הזו יהיה שרת מהימן שמנוהל על ידי פלטפורמת הפרסום הדיגיטלי.
כתובת 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 הזה מאפשר לפונקציית קריאה חוזרת (caller) לציין את המועד שבו צריך לבצע את הקריאה ל-API, וכך לתת לטכנולוגיית הפרסום זמן נוסף לעבד אירועים ברמת האפליקציה ולקבוע לאילו קהלים מוגנים המשתמש צריך להצטרף או להסיר ממנו.

/**
* API To schedule delayed update events for Custom Audience
*
* @param delayedCustomUpdates List of Delayed Update events that trigger a
* call to DSP endpoint provided inside the DelayedCustomUpdate object
*/

public void scheduleCustomAudienceUpdates(
    @NonNull DelayedCustomUpdate delayedCustomAudienceUpdate,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

DelayedCustomAudienceUpdate

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

תרשים זרימה שמראה את התחלת תהליך בחירת המודעות.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

שפת תכנות

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

עיבוד המודעה הזוכה

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

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

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

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

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

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

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

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

registerAdBeacon(beacons)

קלט:

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

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

שילוב של Attribution Reporting API

כדי לתמוך בקונים שמשתתפים במכרז של Protected Audience API, אנחנו מספקים פונקציונליות של חוצה-ממשקי API בכל ממשקי Protected Audience ו-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. הקונים הזו שרושמים משׂואות רשת (beacon) של מודעות יכולים לבחור אילו דוחות reportEvent יירשמו בממשקי ה-API של Attribution Reporting בתור מקור רשום. כותרת הבקשה Attribution-Reporting-Eligible תתווסף לכל הבקשות לדיווח על אירועים שנשלחו מ-reportEvent(). תגובות עם כותרות ARA מתאימות ינותחו באותו אופן כמו כל תגובה רגילה אחרת של רישום מקור ב-ARA. במאמר רישום כתובת URL של מקור מוסבר איך משתמשים ב-Attribution Reporting API.

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

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

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

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

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

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

במהלך ההפעלה של reportWin, הקונה יכול לרשום שחיישן מודעה יופעל בזמן רינדור המודעה ובאירועי אינטראקציה ספציפיים (registerAdBeacon()). כדי לשייך אותות של מכרז לאירוע מודעה, צריך להגדיר את auctionId כפרמטר השאילתה בכתובת ה-URL של האיתות.
במהלך עיבוד המודעה, אפשר להפעיל או לשפר את משׂואות הרשת (beacon) שנרשמו בזמן המכרז באמצעות נתונים ברמת האירוע. אתר המכירה צריך להפעיל reportEvent() ולהעביר את הנתונים ברמת האירוע. הפלטפורמה תבצע פינג לכתובת ה-URL של חיישן המודעה הרשום של הקונה, שתואמת ל-reportEvent() שהופעל.
הקונה ירשום את המודעה ב-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 לעיבוד של קריאייטיבים:

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

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

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

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

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

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