რატომ უნდა უსმენდნენ თქვენი სკრიპტები და არ აკეთებდნენ პოლინგს

ნებისმიერ სკრიპტს, რომელიც თანხმობაზეა დამოკიდებული — სარეკლამო თეგი, ანალიტიკის ჩამტვირთავი, header bidding-ის ვრაპერი — ორი რამ უნდა იცოდეს: აქვს თუ არა CMP-ს უკვე გადაწყვეტილება და რა არის ის. გავრცელებული შეცდომაა ქუქი-ფაილის წაკითხვა გვერდის ჩატვირთვისას ან CMP-ის ტაიმერით პოლინგი, სანამ რამე გამოჩნდება. ორივე მიდგომა წინასწარ განჭვრეტადი გზით ფუჭდება: ქუქი-ფაილის ფორმატი CMP-ის შიდა საქმეა და შეიძლება შეიცვალოს, ხოლო პოლინგი ან ძალიან ადრე გააქტიურდება, ან დროს ტყუილად ხარჯავს ლოდინში.

IAB TCF სწორედ ამ საქმისთვის განსაზღვრავს სტანდარტულ JavaScript ინტერფეისს: __tcfapi ფუნქციას. ეს სახელმძღვანელო განიხილავს ბრძანებებს, რომლებიც რეალურად გჭირდებათ, მოვლენებს, რომლებსაც მიიღებთ, და შეცდომებს, რომლებიც პროდაქშენში ყველაზე ხშირად ჩნდება.

სტაბი და რიგი

TCF CMP-ისგან მოსალოდნელია, რომ გვერდზე პატარა სტაბს რაც შეიძლება ადრე განათავსებს, სრული 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-ში თანხმობა და კანონიერი ინტერესი წარმოდგენილია ID-ით გასაღებიან ობიექტებად:

• tcData.purpose.consents[1] — თანხმობა მიზანზე 1 (მოწყობილობაზე შენახვა).
• tcData.purpose.legitimateInterests[7] — კანონიერი ინტერესის სტატუსი მიზანზე 7.
• tcData.vendor.consents[ID] და tcData.vendor.legitimateInterests[ID] — თითოეული ვენდორის სტატუსი ვენდორის Global Vendor List ID-ის გამოყენებით.
• 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. გაიმეორეთ ყველას მიღებით, ყველაზე უარის თქმით და მორგებული არჩევანით და დარწმუნდით, რომ თქვენი სკრიპტი თითოეულ შემთხვევაში სწორად იქცევა.

ძირითადი დასკვნები

• გამოიყენეთ __tcfapi CMP-ის ქუქი-ფაილების კითხვის ან პოლინგის ნაცვლად.
• დარწმუნდით, რომ CMP სტაბი API-ს გამომძახებელ ნებისმიერ სკრიპტამდე იტვირთება.
• გამოიყენეთ addEventListener და იმოქმედეთ მხოლოდ tcloaded-ზე ან useractioncomplete-ზე.
• შეამოწმეთ როგორც მიზნის, ისე ვენდორის სტატუსი და გაითვალისწინეთ gdprApplies.
• iframe-ებში გამოიყენეთ __tcfapiLocator postMessage შაბლონი.