Browser SDK 2를 계측하고 구성하세요

이 가이드에서는 Get started 이후 Browser SDK 2를 사용한 일상적인 작업(자체 이벤트 추적, ID 및 세션 관리, 자동 캡처 기능 선택, 이벤트가 Amplitude에 전달되는 방식 제어)에 대해 설명합니다. 정확한 서명과 모든 옵션을 보려면 Reference로 이동하십시오. 기능이 추가되거나 변경된 릴리즈를 찾으려면 Browser SDK 2 릴리즈 노트를 참조하십시오.

이벤트 추적

브라우저 SDK 2는 사용자 지정 이벤트, 사용자 속성, 그룹 멤버십, 그룹 속성 및 수익이라는 5가지 유형의 데이터를 전송합니다. 각각 고유한 메서드를 가지고 있으며, 각 메서드는 업로드 시도 후에 해결되는 { promise }를 반환합니다. 트래킹 플랜에서 정의하는 이벤트에 대해 이러한 메서드를 사용하십시오. 페이지 뷰, 클릭, 양식 상호 작용 및 SDK가 코드 없이 수집할 수 있는 기타 이벤트에 대해서는 자동 캡처로 이동하십시오.

사용자 지정 이벤트 추적

이벤트 이름과 선택적으로 이벤트 속성 객체를 전달합니다.

ts
amplitude.track("Song Played", {
  title: "Here Comes the Sun",
  duration_seconds: 185,
  genres: ["rock", "pop"],
});

문자열, 숫자, 불리언, 배열 또는 중첩된 객체를 속성 값으로 사용합니다. 이벤트 이름은 비어 있지 않은 문자열이어야 합니다. SDK는 이름이 빈 이벤트를 삭제하고 Event skipped due to empty event type를 기록합니다.

logEvent() 는 동일한 인수를 가진 track()의 별칭입니다.

이벤트를 객체로 전달합니다.

이름과 속성보다 더 많은 필드를 설정하려면 BaseEvent객체를 전달하십시오. 이 양식은 groups, time, app_version 및 insert_id와 같이 HTTP V2 API가 허용하는 모든 필드를 허용합니다.

ts
amplitude.track({
  event_type: "Song Played",
  event_properties: { title: "Here Comes the Sun" },
  time: Date.now() - 60_000,
  insert_id: "song-played-8f2c",
});

자체 코드의 재시도 이후와 같이 동일한 이벤트가 두 번 전송될 수 있는 경우 insert_id에 설정합니다. Amplitude는 7일 내에 동일한 insert_id 및 device_id로 두 번째 이벤트를 무시합니다.

하나의 이벤트에 대한 ID 재정의

세 번째 인수에 이벤트 옵션을 user_id또는 device_id로 전달합니다. 재정의는 이 이벤트에만 적용됩니다. 이후 이벤트는 여전히 setUserId()및 setDeviceId()의 ID를 사용합니다.

ts
amplitude.track(
  "Invite Sent",
  { channel: "email" },
  {
    user_id: "user-12345",
  },
);

identify() 는 다르게 동작합니다. user_id또는 device_id를 identify()에 전달하면 setUserId()또는 setDeviceId()도 호출되며, 이는 이후 모든 이벤트의 ID를 변경합니다.

탐색하기 전에 이벤트를 기다립니다

SDK는 초에 한 번 정도 이벤트를 배치로 업로드합니다. 코드가 바로 track()이후에 페이지를 떠나는 경우, 먼저 프로미스를 기다리세요.

ts
await amplitude.track("Checkout Started").promise;
window.location.assign("/checkout");

기본 전송은 이미 keepalive를 fetch와 함께 전송하므로 대부분의 이벤트는 기다리지 않아도 페이지 전환 시 유지됩니다. 다음 페이지가 로드되기 전에 이벤트가 도착해야 할 때 기다립니다. 언로드 동작에 대한 자세한 내용은 데이터 전송으로 이동하십시오.

사용자 속성 설정

사용자 속성은 사용자를 설명하며 변경될 때까지 모든 이후 이벤트에 연결된 상태로 유지됩니다. Identify객체를 구축하고 하나 이상의 작업을 추가한 다음 identify()에 전달합니다.

ts
const identifyEvent = new amplitude.Identify()
  .set("plan", "pro")
  .setOnce("first_seen_at", "2026-10-26")
  .add("login_count", 1)
  .append("visited_sections", "billing");
amplitude.identify(identifyEvent);

SDK가 $identify이벤트를 전송합니다. 차트에는 이벤트로 나타나지 않지만 사용자의 속성을 업데이트합니다.

각 속성은 Identify객체당 하나의 작업에서만 나타날 수 있습니다. SDK는 동일한 키에 대한 두 번째 작업을 알림 없이 무시하므로 충돌하는 작업을 두 identify()개의 호출로 분할합니다.

초기화의 일부로 사용자 속성을 설정하여 첫 번째 자동 캡처된 이벤트 전에 적용되도록 하려면 Identify객체를 init()에 전달하십시오.

ts
amplitude.init("YOUR_API_KEY", "user-12345", {
  identify: new amplitude.Identify().set("plan", "pro"),
});

SDK는 새 세션이 시작될 때마다 세션의 시작 이벤트 전에 이 식별자를 전송합니다. 이 identify 옵션을 사용하려면 브라우저 SDK 2.25.0 이상이 필요합니다.

사용자를 그룹에 할당

그룹을 사용하면 계정 또는 조직 수준에서 행동을 분석할 수 있습니다. 그룹 분석에는 계정 추가 기능이 필요합니다.

setGroup() 는 현재 사용자를 특정 유형의 하나 이상의 그룹에 할당합니다. 할당은 사용자 속성과 마찬가지로 사용자에게 유지됩니다.

ts
amplitude.setGroup("company", "Acme Inc");
amplitude.setGroup("team", ["engineering", "design"]);

사용자의 그룹을 변경하지 않고 하나의 이벤트만 그룹과 연결하려면, 해당 이벤트에 groups다음을 설정하십시오:

ts
amplitude.track({
  event_type: "Report Exported",
  groups: { company: "Acme Inc" },
});

그룹 속성 설정

그룹 속성은 사용자가 아닌 그룹을 설명합니다. Identify객체와 함께 groupIdentify()(을)를 사용합니다. 모든 Identify 작업은 사용자 속성과 동일한 방식으로 작동합니다. 업데이트는 해당 시점 이후의 이벤트에만 적용됩니다.

ts
const groupProperties = new amplitude.Identify()
  .set("plan", "enterprise")
  .set("seats", 250);
amplitude.groupIdentify("company", "Acme Inc", groupProperties);

매출 추적

Revenue객체를 구축하고 이를 revenue()전달합니다. SDK는 Amplitude가 수익 분석을 위해 사용하는 revenue_amount이벤트를 전송합니다.

