הסכמה בתוך iframes חוצי-origin: תבנית __tcfapiLocator ו-__gppLocator
הבעיה: ההסכמה חיה בחלון העליון
ה-CMP רץ בעמוד שלך, בחלון הרמה העליונה. חלק גדול מהפרסום שלך לא. קריאייטיבים של תצוגה, מדיה עשירה, מרנדרים של header bidding וווידג'טים רבים של צד שלישי רצים בתוך iframes, לעיתים קרובות ב-origin שונה. קוד ב-iframe חוצה-origin לא יכול לקרוא ישירות לפונקציה בעמוד האב, ולכן הוא לא יכול פשוט לקרוא ל-__tcfapi או ל-__gpp ולקרוא את בחירת המבקר.
מסגרות ה-IAB פותרות זאת באמנת הודעות קטנה ומוגדרת היטב. אם אתה בונה מוצרי פרסום, הטמעות או סקריפטים למדידה שרצים בפריימים, או מדבג מערכי מודעות שעושים זאת, כדאי לדעת בדיוק איך זה עובד.
פריים ה-locator
לצד ממשק ה-JavaScript, CMP של TCF מוסיף לעמוד העליון iframe ריק ובלתי נראה בשם __tcfapiLocator. CMP של GPP עושה אותו דבר עם פריים בשם __gppLocator. בפריימים אין תוכן. התפקיד היחיד שלהם הוא להיות ניתנים לאיתור: כל סקריפט בכל פריים מקונן יכול לטפס במעלה היררכיית החלונות ולבדוק בכל רמה אם קיים פריים בשם הזה.
מכיוון ששמות פריימים גלויים בין origins דרך window.frames, סקריפט ב-iframe חוצה-origin מקונן עמוק יכול לאתר את החלון שמארח את ה-CMP בלי גישה לשום דבר אחר באותו עמוד.
איך סקריפט בפריים מוצא את ה-CMP
- התחל בחלון הנוכחי. אם __tcfapi קיים מקומית, השתמש בו ישירות — הסקריפט אינו בפריים, או שהפריים חולק את ה-CMP.
- אחרת, בצע לולאה כלפי מעלה: בדוק אם החלון הנוכחי מכיל פריים בשם __tcfapiLocator; אם לא, עבור ל-window.parent ובדוק שוב, ועצור בחלון העליון.
- כשה-locator נמצא, החלון שמכיל אותו הוא חלון ה-CMP. התקשורת מתבצעת כעת דרך postMessage.
עטוף כל גישה ב-try/catch, כי חלק מהדפדפנים או מהגדרות ה-sandbox זורקים חריגה בגישה למאפיין חוצה-origin, ועצור את הלולאה כש-window.parent שווה לחלון הנוכחי.
פורמט ההודעה
ב-TCF, הסקריפט שבפריים שולח לחלון ה-CMP הודעה שמכילה אובייקט עם המאפיין __tcfapiCall. בתוכו ארבעה שדות:
- command — למשל getTCData, ping או addEventListener;
- parameter — כל ארגומנט שהפקודה צריכה, או null;
- version — גרסת ה-API, 2 עבור TCF v2;
- callId — ערך ייחודי שהקורא מייצר.
ה-CMP מאזין להודעות האלה, מריץ את הפקודה ושולח בחזרה אובייקט עם המאפיין __tcfapiReturn המכיל returnValue, success ואת אותו callId. הקורא מחזיק מפה של callbacks ממתינים לפי callId, מאזין לאירועי message ומפנה כל תשובה ל-callback הנכון. GPP פועל באותה תבנית עם __gppCall ו-__gppReturn.
אינטגרציות רבות כותבות proxy קטן: פונקציה מקומית בשם __tcfapi בתוך הפריים שמתרגמת קריאות להודעות. קוד שנכתב לחלון העליון עובד אז ללא שינוי בתוך הפריים.
מאזיני אירועים בין פריימים
קריאת addEventListener שנשלחת דרך postMessage אינה בקשה חד-פעמית. ה-CMP ישלח הודעת החזרה בכל פעם שמצב ההסכמה משתנה, כולן עם אותו callId. לכן המפיץ שלך חייב להשאיר את ה-callback הזה רשום ולא למחוק אותו אחרי התגובה הראשונה. שכחה של זה היא באג קלאסי: הסקריפט שבפריים קורא הסכמה פעם אחת ולעולם לא שם לב לביטול מאוחר יותר.
שיקולי אבטחה
- אמת את צורת ההודעה. התעלם מכל הודעה שאינה מכילה את המאפיין הצפוי, ופענח payloads מסוג מחרוזת בזהירות, כי חלק מהמימושים שולחים מחרוזות JSON ולא אובייקטים.
- אל תבטח באופן עיוור. כל עמוד יכול לשלוח הודעות לפריים שלך. התייחס לתגובות כאל אותות הסכמה שיש לכבד, לא כאל נתונים מאומתים, ולעולם אל תתן להן להפעיל פעולות בעלות הרשאות.
- השתמש ב-origin יעד ספציפי כשאפשר. כשה-origin של ה-CMP ידוע, שלח אליו ולא לכל origin.
איפה התבנית לא מגיעה
חלק מסביבות המודעות מבודדות קריאייטיבים בצורה קפדנית יותר. מכולות SafeFrame, iframes ב-sandbox בלי ההרשאות הנכונות וקריאייטיבים שמרונדרים במסמכים נפרדים עשויים לא להצליח לעבור על עץ הפריימים או לקבל הודעות. במקרים כאלה בדרך כלל יש להעביר את אות ההסכמה במפורש, למשל כפרמטרים בבקשת המודעה או כערכים שמוסר שרת המודעות לקריאייטיב, כמו הפרמטרים gdpr ו-gdpr_consent שתגיות מודעות רבות תומכות בהם.
רשימת בדיקה לדיבוג
- ב-DevTools של החלון העליון, ודא שפריימי ה-locator קיימים בלוח Elements.
- החלף את הקשר הקונסולה ל-iframe ובדוק אם ה-locator נגיש משם.
- רשום ביומן אירועי message נכנסים בשני החלונות כדי לוודא שקריאות ותשובות זורמות.
- שנה הסכמה בבאנר ואמת שהמאזינים שבפריים מקבלים עדכון.
- בדוק עם CMP שנטען מאוחר, כדי לוודא שהקוד שבפריים מנסה שוב או ממתין במקום לוותר מיד.
עיקרי הדברים
- פריימים חוצי-origin מגיעים ל-CMP דרך פריימי __tcfapiLocator ו-__gppLocator.
- קריאות ותשובות משתמשות ב-postMessage עם __tcfapiCall/__tcfapiReturn או המקבילות של GPP, ומותאמות לפי callId.
- השאר את ה-callbacks של המאזינים רשומים כדי ששינויי הסכמה מאוחרים יותר יגיעו.
- אמת כל הודעה ואל תתייחס אליה כאל קלט מהימן.
- היכן שהפריימים מבודדים לחלוטין, העבר הסכמה במפורש בבקשת המודעה.