רישום טריגרים של שיוך (Attribution)

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

טריגר שיוך הוא האירוע שמורה לדפדפן לתעד המרות.

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

שיטות הרשמה

כדי לרשום טריגרים, משתמשים ברכיבי HTML או בקריאות JavaScript:

• תג <img>
• תג <script>
• תוסף שיחה אחד (fetch)
• XMLHttpRequest

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

רישום טריגר לשיוך המרה

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

1. מתחילים את רישום הטריגר. משתמשים בפיקסל או בקריאה fetch() כדי לשלוח בקשה.

2. משלימים את רישום הטריגר על ידי שליחת תגובה עם כותרת רישום הטריגר.

   כשמתקבלת בקשת הפיקסל – שנשלחת לנקודת הקצה שמוגדרת במאפיין הרגיל src, או לנקודת הקצה שמוגדרת ב-attributionsrc אם בחרתם להשתמש ב-attributionsrc והגדרתם לו ערך – צריך להגיב עם הכותרת Attribution-Reporting-Register-Trigger.

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

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

   {
     "event_trigger_data": [{
       "trigger_data": "[unsigned 64-bit integer]",
       "priority": "[signed 64-bit integer]",
       "deduplication_key": "[unsigned 64-bit integer]"
     }]
   }
   

   דוגמה לדוחות סיכום:

   {
     ... // existing fields, such as "event_trigger_data"
   
     "aggregatable_trigger_data": [
      {
        "key_piece": "0x400",
        "source_keys": ["campaignCounts"]
      },
      {
        "key_piece": "0xA80",
        "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
      }
     ],
     "aggregatable_values": {
       "campaignCounts": 32768,
       "geoValue": 1664
     }
   }
   

התמודדות עם תתי-דומיינים

אם הערך של destination הוא https://advertiser.example, אפשר לייחס המרות גם ב-https://advertiser.example וגם בתת-הדומיינים שלו, כמו https://shop.advertiser.example.

אם הערך של destination הוא https://shop.advertiser.example, אפשר לשייך המרות גם ב-https://advertiser.example וגם ב-https://shop.advertiser.example.

מאפייני חובה ומאפיינים אופציונליים

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

אם attributionsrc הוא אופציונלי, השימוש בו מציין שהבקשה עומדת בדרישות של Attribution Reporting. אם משתמשים ב-attributionsrc, הדפדפן שולח את הכותרת Attribution-Reporting-Eligible. היא גם שימושית למדידה של מעבר מאפליקציה לאתר: אם הכותרת attributionsrc קיימת, הדפדפן שולח את הכותרת Attribution-Reporting-Support.

שלב 1: הפעלת רישום הטריגר

אפשר לרשום טריגר באמצעות פיקסל (תג <img>) או תג סקריפט.

שימוש בפיקסל המרה חדש או קיים

בדוגמה הבאה, השיוך מופעל בתמונה קיימת על ידי הוספת המאפיין attributionsrc.

המקור של attributionsrc צריך להיות זהה למקור שביצע את רישום המקור.

<img src="https://advertiser.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

בדוגמה הבאה, השיוך מופעל על ידי הוספה של מאפיין חדש של פיקסל המרה attributionsrc.

המקור של src צריך להיות זהה למקור שביצע את רישום המקור.

<img src="https://adtech.example/conversionpixel"
     attributionsrc>

שימוש בתג script

אפשר לבצע רישום של טריגר באמצעות תג script. הפעולה זהה לזו של <img>. בדוגמאות הקוד הבאות אפשר לראות איך משתמשים ב-fetch() וב-XMLHttpRequest() (XHR).

הקוד הזה מדמה למעשה את הפעולה של בקשת HTML עם attributionsrc:

const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

// Optionally set keepalive to make sure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

‫attributionsrc עם ערך או בלי ערך

אפשר להוסיף את attributionsrc עם ערך או בלי ערך.

<!-- Without a value -->
<img src="..." width="1" height="1" attributionsrc>

<!-- With a value (URL) -->
<img src="..." width="1" height="1" attributionsrc="https://...">

אם מגדירים ערך ל-attributionsrc, הוא יכול להיות כתובת URL אחת או יותר שמופרדות באמצעות רווחים.

שימוש בכתובת URL גורם לדפדפן ליזום בקשת אחזור נפרדת של keepalive – אחת לכל כתובת URL – שכוללת את כותרת הבקשה Attribution-Reporting-Eligible.

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

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

שלב 2: מגיבים עם כותרת

אחרי שמקבלים את הבקשה מהדפדפן, מגיבים וכוללים בתשובה את הכותרת Attribution-Reporting-Register-Trigger:

JSON.stringify({
  event_trigger_data: [{
    trigger_data: "412444888111012",
    // Optional
    priority: "1000000000000",
    deduplication_key: "2345698765"
  }],
  debug_key: "1115698977"
});

השלבים הבאים

איך רושמים מקורות שיוך