თანხმობა cross-origin iframe-ებში: __tcfapiLocator და __gppLocator შაბლონი
პრობლემა: თანხმობა ზედა ფანჯარაში ცხოვრობს
CMP თქვენს გვერდზე, უმაღლესი დონის ფანჯარაში მუშაობს. თქვენი რეკლამის დიდი ნაწილი კი არა. Display კრეატივები, rich media, header bidding-ის რენდერერები და მესამე მხარის ბევრი ვიჯეტი iframe-ებში მუშაობს, ხშირად სხვა origin-ზე. კოდს cross-origin iframe-ში არ შეუძლია მშობელ გვერდზე ფუნქციის პირდაპირ გამოძახება, ამიტომ ვერ გამოიძახებს უბრალოდ __tcfapi-ს ან __gpp-ს და ვერ წაიკითხავს ვიზიტორის არჩევანს.
IAB ჩარჩოები ამას პატარა, კარგად განსაზღვრული შეტყობინებების კონვენციით ხსნიან. თუ აგებთ სარეკლამო პროდუქტებს, embed-ებს ან გაზომვის სკრიპტებს, რომლებიც ფრეიმებში მუშაობს, ან აღმოფხვრით სარეკლამო სტეკებს, რომლებიც ამას აკეთებენ, ღირს ზუსტად იცოდეთ, როგორ მუშაობს ის.
Locator ფრეიმი
JavaScript API-სთან ერთად TCF CMP უმაღლესი დონის გვერდს ამატებს ცარიელ, უხილავ iframe-ს სახელად __tcfapiLocator. GPP CMP იგივეს აკეთებს ფრეიმით სახელად __gppLocator. ფრეიმებს კონტენტი არ აქვთ. მათი ერთადერთი დანიშნულება ის არის, რომ ნაპოვნი იქნან: ნებისმიერ ჩადგმულ ფრეიმში მყოფ ნებისმიერ სკრიპტს შეუძლია ფანჯრების იერარქიაში ზევით ასვლა და შემოწმება, არის თუ არა თითოეულ დონეზე ამ სახელის მქონე ფრეიმი.
რადგან ფრეიმების სახელები origin-ებს შორის window.frames-ის მეშვეობით ხილულია, ღრმად ჩადგმულ cross-origin iframe-ში მყოფ სკრიპტს შეუძლია იპოვოს ფანჯარა, რომელიც 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-სთვის 2;
- callId — უნიკალური მნიშვნელობა, რომელსაც გამომძახებელი აგენერირებს.
CMP ამ შეტყობინებებს უსმენს, ასრულებს ბრძანებას და უკან აგზავნის ობიექტს თვისებით __tcfapiReturn, რომელიც შეიცავს returnValue-ს, success-სა და იმავე callId-ს. გამომძახებელი ინახავს მოლოდინში მყოფი callback-ების რუკას callId-ის მიხედვით, უსმენს message event-ებს და თითოეულ დაბრუნებას სწორ callback-ზე ანაწილებს. GPP იგივე შაბლონს მისდევს __gppCall-ითა და __gppReturn-ით.
ბევრი ინტეგრაცია წერს პატარა proxy-ს: ლოკალურ ფუნქციას სახელად __tcfapi ფრეიმის შიგნით, რომელიც გამოძახებებს შეტყობინებებად თარგმნის. ზედა ფანჯრისთვის დაწერილი კოდი მაშინ ფრეიმშიც უცვლელად მუშაობს.
Event listener-ები ფრეიმებს შორის
postMessage-ით გაგზავნილი addEventListener გამოძახება ერთჯერადი მოთხოვნა არ არის. CMP თანხმობის მდგომარეობის ყოველი ცვლილებისას უკან შეტყობინებას გამოაგზავნის, ყველა იმავე callId-ით. ამიტომ თქვენმა dispatcher-მა ეს callback რეგისტრირებული უნდა დატოვოს და არ უნდა წაშალოს პირველი პასუხის შემდეგ. ამის დავიწყება კლასიკური შეცდომაა: ფრეიმში მყოფი სკრიპტი თანხმობას ერთხელ კითხულობს და მოგვიანებით გამოთხოვას ვერასოდეს ამჩნევს.
უსაფრთხოების მოსაზრებები
- გადაამოწმეთ შეტყობინების ფორმა. უგულებელყავით ნებისმიერი შეტყობინება, რომელიც მოსალოდნელ თვისებას არ შეიცავს, და string payload-ები ფრთხილად დაამუშავეთ, რადგან ზოგი იმპლემენტაცია ობიექტების ნაცვლად JSON string-ებს აგზავნის.
- ბრმად ნუ ენდობით. ნებისმიერ გვერდს შეუძლია თქვენს ფრეიმზე შეტყობინებების გაგზავნა. პასუხები განიხილეთ როგორც თანხმობის სიგნალები, რომლებსაც უნდა პატივი სცეთ, და არა როგორც ავთენტიფიცირებული მონაცემები, და არასოდეს დაუშვათ, რომ პრივილეგირებული მოქმედებები გამოიწვიონ.
- სადაც შეგიძლიათ, კონკრეტული target origin-ები გამოიყენეთ. როცა CMP-ის origin ცნობილია, გაუგზავნეთ მას და არა ყველა origin-ს.
სადაც შაბლონი ვერ აღწევს
ზოგი სარეკლამო გარემო კრეატივებს უფრო მკაცრად აიზოლირებს. SafeFrame კონტეინერებმა, სათანადო ნებართვების გარეშე sandbox-ირებულმა iframe-ებმა და ცალკე დოკუმენტებში რენდერირებულმა კრეატივებმა შესაძლოა ფრეიმების ხეში ასვლა ან შეტყობინებების მიღება ვერ შეძლონ. ასეთ შემთხვევებში თანხმობის სიგნალი ჩვეულებრივ ცალსახად უნდა გადაიცეს, მაგალითად, სარეკლამო მოთხოვნის პარამეტრებად ან მნიშვნელობებად, რომლებსაც ad server კრეატივს გადასცემს, როგორიცაა gdpr და gdpr_consent პარამეტრები, რომლებსაც სარეკლამო ტეგების უმეტესობა უჭერს მხარს.
გამართვის ჩეკლისტი
- ზედა ფანჯრის DevTools-ში დარწმუნდით, რომ locator ფრეიმები Elements პანელში არსებობს.
- კონსოლის კონტექსტი გადართეთ iframe-ზე და შეამოწმეთ, ხელმისაწვდომია თუ არა locator იქიდან.
- ორივე ფანჯარაში ჩაწერეთ შემომავალი message event-ები, რათა დარწმუნდეთ, რომ გამოძახებები და დაბრუნებები მიედინება.
- შეცვალეთ თანხმობა ბანერში და გადაამოწმეთ, რომ ფრეიმებში მყოფი listener-ები განახლებას იღებენ.
- გატესტეთ CMP-ის გვიან ჩატვირთვით, რათა დარწმუნდეთ, რომ ფრეიმებში მყოფი კოდი ხელახლა ცდილობს ან ელოდება და ერთბაშად არ ნებდება.
მთავარი დასკვნები
- Cross-origin ფრეიმები CMP-ს __tcfapiLocator და __gppLocator ფრეიმების მეშვეობით აღწევენ.
- გამოძახებები და დაბრუნებები postMessage-ს იყენებს __tcfapiCall/__tcfapiReturn-ით ან GPP-ის ექვივალენტებით, callId-ით შეწყვილებულს.
- listener callback-ები რეგისტრირებული დატოვეთ, რათა თანხმობის შემდგომი ცვლილებები მიაღწიოს.
- გადაამოწმეთ ყოველი შეტყობინება და ნუ მიიჩნევთ მას სანდო შეყვანად.
- სადაც ფრეიმები სრულად იზოლირებულია, თანხმობა ცალსახად გადასცეთ სარეკლამო მოთხოვნაში.