רישום טריגרים של שיוך (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 גורם לדפדפן ליזום בקשת אחזור נפרדת מסוג הודעת keep-alive - אחת לכל כתובת 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"
});

השלבים הבאים

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