איך לרשום טריגרים של שיוך (Attribution) לספירת ההמרות.
טריגר שיוך (Attribution) הוא האירוע שמנחה את הדפדפן לתעד המרות.
בעזרת השלבים שבמסמך הזה תוכלו לרשום טריגרים שיתעדו המרות שהדפדפן משייך אותן לאירועי המקור הרלוונטיים, למשל חשיפות של מודעות או קליקים על מודעות.
שיטות רישום
כדי לרשום טריגרים, צריך להשתמש ברכיבי HTML או בקריאות JavaScript:
- תג
<img>
- תג
<script>
- נכס התקשרות אחד (
fetch
) XMLHttpRequest
הפעולה הזו יוצרת בקשות רשת שאחריהן אתם מגיבים באמצעות כותרת תגובת HTTP לרישום טריגר.
רישום טריגר לשיוך המרה
רישום טריגר דומה לרישום של אירוע של מקור שיוך (Attribution). השלבים המלאים מתוארים בהמשך. הנה הסיכום:
- התחלת הרישום של הטריגר. כדי לשלוח בקשה, צריך להשתמש בפיקסל או ב-
fetch()
. משלימים את רישום הטריגר באמצעות תגובה עם כותרת הטריגר לרישום.
כשתקבלו את בקשת הפיקסל, שנשלחה לנקודת הקצה שהוגדרה במאפיין
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]" }] }
דוגמה לדוחות סיכום:
{ ... // 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>
) או תג סקריפט.
שימוש בפיקסל המרה חדש או קיים
הדוגמה הבאה מפעילה את השיוך של תמונה קיימת על ידי הוספת המאפיין attributionsrc
.
המקור של attributionsrc
חייב להתאים למקור שביצע את רישום המקור.
<img src="https://advertiser.example/conversionpixel"
attributionsrc="https://adtech.example/attribution_trigger?purchase=13">
הדוגמה הבאה מפעילה את השיוך על ידי הוספת מאפיין חדש של פיקסל המרה attributionsrc
.
המקור של src
חייב להתאים למקור שביצע את רישום המקור.
<img src="https://adtech.example/conversionpixel"
attributionsrc>
שימוש בתג סקריפט
אפשר לבצע רישום של טריגר באמצעות תג סקריפט. התג מתנהג באופן זהה לזה של <img>
. דוגמאות הקוד הבאות ממחישות את השימוש ב-fetch()
וב-XMLHttpRequest()
(XHR).
הקוד הזה מדמה באופן יעיל את מה שבקשת HTML באמצעות attributionsrc
עושה:
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 });
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"
});