ts
const purchase = new amplitude.Revenue()
  .setProductId("com.example.pro-annual")
  .setPrice(99.99)
  .setQuantity(2)
  .setRevenueType("subscription")
  .setCurrency("USD")
  .setEventProperties({ coupon: "FALL26" });
amplitude.revenue(purchase);

Amplitude는 수익을 price * quantity(으)로 계산하며, 총액을 직접 설정하는 setRevenue()을(를) 호출하는 경우는 예외입니다. quantity의 기본값은 1이며, setQuantity()은(는) 0 이하의 값을 무시합니다. setPrice()은(는) 환불과 같은 경우에 음수 값을 허용합니다. 수익 확인에는 setRevenueType()및 setReceiptSig()가 필요합니다. 모든 setter에 대해 API 참조에서 Revenue로 이동하십시오.

Amplitude는 currency를 설정한 경우에만 수익을 프로젝트 통화로 변환합니다. 통화 전환 및 수익 이벤트 설정에 대한 자세한 내용은 수익 추적을 참조하십시오.

수익 데이터를 최대한 활용하려면 제품 배열 메서드를 사용하여 제품을 추적하십시오.

비디오 재생 추적

trackVideo() 는 HTML <video> 요소 또는 player.js 호환 내장 플레이어에서 Video Content Started및 Video Content Stopped이벤트를 전송합니다. 이 API는 실험 중이며 예고 없이 변경될 수 있습니다. Browser SDK 2.39.0 이상이 필요합니다.

ts
const video = document.querySelector("video");
if (video) {
  const stopTracking = amplitude.trackVideo(amplitude, video, {
    extraEventProperties: { placement: "homepage" },
  });
  // Later, when you no longer need video events:
  if (typeof stopTracking === "function") {
    stopTracking();
  }
}

하나의 trackVideo()호출에서 발생하는 모든 이벤트는 SDK가 생성하는 view_session_id동일한 UUID와 사용자의 추가 정보를 extraEventProperties포함합니다. 플레이어에 연결할 수 없는 경우, 해당 trackVideo()항목은 함수 Error대신 값을 반환합니다.

둘 이상의 프로젝트로 이벤트 보내기

각 Amplitude 프로젝트는 자체 API 키를 갖습니다. 두 프로젝트로 전송하려면 createInstance()로 두 번째 인스턴스를 생성하고 별도의 instanceName를 지정하십시오.

ts
amplitude.init("PRODUCTION_API_KEY");
const marketing = amplitude.createInstance();
marketing.init("MARKETING_API_KEY", {
  instanceName: "marketing",
});
amplitude.track("Signup Completed");
marketing.track("Signup Completed");

각 인스턴스는 고유한 사용자 ID, 장치 ID, 세션, 큐 및 플러그인을 유지합니다. API 키를 공유하는 인스턴스는 ID 쿠키를 공유하므로 각 프로젝트에 고유 키를 지정하십시오.

식별 및 세션

Browser SDK 2는 모든 이벤트에 장치 ID, 선택적 사용자 ID 및 세션 ID라는 세 가지 식별자를 연결합니다. Amplitude는 이를 사용하여 이벤트를 사용자와 세션에 병합합니다. SDK는 세 가지 모두와 옵트아웃 플래그를 저장하는데, 이는 API 키의 처음 10자가 뒤에 붙는 이름의 자사 쿠키에 저장되어 페이지 로드 및 하위 도메인 전반에서 유지됩니다.AMP_

SDK가 로드 시 식별자를 선택하는 방법

init()SDK는 값을 가진 첫 번째 소스에서 각 식별자를 가져옵니다.

기기 ID

  1. deviceId옵션.
  2. ampDeviceIdURL 매개 변수, 그리고 기존 deviceIdURL 매개 변수.
  3. AMP_쿠키.
  4. 유지 관리 JavaScript SDK(amp_ 접두사)에서 제공하는 쿠키입니다.
  5. 새 UUID입니다.

사용자 ID

  1. userId인수 또는 옵션입니다.
  2. AMP_쿠키.
  3. 유지 관리 JavaScript SDK의 쿠키입니다.

세션 ID

  1. sessionId옵션.
  2. ampSessionIdURL 매개변수입니다.
  3. 옵트아웃에 의해 연기된 세션입니다.
  4. AMP_마지막 이벤트가 이내에 발생한 경우, 쿠키sessionTimeout.
  5. Date.now().

SDK는 ampTimestamp매개변수가 존재하고 현재 시간보다 이전일 때 URL 매개변수를 무시합니다. 도메인 간 사용자 추적으로 이동합니다.

사용자 ID 설정

사용자가 로그인할 때 setUserId()를 호출합니다. 데이터베이스 ID와 같은 시스템에서 안정적이고 고유한 식별자를 사용하십시오. 이메일 주소가 변경될 수 있는 경우 사용하지 마십시오.

ts
amplitude.setUserId("user-12345");

새 사용자 ID는 이후 모든 이벤트에 적용되며 쿠키에 유지됩니다. 사용자 ID 및 장치 ID는 5자 이상이어야 합니다. 그렇지 않으면 Amplitude가 이벤트를 거부합니다. 더 짧은 ID를 허용하려면 init()를 minIdLength로 설정하십시오.

페이지 로드 시 사용자 ID를 알고 있는 경우 대신 init()에 전달하십시오. 그러면 첫 번째 자동 캡처된 이벤트에 해당 값이 표시됩니다.

ts
amplitude.init("YOUR_API_KEY", "user-12345");

사용자가 로그아웃할 때 ID 재설정

사용자가 로그아웃할 때 reset()를 호출합니다. 사용자 ID를 설정하고 새 장치 ID를 생성하므로 이 브라우저의 이후 활동이 로그아웃된 사용자로 병합되지 않습니다undefined.

ts
amplitude.reset();

reset() 는 새 세션을 시작하거나, Amplitude 서버에서 사용자 속성을 지우거나, 옵트아웃을 변경하지 않습니다. 플러그인은 해당 onReset()후크를 통해 이에 반응할 수 있습니다.

장치 ID 설정

SDK는 임의의 UUID를 장치 ID로 생성합니다. 서버나 모바일 앱과 공유되는 것처럼 이미 안정적인 익명 식별자가 있는 경우에만 자신의 식별자를 설정하십시오.

ts
amplitude.setDeviceId("2f9d6a1e-4b7c-4f0e-9a51-0c3e8b7d5a12");

장치당 고유하고 길이가 5자 이상의 값을 사용하십시오. 동일한 장치 ID를 가진 두 개의 브라우저는 Amplitude에서 한 사용자로 병합됩니다.

ID를 함께 읽고 업데이트

getIdentity() 는 이 페이지 로드에서 SDK가 추적한 현재 장치 ID, 사용자 ID 및 사용자 속성을 반환합니다. 브라우저 SDK 2.18.0 이상이 필요합니다.

