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

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

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

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

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

שיטות הרשמה

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

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

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

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

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

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

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

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

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

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

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

כדי לרשום מקור שיוך ללחיצה, אפשר להשתמש בתג <a> או ב-JavaScriptwindow.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 שעומדות בדרישות של navigation-source (בקשות שכוללות את הכותרת Attribution-Reporting-Eligible).

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

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

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

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

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

כדי לרשום מקור שיוך לצפייה, אפשר להשתמש בתג תמונה או בתג סקריפט שאליו מוסיפים את המאפיין 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 או כתובות ה-URL של attributionsrc כך:

עם כתובת 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 make sure 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"}

השלבים הבאים

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