איך רושמים מקורות כדי לשייך קליקים וצפיות לאירועים המתאימים
מקור שיוך הוא אירוע שקשור למודעה (קליק או צפייה), שאליו טכנולוגיית הפרסום יכולה לצרף את סוגי המידע הבאים:
- נתוני דיווח לפי הקשר, כמו מזהה הקריאייטיב של המודעה, מידע על הקמפיין או המיקום הגיאוגרפי.
- יעד המרה, כלומר האתר שבו אתם מצפים שהמשתמש ישלים המרה.
אם תפעלו לפי השלבים שמפורטים במסמך הזה, תוכלו לרשום מקורות – חשיפות של מודעות או קליקים – שהדפדפן משייך אליהם המרות.
שיטות רישום
כדי לרשום מקורות שיוך, משתמשים ברכיבי HTML או בקריאות JavaScript:
- תג
<a>
- תג
<img>
- תג
<script>
- תוסף שיחה אחד (
fetch
) XMLHttpRequest
- תוסף שיחה אחד (
window.open
)
הפעולה הזו יוצרת בקשות רשת, שאליהן תצטרכו להשיב באמצעות כותרת תגובה של HTTP לרישום מקור.
רישום מקורות של קליקים או צפיות
כדי לרשום מקור שיוך לקליק או לצפייה, פועלים לפי השלבים שמפורטים כאן. השלבים המלאים מפורטים בהמשך. זהו הסיכום:
- מתחילים את רישום המקור. משתמשים ברכיב HTML או בקריאה ל-JavaScript כדי לשלוח בקשה. השלב הזה שונה עבור קליקים וצפיות, כפי שאפשר לראות בקטעים הבאים.
משלימים את תהליך ההרשמה של המקור על ידי שליחת תשובה עם הכותרת של הרשמת המקור. כשמקבלים את הבקשה הזו, צריך להשיב עם הכותרת
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). אם משתמשים ב-attributionsrc
, הדפדפן שולח את הכותרת Attribution-Reporting-Eligible
. היא גם מועילה למדידת המרות מאפליקציה לאתר: אם attributionsrc
נמצאת, הדפדפן שולח את הכותרת Attribution-Reporting-Support
.
שיטת הרישום | מקור |
---|---|
תג <a> |
(navigation source)attributionsrc הוא חובה. |
תג <img> |
השדה (event source)attributionsrc הוא חובה. |
תג <script> |
השדה (event source)attributionsrc הוא חובה. |
תוסף שיחה אחד (fetch ) |
האפשרות attributionReporting חובה. |
XMLHttpRequest |
האפשרות attributionReporting חובה. |
תוסף שיחה אחד (window.open ) |
(navigation source)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
, מורים לדפדפן לשלוח את הבקשה הנוספת הזו ולהגדיר את היעד שלה.
כדי לרשום מקור שיוך לדף ספציפי, אפשר להשתמש בתג תמונה או בתג סקריפט שאליו מוסיפים את המאפיין 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"}