ts
const { deviceId, userId, userProperties } = amplitude.getIdentity();

setIdentity() 는 세 가지의 모든 조합을 업데이트합니다. userProperties을(를) 포함하면 SDK는 $identify 이벤트를 전송하여 $set로 각 키를 설정합니다. setIdentity()에는 브라우저 SDK 2.35.0 이상이 필요합니다.

ts
amplitude.setIdentity({
  userId: "user-12345",
  userProperties: { plan: "pro" },
});

userProperties은(는) setIdentity()에서 제외한 속성을 해제하지 않습니다. 사용자 속성을 제거하려면 new amplitude.Identify().unset("key")를 전송합니다.

userProperties은(는) 이 페이지 로드에서 전송된 $set, $unset, 및 $clearAll작업만 반영합니다. Amplitude의 서버에서 사용자 속성을 읽지 않습니다.

세션 작동 방식

세션은 사용자가 한 번의 방문에서 트리거하는 이벤트를 그룹화합니다. ID는 세션의 첫 이벤트의 Unix 타임스탬프(밀리초)입니다.

  • SDK는 이전 이벤트 이후 sessionTimeout 이상 경과한 후에 이벤트가 도착하면 새 세션을 시작합니다. 기본 시간 제한은 30분입니다.
  • 마지막 이벤트 시간이 쿠키에 저장되므로 동일한 도메인의 페이지 로드와 탭 간에 세션이 계속됩니다.
  • 세션 자동 캡처가 켜져 있는 상태에서 (기본값), SDK는 각 세션 시작 시 session_start 를 전송하고 이전 세션이 끝날 때 session_end 를 전송합니다. Amplitude는 이를 [Amplitude] Start Session 및 [Amplitude] End Session 로 표시합니다. SDK는 사용자가 떠날 때가 아니라 다음 세션이 시작될 때 session_end를 전송합니다.
  • autocapture.attribution.resetSessionOnNewCampaign 가 true 로 설정된 경우, 새 캠페인도 새 세션을 시작합니다.

시간 초과를 변경하려면 sessionTimeout 값을 밀리초 단위로 설정합니다:

ts
amplitude.init("YOUR_API_KEY", {
  sessionTimeout: 60 * 60 * 1000, // 1 hour
});

Amplitude가 세션 길이와 세션 지표를 계산하는 방법을 확인하려면 세션 추적으로 이동하십시오.

이벤트 없이 세션을 유지합니다.

extendSession() 는 이벤트를 전송하지 않고 마지막 활동 시간을 업데이트합니다. 사용자가 긴 비디오를 보는 것처럼 SDK가 관찰할 수 없는 활동에 사용하십시오.

ts
amplitude.extendSession();

특정 ID로 세션 시작

setSessionId() 현재 세션을 종료하고 사용자가 전달한 ID로 세션을 시작합니다. Unix 타임스탬프를 밀리초 단위로 전달합니다.

ts
amplitude.setSessionId(Date.now());

세션 자동 캡처가 설정된 경우 SDK는 ID를 세션의 마지막 활동 시간으로 간주합니다. 최근 타임스탬프가 아닌 ID를 전달하는 경우 다음 이벤트가 sessionTimeout보다 늦게 나타나며 SDK는 ID를 새 세션으로 교체합니다. ID가 현재 세션 ID와 같으면setSessionId()는 아무것도 수행하지 않습니다.

도메인 간 사용자 추적

이 AMP_ 쿠키는 www.example.com및 app.example.com와 같은 하나의 등록 가능한 도메인과 해당 하위 도메인을 포함합니다. example.com및 example-shop.com와 같은 두 개의 다른 도메인에 걸쳐 하나의 익명 사용자와 세션을 유지하려면 링크 URL에 식별자를 전달합니다. ampDeviceId및 ampSessionId 매개변수를 사용하려면 브라우저 SDK 2.8.0 이상이 필요합니다.

  1. 소스 도메인에서 현재 ID를 읽고 링크에 추가합니다:

    ts
    const url = new URL("https://www.example-shop.com/cart");
    url.searchParams.set("ampDeviceId", amplitude.getDeviceId() ?? "");
    url.searchParams.set("ampSessionId", String(amplitude.getSessionId()));
    url.searchParams.set("ampTimestamp", String(Date.now() + 60_000));
    window.location.assign(url.toString());
    
  2. 목적지 도메인에서 deviceId또는 sessionId 옵션 없이 SDK를 초기화합니다. SDK는 매개변수를 자동으로 읽습니다.

    ts
    amplitude.init("YOUR_API_KEY");
    

ampTimestamp 는 링크가 작동하는 시간을 제한합니다. SDK는 ampDeviceId가 현재 시간보다 늦을 때만 ampSessionId와 ampTimestamp를 사용합니다. ampTimestamp가 없으면 매개변수가 만료되지 않으므로 공유 또는 북마크된 링크는 관련이 없는 방문자를 하나의 장치로 병합할 수 있습니다. ampTimestamp을(를) 사용하려면 브라우저 SDK 2.21.1 이상이 필요합니다.

사용자를 추적에서 해제합니다

setOptOut(true) 는 SDK가 이 브라우저에 대한 이벤트를 추적하거나 업로드하지 못하도록 합니다. 설정이 AMP_쿠키에 유지됩니다.

ts
amplitude.setOptOut(true);
// Later, after the user consents:
amplitude.setOptOut(false);

opt-out이 켜져 있는 경우:

  • 모든 추적 호출은 코드 0 및 Event skipped due to optOut config로 즉시 해결됩니다.
  • SDK는 세션을 시작하지 않습니다. 옵트아웃된 상태에서 init()가 실행되는 경우, SDK는 세션을 연기하고 setOptOut(false)를 호출할 때 시작합니다.
  • 페이지 보기 및 어트리뷰션 추적은 옵트아웃이 해제될 때 시작됩니다.

사용자가 동의할 때까지 옵트아웃된 상태로 시작하려면 optOut: true를 init()에 전달하십시오. 동의 배너, 지연된 초기화 및 쿠키 없는 저장소를 보려면 쿠키 및 동의 관리로 이동하십시오.

SDK가 ID를 저장하는 위치를 선택합니다.

identityStorage는 SDK가 장치 ID, 사용자 ID, 세션 ID 및 옵트아웃 플래그를 보관하는 위치를 제어합니다.

ts
amplitude.init("YOUR_API_KEY", {
  identityStorage: "localStorage",
});

기본적으로 SDK는 .example.com와 같이 가능한 한 최상위 도메인에 쿠키를 기록하므로 하위 도메인이 ID를 공유합니다. 각 수준에서 쿠키를 작성하고 삭제하여 해당 AMP_TLDTEST도메인을 찾습니다. 도메인을 고정하거나 다른 쿠키 속성을 변경하려면 cookieOptions를 설정합니다. 쿠키 옵션으로 이동합니다.

