Γιατί τα scripts σας πρέπει να ακούν, όχι να κάνουν polling

Κάθε script που εξαρτάται από τη συναίνεση — ένα ad tag, ένας loader analytics, ένα header bidding wrapper — πρέπει να γνωρίζει δύο πράγματα: αν το CMP έχει ήδη απόφαση και ποια είναι αυτή. Ένα συνηθισμένο λάθος είναι η ανάγνωση ενός cookie κατά τη φόρτωση της σελίδας ή το polling του CMP με χρονόμετρο μέχρι να εμφανιστεί κάτι. Και οι δύο προσεγγίσεις αποτυγχάνουν με προβλέψιμους τρόπους: η μορφή του cookie είναι εσωτερική υπόθεση του CMP και μπορεί να αλλάξει, ενώ το polling είτε ενεργοποιείται πολύ νωρίς είτε σπαταλά χρόνο περιμένοντας.

Το IAB TCF ορίζει μια τυποποιημένη διεπαφή JavaScript ακριβώς γι' αυτή τη δουλειά: τη συνάρτηση __tcfapi. Αυτός ο οδηγός περνά από τις εντολές που πραγματικά χρειάζεστε, τα συμβάντα που θα λάβετε και τα σφάλματα που εμφανίζονται συχνότερα στην παραγωγή.

Το stub και η ουρά

Ένα CMP του TCF οφείλει να τοποθετεί ένα μικρό stub στη σελίδα όσο το δυνατόν νωρίτερα, πριν φορτώσει το πλήρες script του CMP. Το stub ορίζει το window.__tcfapi και βάζει σε ουρά τις κλήσεις που γίνονται πριν το CMP είναι έτοιμο. Όταν το CMP ολοκληρώσει τη φόρτωση, επεξεργάζεται την ουρά και απαντά σε κάθε κλήση.

Αυτό κάνει ασφαλές για άλλα scripts να καλούν το __tcfapi αμέσως: εφόσον το stub βρίσκεται στη σελίδα πριν από αυτά, οι κλήσεις τους δεν χάνονται. Αν ένα script πετάει σφάλμα επειδή το __tcfapi είναι undefined, το 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) όταν το script σας δεν χρειάζεται πλέον ενημερώσεις — για παράδειγμα, ένας loader μίας χρήσης που έχει ήδη πάρει την απόφασή του.

Ανάγνωση του eventStatus

Το βασικό πεδίο στο tcData είναι το eventStatus. Υπάρχουν τρεις τιμές:

• tcloaded — το CMP βρήκε έγκυρη αποθηκευμένη απόφαση και δεν θα εμφανιστεί banner. Μπορείτε να ενεργήσετε αμέσως πάνω στα δεδομένα.
• cmpuishown — το banner εμφανίζεται. Τα δεδομένα αντανακλούν την προηγούμενη κατάσταση, αλλά ο χρήστης μπορεί να είναι έτοιμος να την αλλάξει.
• useractioncomplete — ο χρήστης μόλις έκανε ή επιβεβαίωσε μια επιλογή. Ενεργήστε με βάση τα νέα δεδομένα.

Ένας τυπικός loader περιμένει είτε το tcloaded είτε το useractioncomplete και μετά ελέγχει τους σκοπούς και τους προμηθευτές που χρειάζεται. Αγνοεί το cmpuishown, εκτός ίσως για να καταγράψει ότι εμφανίστηκε banner.

Έλεγχος σκοπών και προμηθευτών

Μέσα στο tcData, η συναίνεση και το έννομο συμφέρον εκτίθενται ως αντικείμενα με κλειδί το ID:

• tcData.purpose.consents[1] — συναίνεση για τον Σκοπό 1 (αποθήκευση στη συσκευή).
• tcData.purpose.legitimateInterests[7] — κατάσταση εννόμου συμφέροντος για τον Σκοπό 7.
• tcData.vendor.consents[ID] και tcData.vendor.legitimateInterests[ID] — κατάσταση ανά προμηθευτή, με το ID του προμηθευτή στη Global Vendor List.
• tcData.gdprApplies — αν το CMP έκρινε ότι ο GDPR εφαρμόζεται σε αυτόν τον επισκέπτη. Αν είναι false, το script σας πρέπει να ακολουθήσει τη λογική του εκτός TCF.
• tcData.tcString — το κωδικοποιημένο string, που περνάτε στους συνεργάτες που το περιμένουν.

