Browser SDK 2 이벤트 확인

이벤트는 귀하의 track()호출과 Amplitude의 서버 사이에서 4단계를 거쳐 이동합니다. 각 단계를 순서대로 확인합니다. 이벤트가 잘못 보이는 첫 번째 단계가 바로 문제가 있는 곳입니다.

모든 Amplitude SDK에 공통적으로 발생하는 문제에 대해서는 SDK 문제 해결 및 디버깅으로 이동하십시오. SDK 업그레이드 후 동작이 변경된 경우 Browser SDK 2 릴리즈 노트를 확인하십시오.

디버그 로깅 켜기

확인하는 동안 Debug를 logLevel로 설정합니다. 디버그 로그에는 모든 공개 메소드 호출, 전후의 내부 상태, 최종 이벤트 및 서버 응답이 포함됩니다.

ts
amplitude.init("YOUR_API_KEY", {
  logLevel: amplitude.Types.LogLevel.Debug,
});

Google 태그 관리자와 같이 열거형을 가져올 수 없는 환경에서는 숫자 를 사용하십시오4. 수준은 0None, 1 Error, 2 Warn (기본값), 3 Verbose 및 4Debug입니다. 각 메시지는 Amplitude Logger로 시작하므로 해당 접두어로 콘솔을 필터링하십시오.

Google 태그 관리자에서 숫자를 사용하십시오

. 문자열(예: "LogLevel.None")은 전달하지 마십시오. SDK는 숫자로 logLevel비교하므로 숫자가 아닌 문자열은 디버그를 포함한 모든 수준에서 작동합니다.

출시하기 전에 Warn로 돌아갑니다logLevel. 디버그 출력에는 이벤트 페이로드와 식별자가 포함됩니다.

SDK가 캡처한 내용을 확인하십시오.

디버그 로깅이 켜져 있으면 각 공개 호출은 다음과 같은 블록을 출력합니다.

text
Amplitude Logger [Debug]: {
  "type": "invoke public method",
  "name": "track",
  "args": ["Sign Up Clicked", { "plan": "starter" }],
  "stacktrace": ["at handleClick (app.js:42:13)", "..."],
  "time": { "start": "2026-10-26T12:00:11.402Z", "end": "2026-10-26T12:00:12.611Z" },
  "states": {
    "before": { "config.apiKey": "...", "timeline.queue.length": 0 },
    "after": { "config.apiKey": "...", "timeline.queue.length": 0 }
  }
}

track(), identify()및 flush()와 같이 Promise를 반환하는 메서드의 경우 SDK는 Promise가 해결된 후 블록을 인쇄합니다. 따라서 track블록은 업로드 시도 후, 호출 후 약 1초 후에 나타납니다.

세 가지 사항을 확인하십시오:

  • 호출이 실행되었습니다. track블록이 나타납니다. 그렇지 않은 경우, 코드가 호출에 도달하지 않았거나 호출한 인스턴스에서 실행되지 않은 것입니다. init()``createInstance()의 두 번째 인스턴스는 자체 init()가 필요합니다. 페이지가 글로벌 amplitude를 노출하는 시기(스크립트 로더가 노출함)를 확인하려면 브라우저 콘솔에서 amplitude.init("YOUR_API_KEY")를 실행하십시오. 대기열에 이벤트가 있으면 전송되는데, 자체 init()호출이 실행되지 않았거나 다른 인스턴스에서 실행되었습니다.
  • 인수가 옳습니다. args는 SDK가 수신한 것과 정확하게 같은 이벤트 이름과 속성을 보여줍니다.
  • SDK가 준비되었습니다. 완료 전에 init()수행된 호출은 실패하지 않습니다. 이들은 대기열에서 대기하고 init()이후 실행되므로 로그에 일찍 나타나는 호출은 여전히 나중에 전송할 수 있습니다.

이 단계에서는 SDK가 모든 이벤트에 첨부하는 상태를 확인할 수도 있습니다:

ts
amplitude.getDeviceId(); // "f3b6c1e2-..."
amplitude.getUserId(); // "user-12345" or undefined
amplitude.getSessionId(); // 1761480000000
amplitude.getOptOut(); // false

getOptOut()가 true를 반환하는 경우 SDK는 플러그인이 실행되기 전에 모든 이벤트를 삭제합니다. getOptOut()을(를) 사용하려면 Browser SDK 2.18.0 이상이 필요합니다.

플러그인이 이벤트를 어떻게 변환했는지 확인하십시오.

캡처 후 각 이벤트는 고정된 순서로 플러그인 파이프라인을 통과합니다.

  1. 플러그인 전(type: "before"): 내장 컨텍스트 플러그인은 device_id, user_id, session_id, time, event_id, insert_id, library, user_agent, platform, language 및 ip을(를) 추가합니다. 브라우저가 오프라인 상태인 동안 네트워크 검사기는 업로드를 일시 중지합니다.
  2. 강화 플러그인(type: "enrichment", 기본값): 자동 캡처 플러그인은 여기에 속성을 추가합니다. 예를 들어 페이지 URL 보강은 이를 추가하며[Amplitude] Page URL, [Amplitude] Previous Page Location속성은 캠페인 매개 변수를 추가합니다. 자체 보강 플러그인도 여기에서 추가한 순서대로 실행됩니다.
  3. 목적지 플러그인(type: "destination"): 내장 목적지는 업로드를 위해 이벤트를 amplitude대기열에 넣습니다.

null을 반환하는 before 또는 enrichment 플러그인은 null이벤트를 삭제합니다. 변경 또는 드롭의 원인이 되는 플러그인을 찾으려면 logLevel 을(를) Verbose 또는 Debug(으)로 설정하십시오. 그런 다음 SDK는 각 단계를 기록합니다.