자동 캡처

자동 캡처는 Browser SDK 2가 코드 없이 일반적인 브라우저 이벤트를 추적하기 위해 init()설치하는 플러그인 세트입니다. 사용자는 autocapture 옵션으로 이를 제어하며, Amplitude 프로젝트의 원격 구성이 기능별 설정을 재정의할 수 있습니다. 일반적인 소개를 보려면 자동 캡처로 이동하십시오.

시작 지점 선택

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    elementInteractions: true,
    fileDownloads: false,
    pageViews: { trackHistoryChanges: "pathOnly" },
  },
});

Chrome 확장 프로그램에서 SDK는 기본 설정을 해제합니다. 원하는 각 기능을 true설정합니다. 이 기본값은 2.42.1에서 변경되었습니다.

autocapture 는 사용되지 않는 defaultTracking옵션을 대체합니다. 둘 다 설정하면 autocapture 이(가) 우선합니다.

기능 및 이벤트

모든 하위 옵션 및 기본값에 대해서는 구성 참조에서 자동 캡처 옵션으로 이동하십시오.

원격 구성이 로컬 설정을 우선합니다.

기본적으로 init()는 플러그인을 설치하기 전에 Amplitude에서 프로젝트의 원격 구성을 가져옵니다. _데이터 > 설정 > 자동 캡처_에서 원격 구성을 편집합니다. 원격 구성에서 설정하는 각 기능에 대해 해당 값이 사용자의 값을 대체합니다. 설정되지 않은 기능은 로컬 값을 유지합니다. 원격 구성을 사용하려면 Browser SDK 2.10.0 이상이 필요하며, 2.16.1에서 기본값이 on으로 변경되었습니다.

ts
// Local configuration
amplitude.init("YOUR_API_KEY", {
  autocapture: { pageViews: true, elementInteractions: true },
});
// Remote configuration: elementInteractions off, frustrationInteractions on
// Result: pageViews on, elementInteractions off, frustrationInteractions on

원격 구성은 autocapture: false를 설정하더라도 기능을 활성화할 수 있습니다. 로컬 설정을 최종 설정하려면 fetch를 해제하십시오:

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: false,
  remoteConfig: { fetchRemoteConfig: false },
});

가져오기는 https://sr-client-cfg.amplitude.com/config(또는 sr-client-cfg.eu.amplitude.com EU)로 이동합니다. SDK는 응답을 브라우저에 캐시하고 캐시 또는 네트워크에서 먼저 도착하는 응답을 적용합니다. 광고 차단기 또는 콘텐츠 보안 정책이 요청을 차단하는 경우, SDK는 캐시된 복사본을 사용하거나 캐시가 없는 경우 로컬 설정을 사용합니다. 자체 서버를 통해 라우팅하려면 remoteConfig.serverUrl(브라우저 SDK 2.28.0 이상)를 설정합니다.

마케팅 어트리뷰션

페이지가 로드될 때 어트리뷰션은 UTM 매개변수, 클릭 ID 및 참조자를 읽습니다. attribution.trackingMethod에 의해 제어되는 두 가지 독립적 방식으로 기록됩니다. 둘 모두 기본적으로 실행됩니다. eventProperty 메서드는 브라우저 SDK 2.40.0 이상이 필요하며, 2.45.0에서 기본값이 두 메서드 모두로 변경되었습니다.

SDK는 다음 매개변수를 읽습니다: utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id, referrer, referring_domain, dclid, fbclid, gbraid, gclid, ko_click_id, li_fat_id, msclkid, rdt_cid, ttclid, twclid, wbraid.

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    attribution: {
      trackingMethod: "userProperty",
      excludeReferrers: [/example\.com$/, "checkout.partner.com"],
      resetSessionOnNewCampaign: true,
    },
  },
});

이러한 옵션은 userProperty추적에만 적용됩니다.

  • excludeReferrers 는 일치하는 추천 도메인의 캠페인을 무시합니다. 기본적으로 자체 도메인과 해당 하위 도메인을 제외합니다. 설정하면 기본값이 대체되므로 자체 도메인을 포함하십시오.
  • excludeInternalReferrers 는 페이지와 동일한 도메인의 리퍼러를 무시합니다. true항상 무시하도록 설정하거나, URL에 UTM 매개 변수 또는 클릭 ID가 없는 경우에만 { condition: "always" }무시하도록{ condition: "ifEmptyCampaign" } 설정합니다. 브라우저 SDK 2.36.0 이상이 필요합니다.
  • initialEmptyValue 는 캠페인 값이 없는 initial_*속성의 값입니다. 기본값은 "EMPTY"입니다.
  • 캠페인이 변경될 때 새 세션을 시작합니다resetSessionOnNewCampaign.

fallbackAttributionEvent추적에만 eventProperty적용됩니다. 모든 페이지 보기에서 [Amplitude] Attribution이벤트를 전송하도록 설정하십시오. 그러면 사용자가 다른 이벤트를 트리거하지 않더라도 캠페인 데이터가 도착합니다.true

단일 페이지 앱은 캠페인 컨텍스트 잃음

단일 페이지 앱에서 document.referrer는 첫 번째 로드 후 변경되지 않으며, 라우터는 종종 쿼리 문자열을 제거합니다. 두 가지 결과:

  • userProperty 추적은 init()에서만 캠페인을 읽습니다. 나중에 pushState를 통해 표시되는 캠페인은 사용자 속성을 업데이트하지 않습니다.
  • eventProperty 추적은 각 탐색의 캠페인을 대체합니다. 사용자가 /?utm_source=newsletter에서 /pricing 로 이동한 후, 이후 이벤트에는 utm_source가 없지만 원래 referrer가 유지됩니다.

라우터가 URL을 재작성하기 전에 SDK를 초기화하고, 캠페인 매개 변수를 서버측 리디렉션에 유지하십시오. 랜딩 페이지 후에 리퍼러를 삭제하려면 enrichment 플러그인을 추가하십시오.

ts
const landingUrl = location.href;
amplitude.add({
  name: "drop-referrer-after-landing",
  execute: async (event) => {
    if (location.href !== landingUrl && event.event_properties) {
      delete event.event_properties.referrer;
      delete event.event_properties.referring_domain;
    }
    return event;
  },
});

페이지 뷰 수

SDK는 초기화 [Amplitude] Page Viewed시, 그리고 URL이 history.pushState()변경되거나 popstate이벤트(뒤로, 앞으로 및 해시 변경)를 통해 다시 history.replaceState()전송합니다. 이벤트는 페이지 보기를 트리거하지 않습니다.

다단계 양식

URL을 변경하지 않고 제자리에서 업데이트되는 다단계 양식은 하나의 페이지 보기를 생성합니다. 각 단계를 추적하려면 Google Tag Manager와 같이 각 단계의 URL에 해시를 추가하십시오.

