דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

שיטות רישום

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

תג אחד (<a>)
תג אחד (<img>)
תג אחד (<script>)
נכס התקשרות אחד (fetch)
XMLHttpRequest
window.open

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

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

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

מתחילים את רישום המקור. השתמשו ברכיב HTML או בקריאה של JavaScript כדי לשלוח בקשה. שלב זה שונה מבחינת קליקים וצפיות, כפי שניתן לראות בקטעים הבאים.
כדי להשלים את רישום המקור, צריך לשלוח בתשובה את כותרת הרישום של המקור. עם קבלת הבקשה, משיבים וכותבים את הכותרת 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 שונה עבור קליקים וצפיות. פותחים את הכרטיסיות התואמות לכל אחד מהם.

כדי לרשום מקור שיוך (Attribution) של קליק, אפשר להשתמש בתג <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">

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

יש לקודד באופן הבא:

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

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

<!-- With an anchor tag -->
<a href=... attributionsrc="https://a.example/register-source 
  https://b.example/register-source">

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

// With window.open()
window.open('...', '_blank', attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2})

במקרים כאלה, שתי כתובות ה-URL מקבלות בקשות של navigation-source-eligible attributionsrc (בקשות שכוללות את הכותרת Attribution-Reporting-Eligible).

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

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

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

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

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

בשלב 1 של רישום התצוגות, עוברים אל הכרטיסיות ובוחרים באפשרות 'תצוגות', שלב 1.

כדי לרשום מקור שיוך (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=..."/>

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

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

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

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

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

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

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

// With fetch
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 });

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

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

בשלב 1 של רישום הקליקים, עוברים לכרטיסיות ובוחרים באפשרות 'קליקים', שלב 1.

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