סקירה כללית על דוחות השיוך (Attribution) לנייד

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

סקירה כללית

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

ל-API הזה יש מנגנונים מבניים שמספקים מסגרת לשיפור הפרטיות. בחלקים הבאים של הדף הזה מפורטים המנגנונים האלה:

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

‫Attribution Reporting API תומך בתרחישי השימוש הבאים:

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

ככלל, ה-Attribution Reporting API פועל באופן הבא, שמתואר בפירוט רב יותר בחלקים הבאים של המאמר הזה:

  1. טכנולוגיית הפרסום משלימה תהליך הרשמה כדי להשתמש ב-Attribution Reporting API.
  2. טכנולוגיית הפרסום רושמת מקורות שיוך – קליקים על מודעות או צפיות במודעות – באמצעות Attribution Reporting API.
  3. טכנולוגיית הפרסום רושמת טריגרים – המרות של משתמשים באפליקציה או באתר של המפרסם – באמצעות Attribution Reporting API.
  4. ‫Attribution Reporting API מתאים טריגרים למקורות שיוך (Attribution) – שיוך המרות – ושולח טריגר אחד או יותר אל מחוץ למכשיר באמצעות דוחות ברמת האירוע ודוחות נצברים אל ספקי טכנולוגיות פרסום.

קבלת גישה לממשקי Attribution Reporting API

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

רישום מקור שיוך (קליק או צפייה)

ב-Attribution Reporting API, קליקים על מודעות וצפיות במודעות נקראים מקורות שיוך. כדי לרשום קליק על מודעה או צפייה במודעה, קוראים לפונקציה registerSource(). ה-API הזה מצפה לפרמטרים הבאים:

  • ה-URI של מקור השיוך: הפלטפורמה שולחת בקשה ל-URI הזה כדי לאחזר מטא-נתונים שמשויכים למקור השיוך.
  • אירוע קלט: אובייקט InputEvent (לאירוע קליק) או null (לאירוע צפייה).

כש-API שולח בקשה ל-URI של מקור השיוך, טכנולוגיית הפרסום צריכה להגיב עם המטא-נתונים של מקור השיוך בכותרת HTTP חדשה Attribution-Reporting-Register-Source, עם השדות הבאים:

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

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

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

אם רוצים, תגובת המטא-נתונים של מקור השיוך יכולה לכלול נתונים נוספים בכותרת Attribution reporting redirects. הנתונים מכילים כתובות URL להפניה אוטומטית, שמאפשרות לכמה טכנולוגיות פרסום לרשום בקשה.

המדריך למפתחים כולל דוגמאות שמראות איך מאשרים רישום של מקור.

בדוגמה הבאה מוצג תהליך עבודה:

  1. ערכת ה-SDK של טכנולוגיית הפרסום שולחת קריאה ל-API כדי להתחיל את הרישום של מקור השיוך, ומציינת URI שה-API צריך לשלוח אליו קריאה:

    registerSource(
    Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
    myClickEvent);

  2. ה-API שולח בקשה אל https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA באמצעות אחת מהכותרות הבאות:

    <!-- For click events -->
Attribution-Reporting-Source-Info: navigation

<!-- For view events -->
Attribution-Reporting-Source-Info: event

  3. שרת ה-HTTPS של טכנולוגיית הפרסום הזו משיב עם כותרות שמכילות את הפרטים הבאים:

    Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "234",
    "expiry": "60000",
    "priority": "5"
}
Attribution-Reporting-Redirect:
https://adtechpartner1.example?their_ad_click_id=567
Attribution-Reporting-Redirect:
https://adtechpartner2.example?their_ad_click_id=890

  4. ה-API שולח בקשה לכל כתובת URL שצוינה ב-Attribution-Reporting-Redirect. בדוגמה הזו, מצוינות שתי כתובות URL של שותפים טכנולוגיים לפרסום, ולכן ה-API שולח בקשה אחת אל https://adtechpartner1.example?their_ad_click_id=567 ובקשה נוספת אל https://adtechpartner2.example?their_ad_click_id=890.

  5. שרת ה-HTTPS של טכנולוגיית הפרסום הזו משיב עם כותרות שמכילות את הפרטים הבאים:

    Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "789",
    "expiry": "120000",
    "priority": "2"
}

שלושה מקורות שיוך (Attribution) של ניווט (קליקים) נרשמים על סמך הבקשות שמוצגות בשלבים הקודמים.

רישום של מקור שיוך מ-WebView

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

מכיוון שטכנולוגיות פרסום משתמשות בקוד משותף באינטרנט וב-WebView, ‏ WebView עוקב אחרי הפניות אוטומטיות של HTTP 302 ומעביר את הרישומים התקינים לפלטפורמה. אנחנו לא מתכננים לתמוך בכותרת Attribution-Reporting-Redirect בתרחיש הזה, אבל אפשר לפנות אלינו אם יש לך תרחיש שימוש שמושפע מהשינוי.

רישום טריגר (המרה)

פלטפורמות טכנולוגיות פרסום יכולות לרשום טריגרים – המרות כמו התקנות או אירועים שמתרחשים אחרי ההתקנה – באמצעות השיטה registerTrigger().

