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

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

  • עדכנו את הרשימה של השינויים הקרובים והבעיות הידועות
  • הוספנו הגדרה גמישה בסיסית ברמת האירוע, כגישה להגדרה גמישה מלאה ברמת האירוע
  • החל מספטמבר 2023, ב-registerWebSource, ב-registerWebTrigger, ב-registerAppSource וב-registerAppTrigger צריך להשתמש במחרוזות בשדות שמצופה להם ערך מספרי (כמו priority,‏ source_event_id,‏ debug_key,‏ trigger_data,‏ deduplication_key וכו').
  • ברבעון הרביעי של 2023, תתווסף תמיכה ב-Google Cloud ב-Android Attribution Reporting API כדי ליצור דוחות סיכום באמצעות שירות הצבירה ב-Google Cloud. לוח הזמנים הספציפי מופיע כאן. מידע נוסף על הגדרת שירות צבירת נתונים ב-Google Cloud מופיע במדריך הפריסה.
  • מגבלות חדשות על שיעור השמירה על הפרטיות במספר היעדים הייחודיים.
  • הפונקציונליות המעודכנת של מסנני הטריגרים של חלון מבט לאחור תהיה זמינה ברבעון הראשון של 2024. מידע נוסף זמין בהערה.

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

אופציונלי: התגובה למטא-נתונים של מקור השיוך עשויה לכלול נתונים נוספים בכותרת הפניות אוטומטיות לדיווח על שיוך (Attribution). הנתונים מכילים כתובות 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"
}

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

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

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

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

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

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

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

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

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

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

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

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

אירוע היום שבו מתרחש האירוע הערות
קליק 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 (תואם לשיוך של התקנה מאומתת).
קליק 2 לא נספר ולא יתבצע לו שיוך עתידי.

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

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

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

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

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

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

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

מתן עדיפות למספר טריגרים למקור שיוך אחד

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

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

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

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

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

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

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

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

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

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

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

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

טריגרים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ברשימה הבאה מפורטת סדרה היפותטית של פעולות משתמש שמתרחשות כל אחת במרווח של יום אחד, ומוצג האופן שבו Attribution Reporting API מטפל בפעולות האלה ביחס ל-Ad tech A, ל-Ad tech B ול-MMP:

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

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

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

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

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

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

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

ה-API מגיב באותו אופן שבו הוא הגיב ביום הראשון, מלבד העובדה שהצפייה רשומה ב-Ad Tech A וב-MMP.

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

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

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

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

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

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

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

שיוך חוצה-רשתות ללא הפניות לכתובת URL אחרת

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

זרימה ברמה גבוהה

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

הרשמה של מקור

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

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

הפעלת ההרשמה

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

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

שיוך (Attribution)

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

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

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

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

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

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

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

ניפוי באגים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

המקור השני, למקור הדיווח 2 של חברת AdTech A, יידחה על ידי ה-API. מקור הדיווח 2 של חברת AdTech A לא יוכל לרשום מקור באותו מכשיר באפליקציה B עד ליום הבא.

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

כדי להגביל את כמות דליפת הזהות של משתמש בין צמד של {מקור, יעד}, ה-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, וגם:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

שירותי צבירת נתונים

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

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

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

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

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

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

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

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

שירות ניהול מפתחות (KMS)

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

דיווח על דוחות עם נתונים מצטברים

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

Aggregatable Reports API

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

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

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

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

מפתח הקטגוריה הסופי של ההיסטוגרמה מוגדר במלואו בזמן ההפעלה, על ידי ביצוע פעולת 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
  }
]

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

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

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

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

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

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

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

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

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

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

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

למידע נוסף על הפעלת האפשרות הזו ב-Protected Audience API, עיינו בקטע הרלוונטי בהסבר על 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 משייך את הטריגר הזה ולוחצים על מספר 1.
  6. המשתמש מוסיף פריט לעגלת הקניות באפליקציית המפרסם, שרשומה עם העדיפות 1 (המרה 3).
    • קליק 1 הוא מקור השיוך היחיד שעומד בדרישות. ה-API משייך את הטריגר הזה ולוחצים על מספר 1.
  7. המשתמש מוסיף פריט לעגלת הקניות באפליקציה של המפרסם, שמירשם עם תעדוף 1 (המרה מס' 4).
    • קליק 1 הוא מקור השיוך היחיד שעומד בדרישות. מאפייני ה-API מפעילים את הטריגר הזה ללחיצה על 1.
  8. המשתמש מבצע רכישה באפליקציית המפרסם, שרשומה עם עדיפות של 2 (המרה 5).
    • קליק מס' 1 הוא מקור השיוך היחיד שעומד בדרישות. ה-API משייך את הטריגר הזה ולוחצים על מספר 1.

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

  • כברירת מחדל, 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 דוחות כל אחת.

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

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

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

דוחות ניפוי באגים במעבר

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

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

דוחות ניפוי באגים של שיוך (Attribution)

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

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

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

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

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

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

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

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

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

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

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

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

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

פועלת כמצופה:

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

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

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

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

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

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

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