각 페이지 보기에는 다음이 포함됩니다.

옵션:

  • trackOn 페이지 보기를 전송할 시기를 제어합니다. 모든 로드 및 URL 변경 시 전송하려면 이를 생략하십시오. 어트리뷰션이 캠페인"attribution"을 전송할 때만 페이지 보기를 전송하도록 설정합니다. 전송할 값을 반환하는 true함수를 설정합니다.
  • trackHistoryChanges어떤 URL 변경 사항이 카운트될지 제어합니다. 기본값은 쿼리 문자열과 해시를 포함하여 URL에 대한 모든 변경 사항에 대해 페이지 보기를 전송합니다. 동일한 오리진과 경로를 유지하는 변경 사항을 무시하려면 "pathOnly"를 설정합니다.
  • eventType 이벤트의 이름을 바꿉니다.
ts
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    pageViews: {
      trackOn: () => location.pathname.startsWith("/app"),
      trackHistoryChanges: "pathOnly",
    },
  },
});

페이지 보기 이벤트에 고유한 속성을 추가하려면 enrichment 플러그인을 사용하십시오. 작동하는 예제를 보려면 GitHub의 page-view-tracking-enrichment로 이동하십시오.

단일 페이지 앱의 페이지 제목

SDK는 pushState()가 반환되는 직후에 document.title 읽습니다. Angular, SvelteKit, React Router 등의 라우터는 종종 URL이 변경된 후 제목을 설정하므로 페이지 뷰에 이전 페이지의 제목이 기록됩니다. 이 문제를 해결하려면 페이지 보기를 끄고 제목을 설정한 후 라우터에서 페이지 보기를 추적하십시오.

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: { pageViews: false },
});
// Call from your router's navigation-end hook, after the title updates.
function trackPageView() {
  amplitude.track("[Amplitude] Page Viewed", {
    "[Amplitude] Page Domain": location.hostname,
    "[Amplitude] Page Location": location.href,
    "[Amplitude] Page Path": location.pathname,
    "[Amplitude] Page Title": document.title,
    "[Amplitude] Page URL": location.href.split("?")[0],
  });
}

스스로 추적하는 페이지 뷰에는 [Amplitude] Page Counter또는 [Amplitude] Page View ID가 포함되지 않습니다.

세션

SDK는 세션이 시작될 때 session_start 를 전송하며, 다음 세션이 시작될 때 이전 세션에 대한 session_end 를 전송합니다. Amplitude는 이를 [Amplitude] Start Session및 [Amplitude] End Session로 표시합니다. sessions: false에서는 SDK가 여전히 이벤트에 세션 ID를 할당합니다. 세션 규칙을 보려면 Identity 및 세션으로 이동합니다.

양식 상호작용

SDK는 <form> 요소를 추적합니다.

  • [Amplitude] Form Started 양식의 모든 필드에 대한 첫 번째 변경 사항에 대해.
  • [Amplitude] Form Submitted 제출 시 사용자가 필드를 변경하지 않고 제출하면 SDK가 먼저 Form Started를 전송합니다.

두 이벤트 모두 [Amplitude] Form ID, [Amplitude] Form Name및 [Amplitude] Form Destination (양식의 action URL)를 포함합니다.

입력이 유효하지 않은 경우에도 novalidate 속성이 있는 양식에서 submit 가 발생합니다. 어떤 제출이 카운트될지 결정하려면 shouldTrackSubmit (Browser SDK 2.34.0 이상)을 전달하세요:

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    formInteractions: {
      shouldTrackSubmit: (event) =>
        (event.target as HTMLFormElement).checkValidity(),
    },
  },
});

파일 다운로드

SDK는 사용자가 URL 경로가 pdf, xls, xlsx, doc, docx, txt, rtf, csv, exe, key, pps, ppt, pptx, 7z, pkg, rar, gz, zip, avi, mov, mp4, mpg, mpeg, wmv, mid, midi, mp3, wav 또는 wma 확장자 중 하나로 끝나는 <a> 요소를 클릭할 때 [Amplitude] File Downloaded를 전송합니다. 로드 후 추가된 링크도 감시합니다.

속성: [Amplitude] File Extension, [Amplitude] File Name (URL 경로), [Amplitude] Link ID, [Amplitude] Link Text및 [Amplitude] Link URL.

페이지 URL 보강

페이지 URL 강화는 사용자 지정 이벤트를 포함하여 모든 이벤트에 페이지 컨텍스트를 추가합니다: [Amplitude] Page Domain, [Amplitude] Page Location, [Amplitude] Page Path, [Amplitude] Page Title, [Amplitude] Page URL, [Amplitude] Previous Page Location, 및 [Amplitude] Previous Page Type. 이벤트에 이미 있는 속성을 덮어쓰지는 않습니다. 자세한 내용은 Page URL enrichment 플러그인을 참조하십시오. Browser SDK 2.22.0 이상이 필요하며, 2.29.0에서 기본값이 켜짐으로 변경되었습니다.

자동 캡처를 끄더라도 다음과 같이 직접 플러그인을 추가할 수 있습니다.

ts
import { pageUrlEnrichmentPlugin } from "@amplitude/plugin-page-url-enrichment-browser";
amplitude.add(pageUrlEnrichmentPlugin());
amplitude.init("YOUR_API_KEY", { autocapture: false });

요소 상호 작용

요소 상호 작용은 대화형 요소에 대해 [Amplitude] Element Clicked및 [Amplitude] Element Changed를 전송합니다. 시각적 라벨링 및 Zoning 인사이트는 이러한 이벤트에 따라 달라집니다. 수집된 데이터와 텍스트 마스킹의 작동 방식에 대해서는 자동 캡처 개인정보 보호 및 보안으로 이동하십시오.

기본적으로 SDK는 클릭 및 a, button, input, select, textarea, label, video, audio, [contenteditable="true"], [data-amp-default-track] 및 .amp-default-track에서의 변경 사항을 추적합니다. 또한 div, span, h1에서 발생하는 클릭을 h6를 통해 추적하며, 클릭이 DOM을 변경하거나 페이지를 이동시킵니다.