השיטה registerTrigger() מצפה לפרמטר Trigger URI. ה-API שולח בקשה ל-URI הזה כדי לאחזר מטא-נתונים שמשויכים לטריגר.

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

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

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

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

  • מפתחות צבירה (אופציונלי): רשימה של מילונים שמציינים מפתחות צבירה ואת הדוחות שניתן לצבור את הערך שלהם.

  • ערכי צבירה (אופציונלי): רשימה של סכומים שמשויכים לכל מפתח.

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

אופציונלי: תגובת השרת של טכנולוגיית הפרסום עשויה לכלול נתונים נוספים בכותרת Attribution Reporting Redirects. הנתונים מכילים כתובות URL להפניה אוטומטית, שמאפשרות לכמה טכנולוגיות פרסום לרשום בקשה.

כמה טכנולוגיות פרסום יכולות לרשום את אותו אירוע הפעלה באמצעות הפניות אוטומטיות בשדה Attribution-Reporting-Redirect או באמצעות כמה קריאות לשיטה registerTrigger(). מומלץ להשתמש בשדה מפתח לביטול כפילויות כדי להימנע מהכללת טריגרים כפולים בדוחות במקרה שאותה טכנולוגיית פרסום מספקת כמה תגובות לאותו אירוע טריגר. מידע נוסף על השימוש במפתח לביטול כפילויות

המדריך למפתחים כולל דוגמאות שמראות איך לקבל רישום של טריגרים.

בדוגמה הבאה מוצג תהליך עבודה:

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

    registerTrigger(
    Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));

  2. ה-API שולח בקשה אל https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA.

  3. שרת ה-HTTPS של טכנולוגיית הפרסום הזו משיב עם כותרות שמכילות את הפרטים הבאים:

    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{
    "trigger_data": "1122",
    // This returns 010 for click-through conversions (CTCs) and 0 for
    // view-through conversions (VTCs) in reports
    "priority": "3",
    "deduplication_key": "3344"
    }],
}
Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567

  4. ה-API שולח בקשה לכל כתובת URL שצוינה ב-Attribution-Reporting-Redirect. בדוגמה הזו מצוינת רק כתובת URL אחת, ולכן ה-API שולח בקשה אל https://adtechpartner.example?app_install=567.

  5. שרת ה-HTTPS של טכנולוגיית הפרסום הזו משיב עם כותרות שמכילות את הפרטים הבאים:

    Attribution-Reporting-Register-Trigger: {
"event_trigger_data":[{
  "trigger_data": "5566",
  "priority": "3",
  "deduplication_key": "3344"
}]
}

    שני טריגרים נרשמים על סמך הבקשות בשלבים הקודמים.

יכולות שיוך

בקטעים הבאים מוסבר איך Attribution Reporting API מתאים טריגרים של המרות למקורות שיוך.

הוחל אלגוריתם שיוך לפי תעדוף המקור

‫Attribution Reporting API משתמש באלגוריתם שיוך עם עדיפות למקורות כדי להתאים טריגר (המרה) למקור שיוך.

פרמטרים של עדיפות מספקים דרכים להתאים אישית את השיוך של טריגרים למקורות:

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

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

מסנני טריגר

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

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

כדי לסנן טריגרים באופן סלקטיבי, טכנולוגיית הפרסום יכולה לציין נתוני סינון שכוללים מפתחות וערכים במהלך הרישום של מקור וטריגר. אם אותו מפתח מצוין גם למקור וגם לטריגר, המערכת מתעלמת מהטריגר אם החיתוך ריק. לדוגמה, מקור יכול לציין "product": ["1234"], כאשר product הוא מפתח המסנן ו-1234 הוא הערך. אם מסנן הטריגר מוגדר לערך "product": ["1111"], המערכת מתעלמת מהטריגר. אם אין מפתח מסנן טריגר שתואם ל-product, המערכת מתעלמת מהמסננים.

תרחיש נוסף שבו פלטפורמות טכנולוגיות פרסום עשויות לרצות לסנן טריגרים באופן סלקטיבי הוא כדי לכפות חלון תפוגה קצר יותר. במהלך רישום הטריגר, טכנולוגיית פרסום יכולה לציין (בשניות) חלון מבט לאחור ממועד ההמרה. לדוגמה, חלון מבט לאחור של 7 ימים יוגדר כך: "_lookback_window": 604800 // 7d

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

פלטפורמות טכנולוגיות פרסום יכולות גם לבחור נתוני טריגר על סמך נתוני אירועים ממקורות שונים. לדוגמה, הערך source_type נוצר אוטומטית על ידי ה-API כ-navigation או כ-event. במהלך רישום הטריגר, אפשר להגדיר את trigger_data כערך אחד עבור "source_type": ["navigation"] וכערך אחר עבור "source_type": ["event"].

טריגרים מוחרגים מדוחות ברמת האירוע אם מתקיים אחד מהתנאים הבאים:

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

