설명서Experience Platform데이터 수집

Adobe 클라이언트 데이터 레이어 문제 해결

마지막 업데이트: 2026년 11월 13일

작성 대상:

  • 중급
  • 개발자

이 페이지에서는 Adobe 클라이언트 데이터 레이어(ACDL)의 일반적인 문제를 진단할 수 있습니다. 대부분의 검사는 브라우저의 개발자 콘솔을 사용합니다.

데이터 레이어 검사 inspect

콘솔에서 다음 명령을 실행합니다.

명령
결과
adobeDataLayer.version
ACDL 버전(예: "3.0.1"). undefined인 경우 ACDL이 로드되지 않았습니다.
adobeDataLayer.getState()
계산 상태입니다.
adobeDataLayer
처리된 순서대로 데이터 및 이벤트 개체의 history입니다.

이벤트가 발생할 때 이를 보려면 임시 수신자를 추가합니다.

adobeDataLayer.addEventListener("adobeDataLayer:event", function(event) {
  console.log("ACDL event:", event.event, event);
}, { scope: "future" });

콘솔 메시지 console-messages

메시지
원인 및 해결 방법
The following item cannot be handled by the data layer because it does not have a valid format: ...
문자열 또는 배열과 같이 일반 개체나 함수가 아닌 값을 푸시했습니다. 메시지에 표시된 값을 푸시하는 코드를 찾습니다. 잘못된 항목을(를) 참조하십시오.
Adobe Client Data Layer v... has already been imported/initialized on this page. You may be erroneously loading it a second time.
라이브러리가 두 번 이상 로드되었습니다. 첫 번째 복사본이 계속 작동합니다. 추가 복사본을 제거합니다. 라이브러리를 한 번만 로드를 참조하십시오.
TypeError: adobeDataLayer.getState is not a function(또는 addEventListener, removeEventListener)
라이브러리가 로드되기 전에 ACDL 메서드가 호출된 코드입니다. 대신 푸시하는 함수에서 호출합니다. Call 메서드를 안전하게을(를) 참조하십시오.
ReferenceError: structuredClone is not defined
브라우저가 ACDL 3.x가 지원하는 것보다 오래되었습니다. 브라우저 요구 사항을 참조하세요.
TypeError: Cannot read properties of null (reading 'event')
코드가 null 또는 undefined을(를) 푸시했습니다.
RangeError: Maximum call stack size exceeded
리스너는 자신을 트리거하는 무엇인가를 밀어냅니다. 무한 루프 방지를 참조하십시오.

JavaScript 오류 메시지의 문구는 브라우저마다 약간 다릅니다. 예를 들어 Safari는 ReferenceError: Can't find variable: structuredClone을(를) 보고합니다.

ACDL이 로드되지 않음 not-loaded

adobeDataLayer.version이(가) undefined인 경우 다음을 확인하십시오.

  • 라이브러리가 페이지에 없습니다. 네트워크 패널에서 adobe-client-data-layer.min.js을(를) 확인하거나 태그 확장이 ACDL을 로드하는 경우 태그 라이브러리를 확인합니다. 컨텐츠 보안 정책에서 스크립트를 허용하는지 확인합니다.
  • adobeDataLayer은(는) 배열이 아닙니다. 다른 스크립트가 ACDL이 로드되기 전에 window.adobeDataLayer을(를) 배열이 아닌 다른 것으로 설정하면 ACDL이 연결되지 않습니다.
  • 스크립트가 배열을 대체했습니다. window.adobeDataLayer = [];과(와) 같은 코드는 데이터 레이어를 새로운 빈 배열로 대체하므로 ACDL 메서드, 계산된 상태 및 모든 리스너가 손실됩니다. 항상 window.adobeDataLayer = window.adobeDataLayer || [];을(를) 사용하십시오. 데이터 레이어 배열 만들기를 참조하십시오.
  • 대기 중인 함수에서 오류가 발생했습니다. ACDL이 로드되기 전에 푸시된 함수에서 오류가 발생하면 콘솔에 오류가 표시되고 해당 함수 후 큐에 있던 항목이 손실됩니다. 푸시한 함수 내에서 오류를 catch합니다.

수신기가 실행되지 않습니다. listener-not-called

