رضایت در iframeهای cross-origin: الگوی __tcfapiLocator و __gppLocator
مسئله: رضایت در پنجره بالایی زندگی میکند
CMP روی صفحه شما، در پنجره سطح بالا اجرا میشود. بخش زیادی از تبلیغات شما چنین نیست. کریتیوهای نمایشی، رسانه غنی، رندرکنندههای header bidding و بسیاری از ویجتهای شخص ثالث درون iframe اجرا میشوند، اغلب در origin متفاوت. کد در iframe cross-origin نمیتواند مستقیماً تابعی را در صفحه والد فراخوانی کند، پس نمیتواند ساده __tcfapi یا __gpp را صدا بزند و انتخاب بازدیدکننده را بخواند.
چارچوبهای IAB این مسئله را با یک قرارداد پیامرسانی کوچک و کاملاً تعریفشده حل میکنند. اگر محصولات تبلیغاتی، جاسازیها یا اسکریپتهای اندازهگیری میسازید که در فریمها اجرا میشوند، یا زیرساختهای تبلیغاتی را که چنین میکنند اشکالزدایی میکنید، دانستن دقیق نحوه کار آن ارزش دارد.
فریم locator
در کنار API جاوااسکریپت، یک CMP از نوع TCF یک iframe خالی و نامرئی به نام __tcfapiLocator به صفحه سطح بالا اضافه میکند. یک CMP از نوع GPP همین کار را با فریمی به نام __gppLocator میکند. این فریمها محتوایی ندارند. تنها کارشان قابلپیدا بودن است: هر اسکریپتی در هر فریم تودرتو میتواند سلسلهمراتب پنجرهها را بالا برود و در هر سطح بررسی کند آیا فریمی با آن نام وجود دارد.
چون نام فریمها از طریق window.frames در سراسر originها دیده میشود، اسکریپتی در iframe cross-origin عمیقاً تودرتو میتواند پنجره میزبان CMP را بیابد بیآنکه به چیز دیگری در آن صفحه دسترسی داشته باشد.
اسکریپت درون فریم چگونه CMP را پیدا میکند
- از پنجره فعلی شروع کنید. اگر __tcfapi بهصورت محلی وجود دارد، مستقیم از آن استفاده کنید — اسکریپت در فریم نیست یا فریم CMP را به اشتراک میگذارد.
- در غیر این صورت، به بالا حلقه بزنید: بررسی کنید آیا پنجره فعلی فریمی به نام __tcfapiLocator دارد؛ اگر نه، به window.parent بروید و دوباره بررسی کنید و در پنجره سطح بالا متوقف شوید.
- وقتی locator پیدا شد، پنجرهای که آن را دربردارد پنجره CMP است. ارتباط اکنون از طریق postMessage انجام میشود.
هر دسترسی را در try/catch بپیچید، چون برخی مرورگرها یا تنظیمات sandbox هنگام دسترسی به ویژگی cross-origin خطا میاندازند، و وقتی window.parent برابر پنجره فعلی بود حلقه را متوقف کنید.
قالب پیام
در TCF، اسکریپت درون فریم پیامی به پنجره CMP میفرستد که شیئی با ویژگی __tcfapiCall دارد. درون آن چهار فیلد است:
- command — برای مثال getTCData، ping یا addEventListener؛
- parameter — هر آرگومانی که فرمان لازم دارد، یا null؛
- version — نسخه API، که در TCF v2 برابر ۲ است؛
- callId — مقداری یکتا که فراخواننده تولید میکند.
CMP به این پیامها گوش میدهد، فرمان را اجرا میکند و شیئی با ویژگی __tcfapiReturn بازمیفرستد که شامل returnValue، success و همان callId است. فراخواننده نگاشتی از callbackهای در انتظار را با کلید callId نگه میدارد، به رویدادهای message گوش میدهد و هر بازگشت را به callback درست میفرستد. GPP از همین الگو با __gppCall و __gppReturn پیروی میکند.
بسیاری از یکپارچگیها یک proxy کوچک مینویسند: تابعی محلی به نام __tcfapi درون فریم که فراخوانیها را به پیام ترجمه میکند. آنگاه کدی که برای پنجره سطح بالا نوشته شده بدون تغییر درون فریم کار میکند.
شنوندگان رویداد در سراسر فریمها
فراخوانی addEventListener که از طریق postMessage فرستاده میشود درخواست یکباره نیست. CMP هر بار که وضعیت رضایت تغییر کند یک پیام بازگشتی میفرستد، همه با همان callId. پس dispatcher شما باید آن callback را ثبتشده نگه دارد، نه اینکه پس از اولین پاسخ حذفش کند. فراموش کردن این یک باگ کلاسیک است: اسکریپت درون فریم رضایت را یک بار میخواند و هرگز پسگیری بعدی را متوجه نمیشود.
ملاحظات امنیتی
- شکل پیام را اعتبارسنجی کنید. هر پیامی را که ویژگی مورد انتظار را ندارد نادیده بگیرید و payloadهای رشتهای را با احتیاط parse کنید، چون برخی پیادهسازیها بهجای شیء رشته JSON میفرستند.
- کورکورانه اعتماد نکنید. هر صفحهای میتواند به فریم شما پیام بفرستد. پاسخها را سیگنال رضایتی بدانید که باید رعایت شود، نه داده احرازهویتشده، و هرگز نگذارید اقدامات دارای امتیاز را فعال کنند.
- در صورت امکان از origin هدف مشخص استفاده کنید. وقتی origin مربوط به CMP معلوم است، بهجای همه originها به همان بفرستید.
جایی که این الگو نمیرسد
برخی محیطهای تبلیغاتی کریتیوها را سختگیرانهتر جدا میکنند. کانتینرهای SafeFrame، iframeهای sandbox بدون مجوزهای لازم و کریتیوهایی که در اسناد جداگانه رندر میشوند ممکن است نتوانند درخت فریمها را بپیمایند یا پیام دریافت کنند. در این موارد، سیگنال رضایت معمولاً باید صریحاً منتقل شود، مثلاً بهصورت پارامترهای درخواست تبلیغ یا مقادیری که سرور تبلیغات به کریتیو میدهد، مانند پارامترهای gdpr و gdpr_consent که بسیاری از تگهای تبلیغاتی پشتیبانی میکنند.
چکلیست اشکالزدایی
- در DevTools پنجره سطح بالا، در پنل Elements تأیید کنید فریمهای locator وجود دارند.
- زمینه کنسول را به iframe تغییر دهید و بررسی کنید locator از آنجا در دسترس است.
- رویدادهای message ورودی را در هر دو پنجره لاگ کنید تا مطمئن شوید فراخوانیها و بازگشتها جریان دارند.
- رضایت را در بنر تغییر دهید و تأیید کنید شنوندگان درون فریم بهروزرسانی میگیرند.
- با بارگذاری دیرهنگام CMP آزمایش کنید تا مطمئن شوید کد درون فریم بهجای تسلیم فوری، دوباره تلاش میکند یا منتظر میماند.
نکات کلیدی
- فریمهای cross-origin از طریق فریمهای __tcfapiLocator و __gppLocator به CMP میرسند.
- فراخوانیها و بازگشتها از postMessage با __tcfapiCall/__tcfapiReturn یا معادلهای GPP استفاده میکنند و با callId تطبیق داده میشوند.
- callbackهای شنونده را ثبتشده نگه دارید تا تغییرات بعدی رضایت برسند.
- هر پیام را اعتبارسنجی کنید و آن را ورودی مورد اعتماد فرض نکنید.
- جایی که فریمها کاملاً ایزولهاند، رضایت را صریحاً روی درخواست تبلیغ منتقل کنید.