רישום טריגרים של שיוך (Attribution)

איך רושמים טריגרים של שיוך (Attribution) כדי לספור את ההמרות.

טריגר שיוך (Attribution) הוא האירוע שאומר לדפדפן לתעד המרות.

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

שיטות רישום

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

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

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

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

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

  1. מפעילים רישום של טריגר. כדי לשלוח בקשה, משתמשים בפיקסל או בקריאה ל-fetch().

  2. כדי להשלים את ההרשמה לטריגר, צריך להגיב ולציין את הכותרת של רישום הטריגר.

    עם קבלת הבקשה לפיקסלים, שנשלחה לנקודת הקצה (endpoint) שהוגדרה במאפיין 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]"
  }]
}
```

**Example for summary reports:**

```json
{
  ... // 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>) או תג סקריפט.

שימוש בפיקסל המרה חדש או קיים

<img src="https://ad-tech.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

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

אפשר לבצע רישום טריגר באמצעות תג סקריפט. הוא פועל באופן זהה ל-<img>. דוגמאות הקוד הבאות ממחישות את השימוש ב-fetch() וב-XMLHttpRequest() (XHR).

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

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

// With XMLHttpRequest:
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'})

השלבים הבאים

בקישור הבא אפשר לקבל מידע נוסף על רישום מקורות שיוך (Attribution).