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

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

סקירה כללית

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

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

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

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

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

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

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

מערכת טכנולוגיית הפרסום משלימה תהליך הרשמה כדי להשתמש ב-Attribution Reporting API.
טכנולוגיית הפרסום רושמת מקורות שיוך – קליקים על מודעות או צפיות במודעות – באמצעות Attribution Reporting API.
טכנולוגיית הפרסום רושמת טריגרים – המרות של משתמשים באפליקציה או באתר של המפרסם – באמצעות Attribution Reporting API.
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 reporting redirects. הנתונים מכילים כתובות URL להפניה אוטומטית, שמאפשרות לספקי טכנולוגיות פרסום שונים לרשום בקשה.

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

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

ערכת ה-SDK של חברת טכנולוגיית הפרסום קוראת ל-API כדי להתחיל את ההרשמה של מקור השיוך, ומציינת מזהה URI לקריאה של ה-API:
```
registerSource(
    Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
    myClickEvent);
```
ה-API שולח בקשה אל https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA באמצעות אחת מהכותרות הבאות:
```

Attribution-Reporting-Source-Info: navigation


Attribution-Reporting-Source-Info: event
```

שרת ה-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

ה-API שולח בקשה לכל כתובת URL שצוינה ב-Attribution-Reporting-Redirect. בדוגמה הזו צוינו שתי כתובות URL של שותפי טכנולוגיית הפרסום, כך שה-API שולח בקשה אחת אל https://adtechpartner1.example?their_ad_click_id=567 ובקשה נוספת אל https://adtechpartner2.example?their_ad_click_id=890.
שרת ה-HTTPS של טכנולוגיית הפרסום הזו משיב עם כותרות שמכילות את הפרטים הבאים:
```
Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "789",
    "expiry": "120000",
    "priority": "2"
}
```
הערה: בתשובות של טכנאי הפרסום יכולים להופיע מטא-נתונים שונים בכותרת Attribution-Reporting-Register-Source.

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

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

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

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

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

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

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

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

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

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

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

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

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

ה-SDK של AdTech מבצע קריאה ל-API כדי להתחיל את רישום הטריגר באמצעות URI שנרשם מראש. מידע נוסף זמין במאמר הרשמה לחשבון בארגז החול לפרטיות.
```
registerTrigger(
    Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));
```
ה-API שולח בקשה אל https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA.

שרת ה-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

ה-API שולח בקשה לכל כתובת URL שצוינה ב-Attribution-Reporting-Redirect. בדוגמה הזו צוינה רק כתובת URL אחת, ולכן ה-API שולח בקשה אל https://adtechpartner.example?app_install=567.
שרת ה-HTTPS של טכנולוגיית הפרסום הזו משיב עם כותרות שמכילות את הפרטים הבאים:
```
Attribution-Reporting-Register-Trigger: {
"event_trigger_data":[{
  "trigger_data": "5566",
  "priority": "3",
  "deduplication_key": "3344"
}]
}
```
שני טריגרים נרשמים על סמך הבקשות בשלבים הקודמים.

יכולות השיוך (Attribution)

בקטעים הבאים נסביר איך 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) לאחר ההתקנה:

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

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

ברשימה הבאה מפורטות הערות נוספות לגבי שיוך (Attribution) לאחר ההתקנה:

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

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

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

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

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

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

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

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

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

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

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

מקורות שיוך

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

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

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

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

טריגרים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הרשמה של מקור

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

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

רישום טריגר

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

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

שיוך (Attribution)

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

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

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

השיוך ל-MMP כולל עכשיו את הנתונים הבאים:

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

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

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

ניפוי באגים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוחות שאפשר לצבור

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

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

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

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

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

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

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

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

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

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

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

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

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

שירות צבירה

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

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

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

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

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

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

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

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

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

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
  }
]

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

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

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

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

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

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

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

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

המשתמש רואה מודעה. טכנולוגיית הפרסום רושמת מקור שיוך ב-API עם עדיפות 0 (תצוגה מס' 1).
המשתמש רואה מודעה, שרשומה עם רמת תעדוף 0 (צפייה מס' 2).
המשתמש לוחץ על מודעה, שרשומה עם רמת תעדוף 1 (קליק מס' 1).
המשתמש ממיר (מגיע לדף הנחיתה) באפליקציה של המפרסם. טכנולוגיית הפרסום מתעדת טריגר ב-API, עם תעדוף 0 (המרה מס' 1).
- כשהטריגרים נרשמים, ה-API מבצע שיוך לפני שהוא יוצר דוחות.
- יש 3 מקורות שיוך זמינים: צפייה מס' 1, צפייה מס' 2 קליק מס' 1. ה-API משייך את הטריגר הזה לקליק מספר 1 כי הוא בעל העדיפות הגבוהה ביותר והוא הטריגר האחרון.
- תצוגה מס' 1 ותצוגה מס' 2 יידחו ולא יהיו זכאיות יותר לשיוך עתידי.
המשתמש מוסיף פריט לעגלת הקניות באפליקציה של המפרסם, שמירת האירוע מתבצעת עם תעדוף 1 (המרה מס' 2).
- קליק מס' 1 הוא מקור השיוך היחיד שעומד בדרישות. מאפייני ה-API מפעילים את הטריגר הזה ללחיצה על 1.
המשתמש מוסיף פריט לעגלת הקניות באפליקציה של המפרסם, שמירשם עם תעדוף 1 (המרה מס' 3).
- קליק מס' 1 הוא מקור השיוך היחיד שעומד בדרישות. מאפייני ה-API משייכים את הטריגר הזה ללחיצה על 1.
המשתמש מוסיף פריט לעגלת הקניות באפליקציה של המפרסם, שמירשם עם תעדוף 1 (המרה מס' 4).
- קליק מס' 1 הוא מקור השיוך היחיד שעומד בדרישות. מאפייני ה-API מפעילים את הטריגר הזה ללחיצה על 1.
המשתמש מבצע רכישה באפליקציה של המפרסם, שמתועדת עם תעדוף 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-success ו-verbose.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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