למה הסקריפטים שלכם צריכים להאזין ולא לדגום

כל סקריפט שתלוי בהסכמה — תג פרסומי, טוען אנליטיקה, wrapper של header bidding — צריך לדעת שני דברים: האם ל-CMP כבר יש החלטה, ומהי ההחלטה. טעות נפוצה היא לקרוא עוגייה בטעינת העמוד, או לדגום את ה-CMP בטיימר עד שמשהו מופיע. שתי הגישות נשברות בדרכים צפויות: פורמט העוגייה פנימי ל-CMP ועלול להשתנות, והדגימה או מופעלת מוקדם מדי או מבזבזת זמן בהמתנה.

IAB TCF מגדיר ממשק JavaScript סטנדרטי בדיוק למשימה הזו: הפונקציה __tcfapi. מדריך זה עובר על הפקודות שבאמת נחוצות, על האירועים שתקבלו ועל הבאגים שמופיעים הכי הרבה בסביבת ייצור.

ה-Stub והתור

מצופה מ-CMP של TCF למקם stub קטן בעמוד מוקדם ככל האפשר, לפני טעינת סקריפט ה-CMP המלא. ה-stub מגדיר את window.__tcfapi ומכניס לתור כל קריאה שמתבצעת לפני שה-CMP מוכן. כשה-CMP מסיים להיטען, הוא מעבד את התור ועונה על כל קריאה.

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

הפקודות החשובות

ping

__tcfapi('ping', 2, callback) מחזירה סטטוס בסיסי בלי להמתין להחלטת המשתמש. התגובה כוללת cmpLoaded, ערך cmpStatus כגון stub, loading, loaded או error, ו-displayStatus של visible, hidden או disabled. היא מדווחת גם על gdprApplies ברגע שהערך ידוע. השתמשו בה לאבחון ולהחלטה אם ה-TCF רלוונטי בכלל לגולש הזה.

addEventListener

__tcfapi('addEventListener', 2, callback) היא הפקודה שרוב האינטגרציות צריכות להשתמש בה. ה-callback מקבל אובייקט tcData ודגל הצלחה, והוא נקרא שוב בכל פעם שמצב ההסכמה משתנה. מאז TCF v2.2 זו הדרך המומלצת לקבל נתוני הסכמה; הפקודה הישנה getTCData הוצאה משימוש.

removeEventListener

כל אובייקט tcData נושא listenerId. העבירו אותו אל __tcfapi('removeEventListener', 2, callback, listenerId) כשהסקריפט שלכם כבר לא צריך עדכונים — למשל טוען חד-פעמי שכבר קיבל את החלטתו.

קריאת eventStatus

השדה המרכזי ב-tcData הוא eventStatus. יש לו שלושה ערכים:

• tcloaded — ה-CMP מצא החלטה שמורה תקפה ולא יוצג באנר. אפשר לפעול על הנתונים מיד.
• cmpuishown — הבאנר מוצג. הנתונים משקפים כל מצב קודם, אך ייתכן שהמשתמש עומד לשנות אותו.
• useractioncomplete — המשתמש הרגע ביצע או אישר בחירה. פעלו על הנתונים החדשים.

טוען טיפוסי ממתין ל-tcloaded או ל-useractioncomplete, ואז בודק את המטרות והספקים שהוא צריך. הוא מתעלם מ-cmpuishown, אולי מלבד תיעוד שבאנר הופיע.

בדיקת מטרות וספקים

בתוך tcData, הסכמה ואינטרס לגיטימי נחשפים כאובייקטים לפי מזהה:

• tcData.purpose.consents[1] — הסכמה למטרה 1 (אחסון במכשיר).
• tcData.purpose.legitimateInterests[7] — מצב האינטרס הלגיטימי למטרה 7.
• tcData.vendor.consents[ID] ו-tcData.vendor.legitimateInterests[ID] — מצב לכל ספק, לפי מזהה הספק ב-Global Vendor List.
• tcData.gdprApplies — האם ה-CMP קבע ש-GDPR חל על הגולש הזה. אם הערך false, הסקריפט שלכם צריך לפעול לפי הלוגיקה שאינה TCF.
• tcData.tcString — המחרוזת המקודדת, שאותה מעבירים לשותפים שמצפים לה.

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

Iframes וקריאות בין פריימים

פרסומות וווידג׳טים רצים לעיתים קרובות בתוך iframes שאינם רואים את __tcfapi של העמוד האב. ה-TCF פותר זאת בפרוטוקול postMessage: ה-CMP מוסיף פריים בשם __tcfapiLocator לעמוד העליון, וקוד בתוך iframe יכול לאתר אותו, לשלוח הודעת __tcfapiCall ולקבל תגובת __tcfapiReturn. רוב ערכות ה-SDK הפרסומיות כבר עושות זאת. אם אתם כותבים קוד iframe משלכם, ממשו את אותו דפוס במקום לקרוא עוגיות בין פריימים.

באגים נפוצים ואיך לזהות אותם

1. פעולה על cmpuishown. סקריפטים שנטענים ברגע שכל callback נורה ירוצו לפני שהמשתמש החליט. סננו לפי eventStatus.
2. הסרת ה-listener מוקדם מדי. אם תסירו אותו אחרי ה-callback הראשון, תפספסו useractioncomplete מאוחר יותר ולעולם לא תיטענו.
3. התעלמות מביטולי הסכמה. סקריפטים מתמשכים צריכים להמשיך להאזין ולעצור או להגדיר את עצמם מחדש כשההסכמה נשללת.
4. התעלמות מ-gdprApplies. מחוץ לאזורי TCF אובייקטי המטרות עשויים להיות ריקים; התייחסות לכך כאל “אין הסכמה” עלולה לכבות הכנסות שמותר לכם להרוויח.
5. אי בדיקת דגל ההצלחה. כאשר success הוא false, תעדו זאת; זה בדרך כלל מעיד על הגדרת CMP שבורה.

בדיקת האינטגרציה שלכם

בקונסולת הדפדפן, קראו ל-__tcfapi('ping', 2, console.log) כדי לוודא שה-CMP קיים, ואז רשמו listener עם console.log כ-callback ועברו על הבאנר. בביקור ראשון אמורים להופיע cmpuishown ואחריו useractioncomplete, ובטעינה מחדש tcloaded. חזרו על כך עם אישור הכל, דחיית הכל ובחירה מותאמת, וודאו שהסקריפט שלכם מתנהג נכון בכל מקרה.

עיקרי הדברים

• השתמשו ב-__tcfapi במקום לקרוא עוגיות CMP או לדגום.
• ודאו שה-stub של ה-CMP נטען לפני כל סקריפט שקורא ל-API.
• השתמשו ב-addEventListener ופעלו רק על tcloaded או useractioncomplete.
• בדקו גם מטרה וגם ספק, וכבדו את gdprApplies.
• השתמשו בדפוס __tcfapiLocator עם postMessage בתוך iframes.