שיוך אחרי ההתקנה

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

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

  • כשרושמים מקור שיוך, צריך לציין חלון שיוך להתקנות שבו צפויות התקנות (בדרך כלל 2-7 ימים, הטווח המקובל הוא 1-30 ימים). מציינים את חלון הזמן הזה כמספר שניות.
  • כשרושמים מקור שיוך (Attribution), מציינים חלון בלעדיות של שיוך אחרי התקנה, שבו כל אירועי הטריגר אחרי ההתקנה ישויכו למקור השיוך שהניב את ההתקנה (בדרך כלל 7-30 ימים, הטווח המקובל הוא 0 עד 30 ימים). מציינים את חלון הזמן הזה כמספר שניות.
  • ‫Attribution Reporting API מאמת מתי מתבצעת התקנה של אפליקציה, ובאופן פנימי משייך את ההתקנה למקור השיוך (Attribution) שקיבל עדיפות. עם זאת, ההתקנה לא נשלחת לטכנולוגיות פרסום ולא נספרת במסגרת מגבלות הקצב של הפלטפורמות.
  • אימות התקנת האפליקציה זמין לכל אפליקציה שהורדתם.
  • כל הטריגרים העתידיים שמתרחשים בחלון השיוך לאחר ההתקנה משויכים לאותו מקור שיוך כמו ההתקנה שאומתה, כל עוד מקור השיוך הזה עומד בדרישות.

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

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

אירוע היום שבו האירוע מתרחש הערות
קליק 1 1 ‫install_attribution_window מוגדר ל-172800 (יומיים), ו- ‫post_install_exclusivity_window מוגדר ל-864000 (10 ימים)
התקנה מאומתת 2 ה-API משייך באופן פנימי התקנות מאומתות, אבל ההתקנות האלה לא נחשבות לטריגרים. לכן, לא נשלחים דוחות בשלב הזה.
טריגר 1 (פתיחה ראשונה) 2 הטריגר הראשון שנרשם על ידי טכנולוגיית הפרסום. בדוגמה הזו, הוא מייצג פתיחה ראשונה, אבל יכול להיות כל סוג של טריגר.
משויך לקליק 1 (תואם לשיוך של התקנה מאומתת).
קליק 2 4 הערכים במאפיינים install_attribution_window ו-post_install_exclusivity_window זהים לאלה של קליק 1
טריגר 2 (אחרי ההתקנה) 5 הטריגר השני שנרשם על ידי טכנולוגיית הפרסום. בדוגמה הזו, הוא מייצג המרה אחרי התקנה, כמו רכישה.
משויך לקליק 1 (תואם לשיוך של התקנה מאומתת).
הקליק השני נפסל ולא נכלל בשיוך עתידי.

הרשימה הבאה כוללת הערות נוספות לגבי שיוך המרות אחרי התקנה:

  • אם ההתקנה המאומתת לא מתרחשת תוך מספר הימים שצוין על ידי install_attribution_window, לא מוחל שיוך להתקנה.
  • התקנות מאומתות לא נרשמות על ידי טכנולוגיות פרסום ולא נשלחות בדוחות. הן לא נספרות במגבלות הקצב של טכנולוגיות פרסום. התקנות מאומתות משמשות רק לזיהוי מקור השיוך שזוכה לקרדיט על ההתקנה.
  • בדוגמה מהטבלה הקודמת, trigger 1 ו-trigger 2 מייצגים פתיחה ראשונה והמרה לאחר התקנה, בהתאמה. עם זאת, פלטפורמות טכנולוגיות פרסום יכולות לרשום כל סוג של טריגר. במילים אחרות, הטריגר הראשון לא חייב להיות טריגר של פתיחה ראשונה.
  • אם נרשמו עוד טריגרים אחרי ש-post_install_exclusivity_window פג, הקליק 1 עדיין עומד בדרישות לשיוך, בהנחה שהוא לא פג ולא הגיע למגבלות התדירות שלו.
    • יכול להיות שקליק 1 עדיין יאבד או יימחק אם נרשם מקור שיוך בעדיפות גבוהה יותר.
  • אם האפליקציה של המפרסם מוסרת ומוחזרת, ההתקנה מחדש נספרת כהתקנה מאומתת חדשה.
  • אם קליק 1 היה אירוע צפייה, עדיין ישויכו אליו גם הטריגרים של 'פתיחה ראשונה' וגם הטריגרים של אירועים אחרי ההתקנה. ה-API מגביל את השיוך לטריגר אחד לכל צפייה, למעט במקרה של שיוך לאחר התקנה, שבו מותרים עד שני טריגרים לכל צפייה. במקרה של שיוך לאחר התקנה, יכול להיות שספק הטכנולוגיה לפרסום יקבל 2 חלונות דיווח שונים (אחרי יומיים או אחרי תפוגה של מקור).

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

‫Attribution Reporting API מאפשר שיוך של נתיבי הטריגר הבאים במכשיר Android יחיד:

  • App-to-app: המשתמש רואה מודעה באפליקציה, ואז משלים המרה באותה אפליקציה או באפליקציה אחרת שהותקנה.
  • App-to-web: המשתמש רואה מודעה באפליקציה ואז משלים המרה בדפדפן בנייד או בדפדפן אינטרנט.
  • Web-to-app: המשתמש רואה מודעה בדפדפן בנייד או בדפדפן אינטרנט, ואז משלים המרה באפליקציה.
  • Web-to-web: המשתמש רואה מודעה בדפדפן בנייד או בדפדפן אינטרנט, ואז משלים המרה באותו דפדפן או בדפדפן אחר באותו מכשיר.

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

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

תעדוף של כמה טריגרים למקור שיוך יחיד

מקור שיוך יחיד יכול להוביל לכמה טריגרים. לדוגמה, תהליך רכישה יכול לכלול את הטריגר app install (התקנת אפליקציה), טריגר אחד או יותר מסוג add-to-cart (הוספה לעגלת קניות) וטריגר מסוג purchase (רכישה). כל טריגר משויך למקור שיוך אחד או יותר בהתאם לאלגוריתם השיוך לפי תעדוף המקור, שמתואר בהמשך הדף.

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

