교차 출처 iframe 내부의 동의: __tcfapiLocator와 __gppLocator 패턴
문제: 동의는 최상위 창에 있습니다
CMP는 페이지의 최상위 창에서 실행됩니다. 그러나 광고의 상당수는 그렇지 않습니다. 디스플레이 크리에이티브, 리치 미디어, 헤더 비딩 렌더러, 많은 제3자 위젯은 종종 다른 오리진의 iframe 안에서 실행됩니다. 교차 출처 iframe 안의 코드는 부모 페이지의 함수를 직접 호출할 수 없으므로, 단순히 __tcfapi나 __gpp를 호출해 방문자의 선택을 읽을 수 없습니다.
IAB 프레임워크는 작고 명확하게 정의된 메시징 규약으로 이를 해결합니다. 프레임 안에서 실행되는 광고 제품, 임베드, 측정 스크립트를 만들거나 그런 광고 스택을 디버깅한다면, 이것이 정확히 어떻게 작동하는지 알아 둘 가치가 있습니다.
로케이터 프레임
JavaScript API와 함께, TCF CMP는 __tcfapiLocator라는 이름의 비어 있고 보이지 않는 iframe을 최상위 페이지에 추가합니다. GPP CMP는 __gppLocator라는 이름의 프레임으로 같은 일을 합니다. 이 프레임에는 콘텐츠가 없습니다. 유일한 역할은 찾을 수 있게 되는 것입니다. 어떤 중첩된 프레임 안의 어떤 스크립트든 창 계층을 따라 올라가며 각 수준에 해당 이름의 프레임이 있는지 확인할 수 있습니다.
프레임 이름은 window.frames를 통해 오리진을 넘어 보이므로, 깊이 중첩된 교차 출처 iframe 안의 스크립트는 해당 페이지의 다른 어떤 것에도 접근하지 않고 CMP를 호스팅하는 창을 찾을 수 있습니다.
프레임 안의 스크립트가 CMP를 찾는 방법
- 현재 창에서 시작합니다. __tcfapi가 로컬에 존재하면 직접 사용합니다. 스크립트가 프레임 안에 있지 않거나, 프레임이 CMP를 공유하는 경우입니다.
- 그렇지 않으면 위로 반복합니다. 현재 창에 __tcfapiLocator라는 이름의 프레임이 있는지 확인하고, 없으면 window.parent로 이동해 다시 확인하며, 최상위 창에서 멈춥니다.
- 로케이터를 찾으면, 그것을 포함한 창이 CMP의 창입니다. 이제 통신은 postMessage를 통해 이루어집니다.
일부 브라우저나 샌드박스 설정은 교차 출처 속성 접근 시 예외를 던지므로 각 접근을 try/catch로 감싸고, window.parent가 현재 창과 같아지면 반복을 멈추십시오.
메시지 형식
TCF의 경우, 프레임 안의 스크립트는 __tcfapiCall 속성을 가진 객체가 담긴 메시지를 CMP 창에 게시합니다. 그 안에는 네 개의 필드가 있습니다.
- command — 예: getTCData, ping, addEventListener
- parameter — 명령에 필요한 인수, 또는 null
- version — API 버전, TCF v2는 2
- callId — 호출자가 생성하는 고유한 값
CMP는 이 메시지를 수신하고, 명령을 실행하며, returnValue, success, 그리고 동일한 callId를 담은 __tcfapiReturn 속성을 가진 객체를 다시 게시합니다. 호출자는 callId를 키로 하는 대기 중인 콜백의 맵을 유지하고, message 이벤트를 수신하며, 각 반환값을 올바른 콜백에 전달합니다. GPP는 __gppCall과 __gppReturn으로 같은 패턴을 따릅니다.
많은 통합이 작은 프록시를 작성합니다. 프레임 안에 __tcfapi라는 이름의 로컬 함수를 두어 호출을 메시지로 변환하는 것입니다. 이렇게 하면 최상위 창용으로 작성된 코드가 프레임 안에서도 수정 없이 작동합니다.
프레임 간 이벤트 리스너
postMessage로 전송된 addEventListener 호출은 일회성 요청이 아닙니다. CMP는 동의 상태가 바뀔 때마다 동일한 callId를 가진 반환 메시지를 게시합니다. 따라서 디스패처는 첫 응답 후에 콜백을 삭제하지 말고 계속 등록해 두어야 합니다. 이를 잊는 것은 전형적인 버그입니다. 프레임 안의 스크립트가 동의를 한 번만 읽고 이후의 철회를 알아차리지 못합니다.
보안 고려 사항
- 메시지 형태를 검증하십시오. 예상되는 속성을 포함하지 않은 메시지는 무시하고, 일부 구현이 객체가 아닌 JSON 문자열을 보내므로 문자열 페이로드는 방어적으로 파싱하십시오.
- 맹목적으로 신뢰하지 마십시오. 어떤 페이지든 귀하의 프레임에 메시지를 게시할 수 있습니다. 응답을 인증된 데이터가 아니라 존중해야 할 동의 신호로 취급하고, 특권 작업을 유발하도록 두지 마십시오.
- 가능한 경우 특정 대상 오리진을 사용하십시오. CMP 오리진을 알고 있다면 모든 오리진이 아니라 그곳으로 게시하십시오.
이 패턴이 닿지 않는 곳
일부 광고 환경은 크리에이티브를 더 엄격하게 격리합니다. SafeFrame 컨테이너, 적절한 권한이 없는 샌드박스 iframe, 별도의 문서에서 렌더링되는 크리에이티브는 프레임 트리를 탐색하거나 메시지를 받지 못할 수 있습니다. 그런 경우 동의 신호는 보통 명시적으로 전달되어야 합니다. 예를 들어 광고 요청의 매개변수로, 또는 많은 광고 태그가 지원하는 gdpr와 gdpr_consent 매개변수처럼 광고 서버가 크리에이티브에 넘겨주는 값으로 전달합니다.
디버깅 체크리스트
- 최상위 창의 DevTools에서 Elements 패널에 로케이터 프레임이 존재하는지 확인합니다.
- 콘솔 컨텍스트를 iframe으로 전환하고 거기서 로케이터에 접근할 수 있는지 확인합니다.
- 두 창 모두에서 수신되는 message 이벤트를 기록하여 호출과 반환이 흐르는지 확인합니다.
- 배너에서 동의를 변경하고 프레임 안의 리스너가 업데이트를 받는지 확인합니다.
- CMP를 늦게 로드한 상태로 테스트하여, 프레임 안의 코드가 즉시 포기하지 않고 재시도하거나 기다리는지 확인합니다.
핵심 요약
- 교차 출처 프레임은 __tcfapiLocator와 __gppLocator 프레임을 통해 CMP에 도달합니다.
- 호출과 반환은 __tcfapiCall/__tcfapiReturn 또는 GPP의 대응 항목과 함께 postMessage를 사용하며, callId로 짝을 맞춥니다.
- 이후의 동의 변경이 도달하도록 리스너 콜백을 등록된 상태로 유지하십시오.
- 모든 메시지를 검증하고 신뢰할 수 있는 입력으로 취급하지 마십시오.
- 프레임이 완전히 격리된 곳에서는 광고 요청에 동의를 명시적으로 전달하십시오.