스크립트는 폴링이 아니라 리스닝을 해야 하는 이유

동의에 의존하는 모든 스크립트(광고 태그, 분석 로더, 헤더 비딩 래퍼 등)는 두 가지를 알아야 합니다. 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)은 대부분의 통합에서 사용해야 하는 명령입니다. 콜백은 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] — 벤더의 글로벌 벤더 목록 ID를 사용하는 벤더별 상태.
• tcData.gdprApplies — CMP가 이 방문자에게 GDPR이 적용된다고 판단했는지 여부. false이면 스크립트는 비TCF 로직을 따라야 합니다.
• tcData.tcString — 인코딩된 문자열로, 이를 기대하는 파트너에게 전달합니다.

목적과 벤더를 모두 확인하십시오. 벤더 동의 없이 목적 동의만 있거나 그 반대인 경우, 대부분의 벤더는 데이터를 처리하기에 충분하다고 보지 않습니다.

iframe과 크로스 프레임 호출

광고와 위젯은 종종 부모 페이지의 __tcfapi를 볼 수 없는 iframe 안에서 실행됩니다. TCF는 postMessage 프로토콜로 이를 해결합니다. CMP가 최상위 페이지에 __tcfapiLocator라는 이름의 프레임을 추가하면, iframe 내부 코드가 이를 찾아 __tcfapiCall 메시지를 보내고 __tcfapiReturn 응답을 받을 수 있습니다. 대부분의 광고 SDK는 이미 이렇게 합니다. 직접 iframe 코드를 작성한다면 프레임 간에 쿠키를 읽는 대신 같은 패턴을 구현하십시오.

흔한 버그와 발견 방법

1. cmpuishown에서 동작하기. 어떤 콜백이든 실행되자마자 로드되는 스크립트는 사용자가 결정하기 전에 실행됩니다. eventStatus로 필터링하십시오.
2. 리스너를 너무 일찍 제거하기. 첫 번째 콜백 후에 제거하면 이후의 useractioncomplete를 놓쳐 로드되지 않습니다.
3. 철회 무시하기. 지속적으로 실행되는 스크립트는 계속 리스닝하다가 동의가 철회되면 스스로 중지하거나 재구성해야 합니다.
4. gdprApplies 무시하기. TCF 적용 지역 밖에서는 목적 객체가 비어 있을 수 있습니다. 이를 “동의 없음”으로 처리하면 얻을 수 있는 수익을 꺼 버릴 수 있습니다.
5. 성공 플래그를 확인하지 않기. success가 false이면 로그를 남기십시오. 보통 CMP 설정이 잘못되었다는 신호입니다.

통합 테스트

브라우저 콘솔에서 __tcfapi('ping', 2, console.log)를 호출하여 CMP가 있는지 확인한 다음, console.log를 콜백으로 리스너를 등록하고 배너를 클릭해 보십시오. 첫 방문에서는 cmpuishown 다음에 useractioncomplete가, 새로고침 시에는 tcloaded가 보여야 합니다. 모두 수락, 모두 거부, 사용자 지정 선택으로 각각 반복하여 스크립트가 모든 경우에 올바르게 동작하는지 확인하십시오.

핵심 요약

• CMP 쿠키를 읽거나 폴링하는 대신 __tcfapi를 사용하십시오.
• API를 호출하는 모든 스크립트보다 CMP 스텁이 먼저 로드되도록 하십시오.
• addEventListener를 사용하고 tcloaded 또는 useractioncomplete에서만 동작하십시오.
• 목적과 벤더 상태를 모두 확인하고 gdprApplies를 준수하십시오.
• iframe 안에서는 __tcfapiLocator postMessage 패턴을 사용하십시오.