ts
import * as amplitude from "@amplitude/analytics-browser";
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    elementInteractions: {
      cssSelectorAllowlist: [
        ...amplitude.Types.DEFAULT_CSS_SELECTOR_ALLOWLIST,
        ".track-me",
      ],
      pageUrlExcludelist: [/\/admin\//],
      dataAttributePrefix: "data-analytics-",
    },
  },
});
  • cssSelectorAllowlist 가 기본 목록을 대체합니다. 확장하려면 DEFAULT_CSS_SELECTOR_ALLOWLISTSpread를 사용하세요. @amplitude/analytics-browser로 가져오세요. amplitude.Types.DEFAULT_CSS_SELECTOR_ALLOWLIST는 이를 @amplitude/plugin-autocapture-browser내보내지 않습니다.
  • actionClickAllowlist페이지를 변경하는 클릭에 대한 제목 목록을 div대체합니다span. []좁힐 때 cssSelectorAllowlist설정하여 선택기만 계산되도록 합니다.
  • pageUrlAllowlist페이지 URL별로 추적을 pageUrlExcludelist제한합니다. 제외 목록이 우선합니다.
  • shouldTrackEventResolver 는 요소별로 결정합니다. 설정하면 SDK는 허용 목록을 무시합니다.
  • data- 는 일치하는 dataAttributePrefix 속성을 속성으로 캡처합니다. 기본값은 data-amp-track-이므로, data-amp-track-plan="pro"는 plan 속성이 됩니다.
  • maskTextRegex 는 SDK의 내장 마스킹 외에도 패턴과 일치하는 텍스트를 마스킹합니다.
  • shadowDomEnabled (실험적 기능)은 열린 섀도우 루트 내의 상호 작용을 maxShadowDomDepth경계(기본값 1, 최대 10)까지 캡처합니다. 켜진 후에는 다음 전체 페이지가 로드될 때까지 켜진 상태로 유지됩니다.

이벤트 속성에는 [Amplitude] Element ID, [Amplitude] Element Class, [Amplitude] Element Tag, [Amplitude] Element Text(클릭 전용), [Amplitude] Element Href(클릭 전용), [Amplitude] Element Position Left, [Amplitude] Element Position Top, [Amplitude] Element Hierarchy, [Amplitude] Element Path(요소에 대한 CSS 선택기), [Amplitude] Element Attributes, [Amplitude] Element Aria Label, [Amplitude] Element Parent Label, [Amplitude] Viewport Height, [Amplitude] Viewport Width, [Amplitude] Page URL 및 [Amplitude] Page Title이 포함됩니다.

불만스러운 상호 작용

frustrationInteractions: true 를 통해 분노 클릭 및 무반응 클릭이 활성화됩니다. 오류 클릭 및 스래시 커서는 개별적으로 켜기 전까지 꺼져 있습니다. 불편 행동 상호 작용을 사용하려면 브라우저 SDK 2.24.0 이상이 필요합니다.

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    frustrationInteractions: {
      rageClicks: true,
      deadClicks: { cssSelectorAllowlist: ["button", "a"] },
      errorClicks: true,
      thrashedCursor: { directionChanges: 12, threshold: 1500 },
    },
  },
});

데드 클릭 및 오류 클릭은 cssSelectorAllowlist를 설정하지 않으면 상호 작용 요소 목록인 DEFAULT_DEAD_CLICK_ALLOWLIST 및 DEFAULT_ERROR_CLICK_ALLOWLIST를 사용합니다. 선택기를 보려면 GitHub의 frustration-interactions.ts로 이동하십시오.

각 신호도 pageUrlAllowlist, pageUrlExcludelist, shouldTrackEventResolver, dataAttributePrefix, 및 maskTextRegex를 frustrationInteractions 수준에서 허용합니다.

네트워크 추적

네트워크 추적은 fetch 및 XMLHttpRequest 호출에 대해 [Amplitude] Network Request 데이터를 전송합니다. 기본적으로 상태가 599 에서 500 사이인 응답만 캡처하며, Amplitude에 대한 요청을 무시합니다. 브라우저 SDK 2.17.0 이상이 필요합니다.

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    networkTracking: {
      ignoreHosts: ["*.example-cdn.com"],
      captureRules: [
        { statusCodeRange: "400-599" },
        {
          urls: [/https:\/\/api\.example\.com\/orders/],
          methods: ["POST"],
          statusCodeRange: "0,200-599",
          responseHeaders: true,
          responseBody: { allowlist: ["order/id", "order/status"] },
        },
      ],
    },
  },
});

SDK는 마지막에서 처음으로 확인하고 URL과 일치하는 첫 번째 규칙을 적용하므로 일반 규칙 다음에 특정 규칙을 넣습니다captureRules. 각 규칙은 다음을 허용합니다.

  • urls (문자열 또는 RegExp, * 지원) 또는 이전의 hosts. 모든 URL과 일치하려면 두 항목을 모두 생략하십시오.
  • methods, 예를 들어 ["POST", "PUT"]. 기본값: all.
  • statusCodeRange, 쉼표로 구분된 코드 및 범위 목록입니다. 기본값: "500-599". 0는 응답 없이 실패한 요청과 일치합니다.
  • requestHeaders 및 responseHeaders: content-type및 cache-control와 같이 민감하지 않은 고정된 헤더 세트를 캡처합니다. true배열은 사용자가 나열하는 이름을 정확하게 캡처합니다.
  • requestBody 및 responseBody: JSON 본문만 해당합니다. allowlist는 유지할 JSON 포인터를 나열합니다(** 는 하나의 키와 일치, * 는 모든 깊이와 일치). excludelist는 허용목록과 일치하는 키를 제거합니다. 사용자가 허용목록을 설정하지 않는 한 SDK는 본문 콘텐츠를 캡처하지 않습니다.

예를 들어, 이 본문으로:

json
{ "a": "A", "b": { "c": "C", "d": { "e": "E", "f": "F" } }, "g": "G" }

이벤트 속성: [Amplitude] URL (민감한 부분이 마스킹된 경우), [Amplitude] URL Query, [Amplitude] URL Fragment, [Amplitude] Request Method, [Amplitude] Status Code, [Amplitude] Error Code, [Amplitude] Error Message, [Amplitude] Start Time, [Amplitude] Completion Time, [Amplitude] Duration, [Amplitude] Request Body Size, [Amplitude] Response Body Size, 그리고 구성된 경우 [Amplitude] Request Body, [Amplitude] Response Body, [Amplitude] Request Headers, 및 [Amplitude] Response Headers.

웹 바이탈

Web vitals는 탭이 처음 숨겨질 때 페이지 로드당 하나의 [Amplitude] Web Vitals 이벤트를 전송합니다. 브라우저가 보고할 때 [Amplitude] LCP, [Amplitude] FCP, [Amplitude] INP, [Amplitude] CLS, [Amplitude] TTFB이(가) 포함되며, Plus 페이지 도메인, 위치, 경로, 제목 및 URL도 포함됩니다. 지표 정의를 보려면 web.dev: LCP, FCP, INP, CLS 및 TTFB로 이동하십시오. 브라우저 SDK 2.20.0 이상이 필요합니다.

단일 페이지 앱에서 소프트 네비게이션당 하나의 이벤트를 전송하도록 webVitals: { reportSoftNav: true }(실험)을 설정합니다. 이를 위해서는 Soft Navigations API(Chromium 151 이상)가 필요합니다. 다른 브라우저는 초기 로드만 보고합니다.

성능 추적

