רישום מקורות שיוך (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)