במקרים שבהם יש כמה טריגרים מעבר למגבלות האלה, כדאי להוסיף לוגיקה של תעדוף כדי לקבל בחזרה את הטריגרים הכי חשובים. לדוגמה, המפתחים של טכנולוגיית פרסום עשויים לתעדף הפעלות של אירוע מסוג purchase על פני הפעלות של אירוע מסוג add-to-cart.

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

מתן הרשאה למספר ספקי טכנולוגיות פרסום לרשום מקורות או טריגרים של שיוך (Attribution)

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

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

  • הגדרת שרת פנימי לרישום ולקבלת דוחות מ-API.
  • להמשיך להשתמש בשותף קיים למדידת ביצועים בנייד.

מקורות שיוך (Attribution)

הפניות אוטומטיות ממקור השיוך נתמכות בשיטה registerSource():

  1. טכנולוגיית הפרסום שמפעילה את השיטה registerSource() יכולה לספק שדה Attribution-Reporting-Redirect נוסף בתגובה שלה, שמייצג את קבוצת כתובות ה-URL להפניה אוטומטית של טכנולוגיית הפרסום של השותף.
  2. לאחר מכן, ה-API קורא לכתובות ה-URL להפניה אוטומטית כדי שספקי טכנולוגיות הפרסום השותפים יוכלו לרשום את מקור השיוך.

אפשר לציין כמה כתובות URL של טכנולוגיות פרסום של שותפים בשדה Attribution-Reporting-Redirect, וטכנולוגיות פרסום של שותפים לא יכולות לציין את השדה Attribution-Reporting-Redirect שלהן.

בנוסף, ה-API מאפשר לטכנולוגיות פרסום שונות לבצע קריאות שונות ל-registerSource().

טריגרים

גם תגים של צד שלישי נתמכים באופן דומה ברישום של טריגרים: חברות AdTech יכולות להשתמש בשדה הנוסף Attribution-Reporting-Redirect או להפעיל כל אחת את השיטה registerTrigger().

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

טיפול בטריגרים כפולים

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

  • המשתמש מבצע את אותה פעולה (טריגר) כמה פעמים. לדוגמה, המשתמש מעיין באותו מוצר כמה פעמים באותו חלון דיווח.
  • האפליקציה של המפרסם משתמשת בכמה ערכות SDK למעקב המרות, שכולן מפנות לטכנולוגיית פרסום זהה. לדוגמה, האפליקציה של המפרסם משתמשת בשני שותפי מדידה, MMP מספר 1 ו-MMP מספר 2. שני פלטפורמות ה-MMP מפנות לטכנולוגיית פרסום מספר 3. כשמופעל טריגר, שתי הפלטפורמות לניהול מדיה לנייד רושמות את הטריגר הזה ב-Attribution Reporting API. טכנולוגיית הפרסום מספר 3 מקבלת שתי הפניות אוטומטיות נפרדות – אחת מ-MMP מספר 1 ואחת מ-MMP מספר 2 – לאותו טריגר.

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

שיטה מומלצת: מפתח לביטול כפילויות

השיטה המומלצת היא שאפליקציית המפרסם תעביר מפתח ייחודי לביטול כפילויות לכל טכנולוגיות הפרסום או ערכות ה-SDK שבהן היא משתמשת למדידת המרות. כשמתרחשת המרה, האפליקציה מעבירה מפתח לביטול כפילויות לטכנולוגיות הפרסום או ל-SDK. לאחר מכן, טכנולוגיות הפרסום או ערכות ה-SDK האלה ממשיכות להעביר את מפתח ביטול הכפילויות להפניות באמצעות פרמטר בכתובות ה-URL שצוינו ב-Attribution-Reporting-Redirect.

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

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

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

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

טכנולוגיות פרסום שיוזמות את הקריאה לרישום הטריגר – למשל, SDK – כוללות פרמטר בכתובות ה-URL שצוינו ב-Attribution-Reporting-Redirect, כמו duplicate_trigger_id. הפרמטר duplicate_trigger_id יכול לכלול מידע כמו שם ה-SDK וסוג הטריגר של המפרסם. טכנולוגיות פרסום יכולות לשלוח קבוצת משנה של הטריגרים הכפולים האלה לדוחות ברמת האירוע. טכנולוגיות פרסום יכולות לכלול את duplicate_trigger_id הזה גם במפתחות הצבירה שלהן.

דוגמה לשיוך (Attribution) חוצה-פלטפורמות

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

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

ברשימה הבאה מפורטות סדרות היפותטיות של פעולות משתמשים שכל אחת מהן מתרחשת בהפרש של יום, ואיך Attribution Reporting API מטפל בפעולות האלה בהקשר של טכנולוגיית פרסום א', טכנולוגיית פרסום ב' ו-MMP:

יום 1: משתמש לוחץ על מודעה שמוצגת על ידי טכנולוגיית פרסום א'

טכנולוגיית פרסום א' מתקשרת אל registerSource() באמצעות ה-URI שלה. ה-API שולח בקשה ל-URI, והקליק נרשם עם המטא-נתונים מתגובת השרת של טכנולוגיית הפרסום א'.