성능 추적은 메인 스레드가 최소 100ms 동안 바쁜 상태일 때 [Amplitude] Main Thread Block를 전송합니다. 사용 가능한 경우 Long Animation Frames API를 사용하며 Long Tasks로 대체합니다. autocapture: true 는 이를 활성화하지 않습니다. 브라우저 SDK 2.41.0 이상이 필요합니다.

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    performanceTracking: {
      mainThreadBlock: { durationThreshold: 200 },
    },
  },
});

데이터 전송

브라우저 SDK 2는 각 이벤트를 추적되는 즉시 전송하지 않습니다. 이벤트를 localStorage의 대기열에 저장하고 일괄 업로드하며, 실패한 업로드는 재시도합니다. 이 섹션에서는 해당 동작을 변경하는 각 설정에 대해 설명합니다. 기본값은 대부분의 사이트에 적합합니다. 탐색에서 이벤트가 누락된 경우, 네트워크가 Amplitude의 도메인을 차단할 때, 또는 특정 데이터 영역이 필요한 경우 이를 변경하십시오.

SDK가 이벤트를 업로드하는 방법

  1. track()이벤트를 인메모리 대기열에 추가하고 대기열을 AMP_unsent_아래에 API 키의 처음 10자를 더해서 기록합니다localStorage.
  2. flushIntervalMillis (기본 1000) 첫 번째 이벤트가 대기열에 진입하면 SDK는 전체 대기열을 전송하며, 이를 최대 flushQueueSize (기본 30) 이벤트의 요청으로 분할합니다. 이벤트를 순서대로 유지하기 위해 요청이 한 번에 하나씩 전송됩니다. 대기열이 꽉 찬 경우 조기 업로드가 트리거되지 않습니다.
  3. 200응답 시 SDK는 대기열과 스토리지에서 이벤트를 제거합니다.
  4. 실패 시 SDK가 재시도합니다. 네트워크 오류 및 5xx응답 후에는 시도할 때마다 대기 시간이 1초씩 증가합니다. Throttled 이벤트(429)는 30초를 기다립니다. A 413는 flushQueueSize를 반으로 줄입니다. flushMaxRetries(기본값 5) 시도가 완료되면 SDK는 이벤트를 삭제합니다.
  5. 다음 페이지 로드 시 SDK는 여전히 localStorage에 있는 모든 이벤트를 전송합니다.

localStorage 에는 최대 1,000개의 미전송 이벤트가 포함됩니다. 예를 들어 오프라인 기간이 길어져 대기열이 이 값을 초과할 경우 SDK는 Failed to save N events because the queue length exceeded 1000 로그를 남기고 추가 이벤트는 유지하지 않습니다. localStorage를 사용할 수 없는 경우 SDK는 메모리에만 대기열을 유지하고 경고를 기록합니다.

ts
amplitude.init("YOUR_API_KEY", {
  flushIntervalMillis: 5000,
  flushQueueSize: 50,
  flushMaxRetries: 3,
});

지금 대기열을 전송하려면 flush()를 호출하십시오. 대기열에 있는 모든 이벤트를 재시도 없이 한 번만 전송합니다.

ts
await amplitude.flush().promise;

업로드 성능 조정

track() 는 네트워크를 기다리지 않습니다. SDK는 이벤트를 대기열에 넣고 백그라운드에서 업로드되므로 대부분의 튜닝은 요청 수와 지연 시간 간의 절충 관계입니다:

  • 요청 감소: flushIntervalMillis을 높입니다. 이벤트는 업로드되기 전에 더 오래 기다립니다. 페이지가 먼저 닫히면 사용자의 다음 방문 시까지 localStorage그대로 유지됩니다.
  • 더 빠른 전송: 더 낮은 flushIntervalMillis. SDK는 더 많은, 더 작은 요청을 전송합니다.
  • 더 큰 요청: 단일 플러시에서 종종 30개 이상의 이벤트를 포함할 경우 flushQueueSize를 증가시킵니다. 각 요청에는 더 많은 이벤트가 포함되므로 바쁜 큐에는 필요한 요청이 줄어듭니다. 요청이 너무 큰 경우, Amplitude는 413를 반환하고 SDK는 flushQueueSize를 반으로 줄입니다.
  • 대용량 소스: useBatch: true를 설정하여 속도 제한이 더 높은 Batch Event Upload API로 전송하세요. 요청 수를 줄이지는 않습니다.

현재 번들 크기에 대해서는 npm 패키지 페이지 또는 BundlePhobia를 확인하십시오.

데이터 영역을 선택하세요

Amplitude 조직의 데이터 센터로 serverZone설정합니다. 기본값은 US입니다.

ts
amplitude.init("YOUR_API_KEY", {
  serverZone: "EU",
});

useBatch: true 는 대용량 소스에 대해 더 높은 속도 제한을 적용하는 Batch Event Upload API(/batch)로 전환합니다. SDK가 브라우저에서 이벤트를 일괄 처리하는 방식을 변경하지 않습니다.

콘텐츠 보안 정책에서 Amplitude 허용

사이트에서 Content-Security-Policy헤더를 전송하는 경우 Amplitude의 도메인을 허용하십시오.

text
script-src  https://*.amplitude.com;
connect-src https://*.amplitude.com;

스크립트 로더를 사용하여 Amplitude의 CDN에서 SDK를 로드할 script-src때만 필요합니다. connect-src이 도구는 이벤트 업로드, 원격 구성 및 SDK 진단을 다룹니다. 모든 트래픽을 자체 도메인을 통해 프록시하는 경우 대신 해당 도메인을 허용하십시오.

페이지가 언로드될 때 이벤트 전송

브라우저는 페이지가 언로드될 때 Inflight 요청을 취소하므로 리디렉션되는 로그인과 같이 탐색 직전에 추적된 이벤트를 잃을 수 있습니다.

기본 fetch 전송 방식은 본문이 16KB 이하인 요청에 대해 설정하므로 keepalive브라우저는 페이지가 언로드된 후 해당 요청을 완료합니다. Keepalive는 압축, 사용자 지정 헤더, 응답 및 재시도를 유지합니다. 브라우저는 페이지의 모든 전송 중인 요청에 대해 64KB keepalive 예산을 공유하며, 이것이 SDK가 해당 예산을 포함하지 않고 더 큰 본문을 전송하는 이유입니다. SDK는 압축 후 본문을 측정합니다. 예산이 꽉 찬 경우 브라우저가 keepalive 요청을 거부하면 SDK는 다음 플러시 시 재시도합니다. keepalive를 지원하지 않는 브라우저는 플래그를 무시하고 일반 요청을 전송합니다.

16KB보다 큰 본문의 경우 페이지가 숨겨질 때 beacon전송으로 전환하십시오.

ts
window.addEventListener("pagehide", () => {
  amplitude.setTransport("beacon");
  amplitude.flush();
});