text
Amplitude Logger [Log]: Timeline.apply: Event after enrichment plugin 'my-plugin', event: {...}
Amplitude Logger [Log]: Timeline.apply: Event filtered out by enrichment plugin 'my-plugin', event: {...}
Amplitude Logger [Log]: Timeline.apply: Final event before destinations, event: {...}

Final event before destinations 행은 SDK가 전송하는 정확한 이벤트입니다. 당신이 기대하는 것과 비교해 보세요.

자동화된 테스트와 같이 코드에서 이벤트를 검사하려면 각 이벤트를 어디에도 전송하지 않고 기록하는 목적지 플러그인을 추가하십시오:

ts
const captured: amplitude.Types.Event[] = [];
amplitude.add({
  name: "inspect-events",
  type: "destination",
  execute: async (event) => {
    captured.push(structuredClone(event));
    return { event, code: 200, message: "inspected" };
  },
});

목적지 플러그인은 모든 before 및 enrichment 플러그인이 실행된 후에 이벤트를 수신합니다. 완료되면 amplitude.remove("inspect-events") 을(를) 사용하여 플러그인을 제거하십시오.

SDK가 전송한 내용을 확인하십시오.

SDK는 요청과 함께 이벤트를 POST업로드합니다. 브라우저의 네트워크 탭을 열고 데이터 센터에 대한 호스트에서 필터를 지정합니다.

첫 번째 이벤트가 큐에 들어온 후 요청은 브라우저를 flushIntervalMillis 떠납니다(기본적으로 1초). 각 요청은 최대 flushQueueSize(기본적으로 30)개의 이벤트를 전달합니다. 즉시 전송하려면 await amplitude.flush().promise를 호출하십시오.

요청 본문은 다음과 같은 형태를 갖습니다:

json
{
  "api_key": "YOUR_API_KEY",
  "events": [
    {
      "event_type": "Sign Up Clicked",
      "event_properties": { "plan": "starter" },
      "device_id": "f3b6c1e2-...",
      "session_id": 1761480000000,
      "time": 1761480012345,
      "event_id": 4,
      "insert_id": "9c0e...",
      "platform": "Web",
      "language": "en-US",
      "ip": "$remote",
      "library": "amplitude-ts/2.49.3",
      "user_agent": "Mozilla/5.0 ..."
    }
  ],
  "options": {},
  "client_upload_time": "2026-10-26T12:00:12.400Z"
}

"ip": "$remote" Amplitude에 요청의 IP 주소를 사용하도록 지시합니다. trackingOptions.ipAddress로 설정하여 false생략합니다.

DevTools를 열지 않고 이벤트를 확인하려면 Amplitude Instrumentation 탐색기 Chrome 확장 프로그램을 설치하십시오. 페이지가 전송하는 각 이벤트와 해당 속성을 나열합니다.

압축된 요청 본문

: Amplitude의 자체 엔드포인트의 경우, 브라우저가 지원하면 SDK는 2KB 이상의 요청 본문을 gzip으로 압축합니다CompressionStream. 이러한 요청에는 Content-Encoding: gzip헤더가 포함되며 페이로드 탭에는 바이너리 데이터가 표시됩니다. 이벤트를 읽으려면 대신 Final event before destinations로그 라인이나 검사 플러그인을 사용하십시오. 이 기본값은 2.42.0에서 변경되었습니다.

요청이 나타나지 않는 경우:

Amplitude가 받은 내용을 확인하십시오.

업로드 결과 읽기

모든 추적 메서드는 { promise }를 반환합니다. 업로드 시도가 완료된 후 promise는 Result로 확인됩니다.

ts
const { event, code, message } =
  await amplitude.track("Sign Up Clicked").promise;

event 는 전송된 마지막 이벤트입니다. code 및 message는 서버 응답에서 또는 SDK에서 가져옵니다.

성공적인 응답 본문은 다음과 같습니다:

json
{
  "code": 200,
  "events_ingested": 1,
  "payload_size_bytes": 412,
  "server_upload_time": 1761480012612
}

200응답은 Amplitude의 수집 API가 이벤트를 수락했음을 의미합니다. Amplitude는 여전히 블록 필터가 일치하는 경우와 같이 허용된 이벤트를 나중에 분석에서 제외할 수 있습니다.

수동 플러시(Manual flushes)

amplitude.flush()는 대기열에 있는 모든 이벤트를 한 번 전송하며, 실패한 이벤트를 재시도하지 않습니다. 각 이벤트의 promise는 응답 상태와 본문을 메시지로 사용하여 해결됩니다(예: success: {"code": 200, ...} 또는 invalid: {...}). 예약된 업로드는 다시 시도하고 테이블의 메시지를 사용합니다.

Amplitude에서 이벤트를 찾습니다.

  1. 사용자 조회를 열고 이벤트의 user_id를 검색하며, 사용자가 익명인 경우 device_id를 검색합니다.
  2. 활동 탭을 선택하고 라이브 이벤트 업데이트를 켭니다.
  3. 이벤트를 열고 해당 속성을 Final event before destinations로그 행과 비교합니다.

많은 사용자가 보낸 이벤트의 경우 수집 디버거를 사용하여 프로젝트에 대해 허용된 요청과 거부된 요청을 검토합니다. Amplitude의 차트 쿼리는 사용자 조회보다 새로운 이벤트를 포함하는 데 몇 분 더 걸릴 수 있습니다.

이 내용이 도움이 되었나요?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

이 페이지에서