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

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

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

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

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

שיטות רישום

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

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

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

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

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

  1. מתחילים את רישום המקור. להשתמש ברכיב HTML או ברכיב קריאה ל-JavaScript כדי לשלוח בקשה. שלב זה שונה עבור קליקים וצפיות, כפי שתוכלו לראות בקטעים הבאים.

  2. משלימים את רישום המקור בתשובה עם המקור כותרת הרישום. עם קבלת הבקשה, עליך להשיב עם הכותרת Attribution-Reporting-Register-Source בכותרת הזו, מציינים את ההגדרה הרצויה של דוחות שיוך (Attribution). השלב הזה זהה עבור קליקים וצפיות.

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

    {
  "aggregation_keys": {
    "campaignCounts": "0x159",
    "geoValue": "0x5"
  },
  "aggregatable_report_window": "86400",
  "destination": "https://example.com"
}

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

    {
  "source_event_id": "12340873456",
  "destination": "[eTLD+1]",
  "expiry": "[64-bit signed integer]",
  "priority": "[64-bit signed integer]",
  "event_report_window": "[64-bit signed integer]"
}

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

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

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

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

שלב 1: התחלת הרישום של המקור

שלב 1 שונה עבור קליקים וצפיות.

כדי לרשום מקור שיוך לקליק, אפשר להשתמש בתג <a> או ב-JavaScript window.open().

שימוש בעיגון

צריך להוסיף attributionsrc לתגי <a> קיימים שעבורם רוצים למדוד חשיפות או קליקים:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

מידע נוסף זמין בקוד לדוגמה.

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

התקשרות אל window.open() עם attributionsrc:

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

לשם כך, צריך להפעיל את השיטה הזו תוך 5 שניות מהאינטראקציה של המשתמש.

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

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

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

מקודדים את הקוד כך:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc יכול גם להשתמש ברשימה של כתובות URL המופרדות ברווחים, כפי שמודגם כאן באמצעות תג <a>:

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

או כפי שהוא כאן באמצעות window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

במקרים כאלה, שתי כתובות ה-URL מקבלות סטטוס attributionsrc שעונה על הדרישות למקור ניווט בקשות (בקשות שכוללות את הכותרת Attribution-Reporting-Eligible).

attributionsrc עם או בלי ערך

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

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

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

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

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

לחלופין, אפשר להשתמש ב-JavaScript fetch() או XMLHttpRequest().

עם תמונה

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

עם סקריפט

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

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

עם כתובת URL אחת:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

עם רשימה של כתובות URL:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

שימוש ב-fetch() או ב-XMLHttpRequest()

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

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

// 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: true,
  triggerEligible: false,
};

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

שלב 2: הוספת כותרת (קליקים ותצוגות)

השלב הבא בכל הנוגע לקליקים וגם לצפיות הוא שליחת תשובה באמצעות הכותרת Attribution-Reporting-Register-Source.

מידע נוסף זמין בקוד לדוגמה.

עם קבלת בקשת הדפדפן בשרת, חשוב להגיב ולכלול את את התשובה שלך, עם הכותרת Attribution-Reporting-Register-Source.

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

לאחר יצירת המחרוזת, הכותרת תיראה כך:

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

השלבים הבאים

מידע נוסף על רישום טריגרים של שיוך (Attribution)