Ελέγξτε και τον σκοπό και τον προμηθευτή. Συναίνεση σκοπού χωρίς συναίνεση προμηθευτή, ή το αντίστροφο, δεν αρκεί για τους περισσότερους προμηθευτές ώστε να επεξεργαστούν δεδομένα.

Iframes και κλήσεις μεταξύ frames

Οι διαφημίσεις και τα widgets εκτελούνται συχνά μέσα σε iframes που δεν βλέπουν το __tcfapi της γονικής σελίδας. Το TCF το λύνει με ένα πρωτόκολλο postMessage: το CMP προσθέτει ένα frame με όνομα __tcfapiLocator στην κορυφαία σελίδα, και ο κώδικας μέσα σε ένα iframe μπορεί να το εντοπίσει, να στείλει μήνυμα __tcfapiCall και να λάβει απάντηση __tcfapiReturn. Τα περισσότερα ad SDKs το κάνουν ήδη. Αν γράφετε δικό σας κώδικα iframe, υλοποιήστε το ίδιο μοτίβο αντί να διαβάζετε cookies μεταξύ frames.

Συνηθισμένα σφάλματα και πώς να τα εντοπίσετε

1. Ενέργεια στο cmpuishown. Scripts που φορτώνουν μόλις ενεργοποιηθεί οποιοδήποτε callback θα τρέξουν πριν αποφασίσει ο χρήστης. Φιλτράρετε με βάση το eventStatus.
2. Πολύ πρόωρη αφαίρεση του listener. Αν τον αφαιρέσετε μετά το πρώτο callback, θα χάσετε ένα μεταγενέστερο useractioncomplete και δεν θα φορτώσει ποτέ.
3. Αγνόηση των ανακλήσεων. Τα μόνιμα scripts πρέπει να συνεχίζουν να ακούν και να σταματούν ή να αναδιαμορφώνονται όταν ανακαλείται η συναίνεση.
4. Αγνόηση του gdprApplies. Εκτός περιοχών TCF, τα αντικείμενα σκοπών μπορεί να είναι κενά· αν το αντιμετωπίσετε ως «καμία συναίνεση», μπορεί να απενεργοποιήσετε έσοδα που δικαιούστε να αποκτήσετε.
5. Μη έλεγχος της σημαίας επιτυχίας. Όταν το success είναι false, καταγράψτε το· συνήθως υποδηλώνει χαλασμένη ρύθμιση του CMP.

Δοκιμή της ενσωμάτωσής σας

Στην κονσόλα του προγράμματος περιήγησης, καλέστε __tcfapi('ping', 2, console.log) για να επιβεβαιώσετε ότι το CMP υπάρχει, και μετά καταχωρήστε έναν listener με το console.log ως callback και περάστε από το banner. Θα πρέπει να δείτε cmpuishown και μετά useractioncomplete στην πρώτη επίσκεψη, και tcloaded σε επαναφόρτωση. Επαναλάβετε με αποδοχή όλων, απόρριψη όλων και προσαρμοσμένη επιλογή, και επιβεβαιώστε ότι το script συμπεριφέρεται σωστά σε κάθε περίπτωση.

Βασικά συμπεράσματα

• Χρησιμοποιήστε το __tcfapi αντί να διαβάζετε cookies του CMP ή να κάνετε polling.
• Βεβαιωθείτε ότι το stub του CMP φορτώνει πριν από οποιοδήποτε script καλεί το API.
• Χρησιμοποιήστε το addEventListener και ενεργήστε μόνο στα tcloaded ή useractioncomplete.
• Ελέγξτε την κατάσταση και του σκοπού και του προμηθευτή, και σεβαστείτε το gdprApplies.
• Χρησιμοποιήστε το μοτίβο postMessage με το __tcfapiLocator μέσα σε iframes.