다음을 확인하십시오.

  • 이벤트 이름이 일치하지 않습니다. 이벤트 이름은 대소문자를 구분하며 공백을 포함하여 정확히 일치해야 합니다.
  • 이벤트를 푸시한 후에 수신기가 추가되었으며 수신기가 future 범위를 사용합니다. 기본 all 범위를 사용합니다. 범위를 참조하세요.
  • 수신기를 추가하기 전에 기록이 지워졌으므로 재생할 내용이 없습니다. 내역 지우기를 참조하십시오.
  • path 옵션은 푸시를 필터링합니다. 경로가 있는 리스너는 해당 경로를 포함하는 푸시에 대해서만 실행됩니다. 경로을(를) 참조하세요.
  • 수신기가 추가되지 않았습니다. listener 인수가 함수가 아니거나 범위가 유효하지 않으면 ACDL이 수신기를 추가하지 않습니다. 대신 on 및 handler 등의 키가 adobeDataLayer.getState()에 나타납니다.
  • 이벤트에 대해 동일한 함수가 이미 등록되었습니다. ACDL은 다른 옵션이 있더라도 두 번째 등록을 무시합니다.
  • 이전 수신기에서 동일한 푸시에 대해 오류​을(를) throw하여 나머지 수신기를 중지합니다. 콘솔에서 오류를 확인합니다.
  • 푸시가 이벤트가 아닙니다. event 값이 없거나 비어 있거나 문자열이 아닌 개체는 데이터로 처리됩니다. 이벤트 수신기가 아니라 adobeDataLayer:change개의 수신기를 트리거합니다.

리스너가 예상보다 자주 실행됩니다. listener-called-too-often

  • 이전 이벤트를 재생합니다. 기본 all 범위를 사용하면 기록에 이미 있는 일치하는 이벤트에 대해 새 수신기가 실행됩니다. 이 동작은 예상되었습니다. 이전 이벤트가 이미 처리된 경우 future 범위를 사용하십시오.
  • 두 번 이상 추가되었습니다. 반복적으로 실행되고 매번 새로운 익명 함수를 전달하는 코드는 매번 새로운 리스너를 추가합니다. 명명된 함수를 사용합니다. 명명된 함수 사용을 참조하세요.
  • 경로를 사용합니다. 경로가 있는 리스너는 값이 변경되지 않았더라도 경로를 포함하는 모든 푸시에 대해 실행됩니다.

계산된 상태에서 데이터가 누락되었거나 잘못되었습니다. state-issues

  • 값이 event 또는 eventInfo(으)로 푸시되었습니다. 이 키는 계산된 상태로 저장되지 않습니다. 다른 키 아래에 데이터를 푸시합니다.
  • 배열 손실된 항목입니다. 배열을 푸시하면 전체 배열이 바뀝니다. 전체 배열을 푸시합니다. 배열을 참조하세요.
  • 개체가 문자열, 숫자 또는 부울을 바꾸지 않았습니다. 먼저 null을(를) 푸시하여 키를 삭제한 다음 개체를 푸시합니다. 값의 형식 변경을 참조하십시오.
  • 날짜 또는 함수가 빈 개체가 되었습니다. 날짜를 문자열 또는 숫자로 저장합니다. 값 형식을 참조하세요.
  • 결과 getState()에 대한 변경 내용이 적용되지 않았습니다. getState()이(가) 복사본을 반환합니다. 대신 변경 사항을 푸시합니다.
  • 경로가 있는 getState()이(가) undefined을(를) 반환합니다. 경로에 있는 모든 키의 철자를 확인합니다. 대괄호가 아닌 배열 인덱스(예: items.0.sku)에 점을 사용합니다. 경로에서 값 가져오기를 참조하십시오.

항목들이 내역에서 누락되었습니다. history-issues

  • 함수 및 잘못된 항목은 보관되지 않습니다. 데이터 개체와 이벤트 개체만 유지됩니다. ACDL 로드 후: 기록을 참조하십시오.
  • 수신기에서 오류가 발생했습니다. 리스너에서 오류가 발생하면 트리거된 항목이 계산된 상태를 업데이트하지만 기록에 추가되지 않습니다.
  • 한 push() 호출에 여러 종류의 항목이 포함되어 있습니다. 각 항목을 별도의 호출로 푸시합니다. 호출당 항목 한 개 푸시를 참조하십시오.
  • 기록이 지워졌습니다. 예를 들어 태그 확장의 데이터 레이어 기록 지우기 작업에 의해 지워졌습니다.
recommendation-more-help
experience-platform-help-collection