טכנולוגיית הפרסום א' כוללת גם את ה-URI של ה-MMP בכותרת Attribution-Reporting-Redirect. ה-API שולח בקשה ל-URI של MMP, והקליק נרשם עם המטא-נתונים מתגובת השרת של MMP.

יום 2: משתמש לוחץ על מודעה שמוצגת על ידי טכנולוגיית פרסום ב'

ספק טכנולוגיות פרסום ב' מתקשר אל registerSource() עם ה-URI שלו. ה-API שולח בקשה ל-URI, והקליק נרשם עם המטא-נתונים מהתגובה של שרת טכנולוגיית הפרסום ב'.

בדומה לטכנולוגיית הפרסום א', גם טכנולוגיית הפרסום ב' כללה את ה-URI של MMP בכותרת Attribution-Reporting-Redirect. ה-API שולח בקשה ל-URI של ה-MMP, והקליק נרשם עם המטא-נתונים מהתגובה של השרת של ה-MMP.

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

התשובה של ה-API זהה לתשובה שהתקבלה ביום הראשון, אבל נרשם צפייה בטכנולוגיית הפרסום א' וב-MMP.

יום 4: המשתמש מתקין את האפליקציה, שמשתמשת ב-MMP למדידת המרות

פלטפורמת ה-MMP מתקשרת אל registerTrigger() באמצעות ה-URI שלה. ה-API שולח בקשה לכתובת ה-URL, וההמרה נרשמת עם המטא-נתונים מהתגובה של השרת של MMP.

פלטפורמת ה-MMP כוללת גם את כתובות ה-URI של טכנולוגיית פרסום א' וטכנולוגיית פרסום ב' בכותרת Attribution-Reporting-Redirect. ה-API שולח בקשות לשרתים של טכנולוגיית פרסום א' וטכנולוגיית פרסום ב', וההמרה נרשמת בהתאם למטא-נתונים מהתשובות של השרתים.

בתרשים הבא מוצג התהליך שמתואר ברשימה שלמעלה:

דוגמה לאופן שבו ה-Attribution Reporting API מגיב לסדרה של פעולות משתמש.

כך פועל השיוך (Attribution):

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

שיוך (Attribution) חוצה-פלטפורמות ללא הפניות אוטומטיות

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

תרשים זרימה ברמה גבוהה

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

הרשמה של מקור

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

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

רישום טריגר

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

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

שיוך (Attribution)

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

  • המשתמש לחץ על מודעות שהוצגו על ידי טכנולוגיות פרסום A,‏ B,‏ C ו-D. לאחר מכן המשתמש התקין את האפליקציה של המפרסם, שמשתמשת בשותף טכנולוגיית פרסום למדידה (MMP).
  • טכנולוגיית הפרסום א' מפנה את המקורות שלה אל ה-MMP.
  • טכנולוגיות הפרסום B ו-C לא מבצעות הפניה אוטומטית, אבל הן משתפות את מפתחות הצבירה שלהן.
  • טכנולוגיית הפרסום D לא מבצעת הפניה או משתפת מפתחות צבירה.

ה-MMP רושם מקור מטכנולוגיית פרסום א', ומגדיר הגדרת שיוך (Attribution) שכוללת את טכנולוגיית פרסום ב' ואת טכנולוגיית פרסום ד'.

השיוך ל-MMP כולל עכשיו:

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

השיוך ל-MMP לא כולל:

  • טכנולוגיית הפרסום C, כי פלטפורמת ה-MMP לא כללה אותה בהגדרת השיוך שלה.
  • טכנולוגיית הפרסום D, כי היא לא ביצעה הפניה או שיתפה מפתחות צבירה.