sendBeacon 는 요청을 브라우저로 전달하고 즉시 반환합니다. 다음과 같은 제한이 있습니다.

  • 응답이 없으므로 SDK가 실패를 재시도할 수 없습니다. 브라우저가 수락한 요청을 성공으로 간주합니다.
  • 사용자 지정 헤더가 없으므로 압축이 없습니다.
  • 요청 간 순서가 보장되지 않습니다.

keepalive를 끄려면(예: keepalive 관련 실패를 디버깅할 때) enableKeepalive: false다음을 설정합니다.

ts
amplitude.init("YOUR_API_KEY", {
  transport: { type: "fetch", enableKeepalive: false },
});

전송 방식 선택

옵션을 설정할 문자열 또는 객체를 전달합니다:

ts
amplitude.init("YOUR_API_KEY", {
  transport: {
    type: "fetch",
    headers: { "X-Request-Source": "web" },
    referrerPolicy: "strict-origin-when-cross-origin",
  },
});
  • headers 는 각 업로드에 HTTP 헤더를 추가합니다(fetch 및 xhr). SDK는 항상 Content-Type및 Accept를 설정하며, 헤더로 대체할 수 없습니다. 사용자 지정 헤더는 요청을 단순하지 않게 만들므로 서버가 CORS 프리플라이트에 응답해야 합니다. Amplitude의 엔드포인트가 수행합니다. 프록시를 확인하십시오. 브라우저 SDK 2.33.0 이상이 필요합니다.
  • referrerPolicy 업로드에 대한 리퍼러 정책을 fetch설정합니다. 브라우저 SDK 2.44.0 이상이 필요합니다.
  • enableKeepalive는 fetchkeepalive를 켜거나 끕니다. 기본적으로 켜져 있으며, 2.43.0에서 변경된 기본값입니다.

init()이후 전송을 변경하려면 setTransport()를 호출하십시오.

요청 본문 압축

브라우저가 CompressionStream를 지원하는 경우, SDK는 2KB 이상의 요청 본문을 gzip으로 압축하고 Content-Encoding: gzip를 설정합니다. Amplitude의 엔드포인트에 대해 항상 켜져 있습니다. 사용자 지정 serverUrl의 경우 서버가 gzip 본문을 허용해야 하므로 enableRequestBodyCompression: true를 설정하지 않는 한 꺼집니다. Compression을 사용하려면 브라우저 SDK 2.36.0 이상이 필요하며, 2.42.0에서 Amplitude의 엔드포인트에 대해 기본값이 켜짐으로 변경되었습니다.

ts
amplitude.init("YOUR_API_KEY", {
  serverUrl: "https://collect.example.com/amplitude",
  enableRequestBodyCompression: true,
});

Chrome 및 Edge 80, Firefox 113, Safari 16.4 및 이후 버전은 CompressionStream를 지원합니다. 이전 브라우저는 압축되지 않은 본문을 전송합니다. 전송은 절대로 압축하지 않습니다beacon.

프록시를 통해 이벤트를 전송하세요

광고 차단기와 일부 기업 네트워크는 *.amplitude.com를 차단합니다. 자체 도메인의 프록시는 이를 방지합니다. 프록시serverUrl를 지정하고 각 요청 본문을 변경하지 않고 해당 지역의 Amplitude 엔드포인트로 전달하십시오.

ts
amplitude.init("YOUR_API_KEY", {
  serverUrl: "https://collect.example.com/amplitude",
  remoteConfig: {
    serverUrl: "https://collect.example.com/amplitude-config",
  },
});

serverUrl 이벤트 업로드의 경우 serverZone및 useBatch를 재정의합니다. remoteConfig.serverUrl는 원격 구성을 별도로 라우팅합니다.

프록시의 경우 다음을 수행해야 합니다.

  • 사이트에 대해 OPTIONSPreflight 요청에 응답하고 Access-Control-Allow-Origin를 반환하십시오. 이 항목이 없으면 브라우저가 요청을 차단하고 콘솔에 has been blocked by CORS policy가 표시됩니다.
  • 요청 본문과 Content-Encoding헤더를 변경하지 않고 전달하거나, 전달하기 전에 압축을 해제하십시오.
  • Amplitude가 위치를 파생하도록 하려면 클라이언트의 IP 주소를 (예: X-Forwarded-For)로 전달하십시오. 그렇지 않으면 Amplitude는 프록시의 IP를 기록합니다.
  • Amplitude의 상태 코드와 JSON 본문을 변경하지 않고 반환합니다. SDK는 이를 읽어 재시도 여부를 결정합니다.

설정 예제를 보려면 프록시 요청으로 이동하십시오.

오프라인 작업

SDK는 브라우저의 online 및 offline 이벤트를 수신합니다.navigator.onLine 가 false인 동안에는 이벤트를 대기열에 보관하고 업로드를 시도하지 않습니다. 브라우저가 다시 온라인으로 전환되면 flushIntervalMillis 이후에 대기열을 업로드합니다. 브라우저 SDK 2.4.0 이상이 필요합니다.

몇 밀리초 이상으로 유지하십시오. flushIntervalMillis``1와 같은 값의 경우, 업로드는 online이벤트가 발생하는 거의 즉시(종종 연결이 안정화되기 전에) 시작되며, Chrome은 이를 ERR_NETWORK_CHANGED로 실패 처리할 수 있습니다. SDK는 실패한 업로드를 재시도합니다.

예를 들어 잘못 보고되는 웹뷰에서 연결을 직접 제어하려면 onLine내장 검사를 해제하십시오.

ts
amplitude.init("YOUR_API_KEY", {
  offline: amplitude.Types.OfflineDisabled,
});

OfflineDisabled를 사용하면 SDK는 항상 업로드를 시도하며 재시도에 의존합니다.

전송되지 않은 이벤트를 다른 곳에 저장

storageProvider localStorage가 전송되지 않은 이벤트 대기열을 대체합니다. 이벤트를 영구 저장소에 저장하지 않도록 Storage인터페이스(isEnabled, get, getRaw, set, remove, reset)를 구현하는 모든 객체를 전달합니다.

ts
const memoryQueue = new Map<string, amplitude.Types.Event[]>();
amplitude.init("YOUR_API_KEY", {
  storageProvider: {
    isEnabled: async () => true,
    get: async (key) => memoryQueue.get(key),
    getRaw: async (key) => JSON.stringify(memoryQueue.get(key)),
    set: async (key, value) => void memoryQueue.set(key, value),
    remove: async (key) => void memoryQueue.delete(key),
    reset: async () => memoryQueue.clear(),
  },
});

메모리 전용 스토리지를 사용할 경우 페이지가 언로드될 때 대기 중인 이벤트는 손실됩니다. Identity 스토리지는 별도로 저장됩니다. SDK가 ID를 저장하는 곳 선택으로 이동합니다.

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

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.

이 페이지에서