چرا اسکریپت‌های شما باید گوش دهند، نه پایش دوره‌ای کنند

هر اسکریپتی که به رضایت وابسته است — یک تگ تبلیغاتی، یک بارگذار تحلیلی، یک wrapper برای header bidding — باید دو چیز را بداند: اینکه آیا CMP هنوز تصمیمی دارد یا نه، و آن تصمیم چیست. اشتباه رایج این است که هنگام بارگذاری صفحه یک کوکی خوانده شود یا با تایمر مرتب از CMP پرس‌وجو شود تا چیزی ظاهر شود. هر دو رویکرد به شیوه‌های قابل‌پیش‌بینی خراب می‌شوند: قالب کوکی داخلی CMP است و می‌تواند تغییر کند، و پایش دوره‌ای یا خیلی زود اجرا می‌شود یا زمان را در انتظار هدر می‌دهد.

IAB TCF دقیقاً برای همین کار یک رابط استاندارد جاوااسکریپت تعریف کرده است: تابع __tcfapi. این آموزش دستورهایی که واقعاً لازم دارید، رویدادهایی که دریافت می‌کنید و باگ‌هایی که بیشتر در محیط تولید دیده می‌شوند را مرور می‌کند.

استاب و صف

از یک CMP مبتنی بر TCF انتظار می‌رود که یک stub کوچک را هرچه زودتر، پیش از بارگذاری اسکریپت کامل CMP، در صفحه قرار دهد. استاب window.__tcfapi را تعریف می‌کند و هر فراخوانی را که پیش از آماده شدن CMP انجام شود در صف قرار می‌دهد. وقتی CMP بارگذاری را تمام کرد، صف را پردازش می‌کند و به هر فراخوانی پاسخ می‌دهد.

همین باعث می‌شود اسکریپت‌های دیگر بتوانند بی‌خطر __tcfapi را فوراً فراخوانی کنند: تا زمانی که استاب پیش از آن‌ها در صفحه باشد، فراخوانی‌هایشان گم نمی‌شود. اگر اسکریپتی به دلیل تعریف‌نشده بودن __tcfapi خطا می‌دهد، استاب یا وجود ندارد یا خیلی دیر بارگذاری می‌شود — به‌جای افزودن تلاش مجدد، ترتیب بارگذاری را اصلاح کنید.

دستورهای مهم

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] — رضایت برای هدف ۱ (ذخیره‌سازی روی دستگاه).
• tcData.purpose.legitimateInterests[7] — وضعیت منفعت مشروع برای هدف ۷.
• tcData.vendor.consents[ID] و tcData.vendor.legitimateInterests[ID] — وضعیت هر فروشنده، با استفاده از شناسه فروشنده در Global Vendor List.
• tcData.gdprApplies — اینکه آیا CMP تشخیص داده GDPR برای این بازدیدکننده اعمال می‌شود. اگر false باشد، اسکریپت شما باید از منطق غیر-TCF خود پیروی کند.
• tcData.tcString — رشته کدگذاری‌شده، که آن را به شرکایی که انتظارش را دارند منتقل می‌کنید.

هم هدف و هم فروشنده را بررسی کنید. رضایت هدف بدون رضایت فروشنده، یا برعکس، برای پردازش داده توسط بیشتر فروشندگان کافی نیست.

iframeها و فراخوانی‌های میان‌فریمی

تبلیغات و ابزارک‌ها اغلب درون iframeهایی اجرا می‌شوند که __tcfapi صفحه والد را نمی‌بینند. TCF این مشکل را با یک پروتکل postMessage حل می‌کند: CMP فریمی به نام __tcfapiLocator به صفحه بالایی اضافه می‌کند و کد درون iframe می‌تواند آن را پیدا کند، پیام __tcfapiCall بفرستد و پاسخ __tcfapiReturn را دریافت کند. بیشتر SDKهای تبلیغاتی این کار را از قبل انجام می‌دهند. اگر کد iframe خودتان را می‌نویسید، به‌جای خواندن کوکی‌ها میان فریم‌ها همین الگو را پیاده کنید.

باگ‌های رایج و نحوه تشخیص آن‌ها

1. عمل بر اساس cmpuishown. اسکریپت‌هایی که به محض فراخوانی هر callback بارگذاری می‌شوند، پیش از تصمیم کاربر اجرا خواهند شد. بر اساس eventStatus فیلتر کنید.
2. حذف زودهنگام شنونده. اگر پس از اولین callback آن را حذف کنید، useractioncomplete بعدی را از دست می‌دهید و هرگز بارگذاری نمی‌شود.
3. نادیده گرفتن پس‌گرفتن رضایت. اسکریپت‌های ماندگار باید به گوش دادن ادامه دهند و هنگام پس‌گرفتن رضایت متوقف شوند یا خود را بازپیکربندی کنند.
4. نادیده گرفتن gdprApplies. خارج از مناطق TCF، اشیای هدف ممکن است خالی باشند؛ تلقی آن به‌عنوان «بدون رضایت» می‌تواند درآمدی را که مجاز به کسب آن هستید خاموش کند.
5. بررسی نکردن پرچم موفقیت. وقتی success برابر false است، آن را ثبت کنید؛ معمولاً نشانه پیکربندی خراب CMP است.

آزمایش یکپارچه‌سازی شما

در کنسول مرورگر، __tcfapi('ping', 2, console.log) را فراخوانی کنید تا از حضور CMP مطمئن شوید، سپس شنونده‌ای با console.log به‌عنوان callback ثبت کنید و بنر را مرحله‌به‌مرحله طی کنید. در بازدید اول باید cmpuishown و سپس useractioncomplete و در بارگذاری مجدد tcloaded را ببینید. با پذیرش همه، رد همه و یک انتخاب سفارشی تکرار کنید و مطمئن شوید اسکریپت شما در هر حالت درست رفتار می‌کند.

نکات کلیدی

• به‌جای خواندن کوکی‌های CMP یا پایش دوره‌ای از __tcfapi استفاده کنید.
• مطمئن شوید stub مربوط به CMP پیش از هر اسکریپتی که API را فراخوانی می‌کند بارگذاری می‌شود.
• از addEventListener استفاده کنید و فقط بر اساس tcloaded یا useractioncomplete عمل کنید.
• هم وضعیت هدف و هم فروشنده را بررسی کنید و به gdprApplies احترام بگذارید.
• درون iframeها از الگوی postMessage مبتنی بر __tcfapiLocator استفاده کنید.