ניפוי באגים

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

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

  • מדידה באפליקציה שבה מותר להשתמש ב-AdId
  • מדידה של מעבר מאפליקציה לאתר במקרים שבהם מותר להשתמש ב-AdID ומתבצעת התאמה בין מקור התנועה באפליקציה לבין הטריגר באתר
  • מדידה מאתר לאתר (באותה אפליקציית דפדפן) כשהפרמטר ar_debug` מופיע גם במקור וגם בטריגר

גילוי מפתחות לשיוך חוצה-פלטפורמות ללא הפניות אוטומטיות

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

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

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

עם ההשקה של תכונת גילוי המפתחות:

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

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

הפניות אוטומטיות בשרשרת

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

בתגובת השרת, טכנולוגיית הפרסום יכולה גם לכלול כותרת אחת של Location (הפניה אוטומטית 302) עם כתובת URL, שבתורה מובילה לרישום נוסף, עד למגבלה מוגדרת.

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

הפניות אוטומטיות לא מתקבלות עבור registerWebSource ו-registerWebTrigger שמשמשים דפדפנים. פרטים נוספים זמינים במדריך להטמעה באתרים ובאפליקציות.

הצגת נתוני מדידה בדוחות שיוך

‫Attribution Reporting API מאפשר ליצור את סוגי הדוחות הבאים, שמתוארים בפירוט בהמשך הדף:

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

שני סוגי הדוחות האלה משלימים זה את זה ואפשר להשתמש בהם בו-זמנית.

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

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

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

הדוח ברמת האירוע מכיל נתונים כמו:

  • יעד: שם חבילת האפליקציה של המפרסם או eTLD+1 שבו הופעל הטריגר
  • מזהה מקור השיוך: אותו מזהה מקור שיוך ששימש לרישום מקור שיוך
  • סוג הטריגר: 1 או 3 ביטים של נתוני טריגר ברמת מהימנות נמוכה, בהתאם לסוג מקור השיוך

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

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

מגבלות על מספר הטכנולוגיות הפרסומיות

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

  • ‫100 טכנולוגיות פרסום עם מקורות שיוך לכל {source app, destination app, 30 days, device}.
  • ‫10 טכנולוגיות פרסום עם טריגרים שמשויכים לכל {אפליקציית מקור, אפליקציית יעד, 30 ימים, מכשיר}.
  • 20 ספקי טכנולוגיות פרסום יכולים לרשום מקור שיוך או טריגר יחיד (באמצעות Attribution-Reporting-Redirect)

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

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

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

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

מקור דיווח אחד לכל אפליקציית מקור בכל יום

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

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

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

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

תקופת צינון והגבלות קצב

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

ההצעה הנוכחית היא להגביל כל טכנולוגיית פרסום ל-100 טריגרים משויכים לכל {אפליקציית מקור, אפליקציית יעד, 30 ימים, מכשיר}.

מספר היעדים הייחודיים

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

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

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

הדיוק של נתוני הטריגר מוגבל

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

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

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

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

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

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

\[ p = \frac{k}{k + e^ε - 1} \]

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

  • ‫p=0.24% למקורות תנועה
  • ‫p=0.00025% למקורות אירועים

מגבלות על טריגרים זמינים (המרות)

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

  • ‫1-2 טריגרים למקורות שיוך של צפייה במודעה (2 טריגרים זמינים רק במקרה של שיוך לאחר התקנה)
  • 3 טריגרים למקורות ייחוס של מודעות לקליקים

חלונות זמן ספציפיים לשליחת דוחות (התנהגות ברירת מחדל)

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

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

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

הגדרה גמישה ברמת האירוע

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

הגמישות הנוספת הזו תוטמע ב-Attribution Reporting API בשני שלבים:

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

אפשר להשתמש בשלב 1 (גמיש ברמת האירוע, גרסה Lite) כדי:

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

שלב 2 (גמישות מלאה ברמת האירוע) מאפשר לבצע את כל הפעולות בשלב 1 וגם:

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

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

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

  • מקסימום 20 דוחות בסך הכול, באופן גלובלי ולכל trigger_data
  • מקסימום 5 חלונות דיווח אפשריים לכל trigger_data
  • מקסימום 32 עוצמות של נתוני טריגר (לא רלוונטי לשלב 1: Lite ברמת האירוע)

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

דוחות שניתן לצבור

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

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

  • דוחות לגבי ערכי טריגר, כמו הכנסה
  • טיפול בסוגים נוספים של טריגרים

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

התרשים הבא מציג את העיצוב הכללי של תהליך ההכנה והשליחה של דוחות מצטברים באמצעות Attribution Reporting API:

  1. המכשיר שולח לספקי טכנולוגיית פרסום דוחות מוצפנים עם נתונים שאפשר לצבור. בסביבת ייצור, ספקי טכנולוגיית פרסום לא יכולים להשתמש בדוחות האלה ישירות.
  2. ספק טכנולוגיית הפרסום שולח חבילה של דוחות עם נתונים שאפשר לצבור אל Aggregation Service לצורך צבירה.
  3. ‫Aggregation Service קורא חבילה של דוחות שאפשר לצבור, מפענח אותם וצובר אותם.
  4. הנתונים המצטברים הסופיים נשלחים בחזרה לטכנולוגיית הפרסום בדוח סיכום.
התהליך שבו משתמשים ב-Attribution Reporting API כדי להכין ולשלוח דוחות שניתן לצבור.

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

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

שירותי צבירה

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

השירותים האלה מנוהלים על ידי גורמים שונים, שמתוארים בפירוט בהמשך הדף:

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

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

שירות הצבירה הזה פועל בסביבת מחשוב אמינה (TEE) שמתארחת בענן. סביבת TEE מציעה את יתרונות האבטחה הבאים:

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

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

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

שירות ניהול מפתחות

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

התחשבות בדוחות שניתן לצבור

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

Aggregatable Reports API

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

רישום של נתוני המקור שניתן לצבור

כשממשק ה-API שולח בקשה ל-URI של מקור השיוך, טכנולוגיית הפרסום יכולה לרשום רשימה של מפתחות צבירה, שנקראים histogram_contributions, בתגובה עם שדה חדש שנקרא aggregation_keys בכותרת ה-HTTP ‏Attribution-Reporting-Register-Source, כאשר המפתח הוא key_name והערך הוא key_piece:

  • ‫(Key) שם המפתח: מחרוזת לשם המפתח. משמש כמפתח לאיחוד עם מפתחות בצד הטריגר כדי ליצור את המפתח הסופי.
  • (ערך) חלק מהמפתח: ערך של מחרוזת ביטים של המפתח.

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

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

מידע נוסף על המבנה של מפתחות צבירה ועל אופן ההגדרה שלהם

בדוגמה הבאה, טכנולוגיית פרסום משתמשת ב-API כדי לאסוף את הנתונים הבאים:

  • צבירה של ספירות המרות ברמת הקמפיין
  • צבירה של ערכי רכישה ברמה גיאוגרפית
// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

רישום טריגרים שניתן לצבירה

רישום טריגר כולל שני שדות נוספים.

השדה הראשון משמש לרישום של רשימת מפתחות מצטברים בצד של הטריגר. טכנולוגיית הפרסום צריכה להשיב עם השדה aggregatable_trigger_data בכותרת HTTP‏ Attribution-Reporting-Register-Trigger, עם השדות הבאים לכל מפתח מצטבר ברשימה:

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

השדה השני משמש לרישום רשימת ערכים שצריכים לתרום לכל מפתח. טכנולוגיית הפרסום צריכה להשיב עם השדה aggregatable_values בכותרת HTTP Attribution-Reporting-Register-Trigger. השדה השני משמש לרישום רשימה של ערכים שצריכים לתרום לכל מפתח, שיכולים להיות מספרים שלמים בטווח $ [1, 2^{16}] $.

כל טריגר יכול לתרום כמה תרומות לדוחות הניתנים לצבירה. הסכום הכולל של התרומות לכל אירוע מקור נתון מוגבל על ידי פרמטר של $ L1 $, שהוא הסכום המקסימלי של התרומות (הערכים) בכל המפתחות המצטברים של מקור נתון מסוים. ‫‎$ L1 $ מתייחס לרגישות או לנורמה L1 של התרומות להיסטוגרמה לכל אירוע מקור. חריגה מהמגבלות האלה תגרום לכך שתוספות עתידיות יוסרו ללא הודעה. ההצעה הראשונית היא להגדיר את $ L1 $ ל-$ 2^{16} $ (65536).

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

בדוגמה הבאה, תקציב הפרטיות מחולק באופן שווה בין campaignCounts לבין geoValue על ידי חלוקת התרומה של ‎ $ L1 $ לכל אחד מהם:

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

בדוגמה הקודמת נוצרות התרומות הבאות להיסטוגרמה:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

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

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

פרטיות דיפרנציאלית

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

\[ Laplace(\frac{L1}{ε}) \]

שילוב של Protected Audience API ו-Attribution Reporting API

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

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

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

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

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

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

דוגמאות לשיוך, לדיווח ולעדיפות של רישום

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

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

נניח שמשתמש מבצע את הפעולות הבאות:

  1. המשתמש רואה מודעה. טכנולוגיית הפרסום רושמת מקור שיוך ב-API, עם עדיפות של 0 (צפייה מס' 1).
  2. המשתמש רואה מודעה שנרשמה עם עדיפות של 0 (צפייה מס' 2).
  3. המשתמש לוחץ על מודעה שנרשמה עם עדיפות של 1 (קליק מספר 1).
  4. המשתמש מבצע המרה (מגיע לדף הנחיתה) באפליקציה של המפרסם. טכנולוגיית הפרסום רושמת טריגר ב-API, עם עדיפות של 0 (ההמרה מספר 1).
    • כשהטריגרים נרשמים, ה-API מבצע שיוך לפני שהוא יוצר דוחות.
    • יש 3 מקורות שיוך זמינים: צפייה מס' 1, צפייה מס' 2 וקליק מס' 1. ה-API משייך את הטריגר הזה לקליק מספר 1 כי הוא בעדיפות הכי גבוהה והוא הכי עדכני.
    • התצוגה מספר 1 והתצוגה מספר 2 נפסלות ולא יכולות יותר להיכלל בשיוך עתידי.
  5. המשתמש מוסיף פריט לעגלת הקניות באפליקציה של המפרסם, שרשומה עם עדיפות של 1 (המרה מספר 2).
    • קליק מספר 1 הוא מקור הייחוס היחיד שעומד בדרישות. מאפייני ה-API שמפעילים את הטריגר הזה.
  6. המשתמש מוסיף פריט לעגלת הקניות באפליקציה של המפרסם, שנרשמה עם עדיפות של 1 (המרה מספר 3).
    • קליק מספר 1 הוא מקור הייחוס היחיד שעומד בדרישות. מאפייני ה-API שמפעילים את הטריגר הזה.
  7. המשתמש מוסיף פריט לעגלת הקניות באפליקציה של המפרסם, שנרשמה עם עדיפות של 1 (המרה מספר 4).
    • קליק מספר 1 הוא מקור הייחוס היחיד שעומד בדרישות. מאפייני ה-API שמפעילים את הטריגר הזה.
  8. המשתמש מבצע רכישה באפליקציה של המפרסם, שנרשמה עם עדיפות של 2 (המרה מספר 5).
    • קליק מספר 1 הוא מקור הייחוס היחיד שעומד בדרישות. מאפייני ה-API שמפעילים את הטריגר הזה.

המאפיינים של דוחות ברמת האירוע:

  • כברירת מחדל, 3 הטריגרים הראשונים שמשויכים לקליק והטריגר הראשון שמשויך לצפייה נשלחים אחרי חלונות הדיווח הרלוונטיים.
  • בחלון הדיווח, אם יש טריגרים שרשומים עם עדיפות גבוהה יותר, הם מקבלים עדיפות ומחליפים את הטריגר האחרון.
  • בדוגמה הקודמת, טכנולוגיית הפרסום מקבלת 3 דוחות אירועים אחרי חלון הדיווח של יומיים, לגבי המרה מספר 2, המרה מספר 3 והמרה מספר 5.
    • כל 5 הטריגרים משויכים לקליק מספר 1. כברירת מחדל, ה-API ישלח דוחות לגבי 3 הטריגרים הראשונים: המרה מספר 1, המרה מספר 2 והמרה מספר 3.
    • עם זאת, העדיפות של המרה מספר 4 (1) גבוהה יותר מהעדיפות של המרה מספר 1 (0). דוח האירועים של המרה מספר 4 מחליף את דוח האירועים של המרה מספר 1 ונשלח.
    • בנוסף, העדיפות של המרה מספר 5 (2) גבוהה יותר מכל טריגר אחר. דוח האירוע של המרה מספר 5 מחליף את הדוח של המרה מספר 4 כדי להישלח.

דוחות שניתן לצבור כוללים את המאפיינים הבאים:

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

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

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

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

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

דוחות זמניים לניפוי באגים

‫Attribution Reporting API הוא ממשק חדש ומורכב למדי למדידת שיוך (Attribution) ללא מזהים חוצי-אפליקציות. לכן, אנחנו תומכים במנגנון מעבר כדי לקבל מידע נוסף על דוחות שיוך כשהמזהה לפרסום זמין (המשתמש לא ביטל את ההסכמה להתאמה אישית באמצעות המזהה לפרסום, והאפליקציה של בעל התוכן הדיגיטלי או המפרסם הצהירה על הרשאות AdID). כך אפשר להבין את ה-API באופן מלא במהלך ההשקה, לעזור בניפוי באגים ולהשוות בקלות רבה יותר את הביצועים לחלופות שמבוססות על מזהה פרסום. יש שני סוגים של דוחות ניפוי באגים: attribution-success ו-verbose.

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

דוחות ניפוי באגים של שיוך להמרות

גם מקורות וגם טריגרים של רישום מקבלים שדה חדש של 64 ביט debug_key (בפורמט מחרוזת), שמאוכלס על ידי טכנולוגיית הפרסום. הפרמטרים source_debug_key ו-trigger_debug_key מועברים ללא שינוי בדוחות ברמת האירוע ובדוחות המצטברים.

אם דוח נוצר עם מפתחות ניפוי באגים של מקור ושל טריגר, נשלח דוח ניפוי באגים כפול עם עיכוב מוגבל לנקודת קצה .well-known/attribution-reporting/debug/report-event-attribution. דוחות הניפוי באגים זהים לדוחות רגילים, כולל שדות מפתח לניפוי באגים. הכללת המפתחות האלה בשני המקומות מאפשרת לקשר בין דוחות רגילים לבין הזרם הנפרד של דוחות ניפוי הבאגים.

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

דוחות מפורטים של ניפוי באגים

דוחות מפורטים של ניפוי באגים מאפשרים למפתחים לעקוב אחרי כשלים מסוימים ברישום של מקורות ייחוס או טריגרים. דוחות הניפוי באגים האלה נשלחים עם עיכוב מוגבל אחרי רישום מקור השיוך או הטריגר אל.well-known/attribution-reporting/debug/verbose נקודת קצה.

כל דוח מפורט מכיל את השדות הבאים:

  • סוג: מה גרם ליצירת הדוח. הרשימה המלאה של סוגי דוחות מפורטים
    • באופן כללי, יש דוחות מפורטים של מקורות ודוחות מפורטים של טריגרים.
    • כדי להשתמש בדוחות מפורטים של מקורות, מזהה הפרסום צריך להיות זמין באפליקציית בעל התוכן הדיגיטלי. כדי להשתמש בדוחות מפורטים של טריגרים, מזהה הפרסום צריך להיות זמין באפליקציית המפרסם.
    • הפעלת דוחות מפורטים (למעט trigger-no-matching-source) יכולה לכלול את source_debug_key. אפשר לכלול את המזהה הזה רק אם מזהה הפרסום זמין גם באפליקציית בעל התוכן הדיגיטלי.
  • גוף הדוח: גוף הדוח, שמשתנה בהתאם לסוג הדוח.

ספקי טכנולוגיות פרסום צריכים להביע הסכמה לקבלת דוחות מפורטים על ניפוי באגים באמצעות שדה מילון חדש debug_reporting בכותרות Attribution-Reporting-Register_Source ו-Attribution-Reporting-Register-Trigger.

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

איך משתמשים בדוחות ניפוי הבאגים

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

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

יכולות להיות כמה סיבות לכך שאין התאמה.

פועל כמצופה:

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

סיבות לא מכוונות:

  • בעיות בהטמעה:
    • ההגדרה של כותרת המקור שגויה.
    • ההגדרה של כותרת הטריגר שגויה.
    • בעיות אחרות בהגדרות.
  • בעיות במכשיר או ברשת:
    • כשלים בגלל תנאי הרשת.
    • התגובה לרישום המקור או הטריגר לא מגיעה ללקוח.
    • באג ב-API.

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

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

בנוסף, אנחנו רוצים לקבל משוב מהקהילה על כמה בעיות:

  1. יש תרחישי שימוש שבהם היית רוצה שה-API ישלח דוחות על ההתקנה המאומתת? הדוחות האלה ייספרו במסגרת מגבלות הקצב של פלטפורמות טכנולוגיית הפרסום.
  2. האם צפויות קשיים בהעברת InputEvent מהאפליקציה לטכנולוגיית הפרסום לצורך רישום המקור?
  3. יש לך תרחישי שימוש מיוחדים בשיוך לאפליקציות שנטענו מראש או לאפליקציות שהותקנו מחדש?