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

איך לרשום טריגרים של שיוך (Attribution) לספירת ההמרות.

טריגר שיוך (Attribution) הוא האירוע שמנחה את הדפדפן לתעד המרות.

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

שיטות רישום

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

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

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

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

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

  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). אם משתמשים attributionsrc, הדפדפן שולח את הכותרת Attribution-Reporting-Eligible. הוא שימושי גם כשמדובר באפליקציה לאתר מדידה: אם attributionsrc קיים, הדפדפן שולח את הכותרת Attribution-Reporting-Support.

שיטת הרישום טריגר
תג <a> לא רלוונטי: תווי עוגן לא יכולים לרשום טריגר.
תג <img> attributionsrc הוא אופציונלי. הכותרת מספיקים כדי לרשום טריגר.
תג <script> attributionsrc הוא אופציונלי. הכותרת מספיקים כדי לרשום טריגר.
תוסף שיחה אחד (fetch) האפשרות attributionReporting היא חובה.
XMLHttpRequest האפשרות attributionReporting היא חובה.
window.open() לא רלוונטי: window.open לא יכול לרשום טריגר.

שלב 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>

שימוש בתג סקריפט

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

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

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

// Optionally set keepalive to ensure 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"
});

השלבים הבאים

מידע נוסף על רישום מקורות שיוך