브라우저 SDK 2

Amplitude의 브라우저 SDK 2를 사용하면 Amplitude로 이벤트를 전송할 수 있습니다.

SDK 설치

npm, yarn 또는 스크립트 로더를 사용하여 종속성을 설치하십시오.

<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>
<script>
window.amplitude.add(window.sessionReplay.plugin({sampleRate: 1}));
window.amplitude.init('AMPLITUDE_API_KEY', {"fetchRemoteConfig":true,"autocapture":{"attribution":true,"fileDownloads":true,"formInteractions":true,"pageViews":true,"sessions":true,"elementInteractions":true,"networkTracking":true,"webVitals":true,"frustrationInteractions":true}});
</script>

SDK 초기화

이 SDK는 이벤트를 계측하기 전에 초기화가 필요하며 Amplitude 프로젝트의 API 키가 필요합니다. 이 호출에서 선택 사항인 userID 및 config 객체를 전달할 수 있습니다.

// Option 1, initialize with Amplitude API key only
amplitude.init(AMPLITUDE_API_KEY);
// Option 2, initialize with options
amplitude.init(AMPLITUDE_API_KEY, options);
// Option 3, initialize with user ID if it's already known
amplitude.init(AMPLITUDE_API_KEY, "user@amplitude.com");
// Option 4, initialize with a user ID and options
amplitude.init(AMPLITUDE_API_KEY, "user@amplitude.com", options);

runOutsideAngular(function () {
  amplitude.init(...args);
});

SDK 구성

일괄 처리 동작 구성

고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. SDK는 track 메서드가 기록하는 모든 이벤트를 메모리 대기열에 추가합니다. flushQueueSize및 flushIntervalMillis 구성 매개변수를 사용하여 이 동작을 사용자 정의하십시오. 대량의 데이터를 한 번에 전송하려면 useBatch을 true로, setServerUrl을 배치 API https://api2.amplitude.com/batch로 설정하십시오. 표준 모드와 배치 모드 모두 동일한 이벤트 업로드 임계값과 플러시 시간 간격을 사용합니다.

EU 데이터 상주

Amplitude의 EU 기반 서버로 데이터를 전송하려면 클라이언트를 초기화할 때 서버 영역을 설정하십시오. 서버 영역을 설정한 후에는 SDK가 이 설정에 의해 결정된 지역으로 전송합니다.

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

디버깅

다음 logLevel 설정을 사용하여 SDK가 콘솔에 출력하는 로그 수준을 제어하십시오.

logLevel 매개변수를 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  logLevel: amplitude.Types.LogLevel.Warn,
});

// In GTM configuration
logLevel: 0;

기본 로거는 개발자 콘솔에 로그를 출력합니다. 사용자 정의 목적을 위해 Logger 인터페이스를 기반으로 자체 로거 구현을 제공할 수 있습니다. 예를 들어 프로덕션 환경에서 SDK로부터 전체 오류 메시지를 수집하는 작업입니다.

loggerProvider를 자체 구현으로 구성하여 로거를 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  loggerProvider: new MyLogger(),
});

디버그 모드

logLevel를 "디버그"로 설정하여 디버그 모드를 활성화하십시오. 예를 들면 다음과 같습니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  logLevel: amplitude.Types.LogLevel.Debug,
});

기본 로거를 사용하면 SDK는 사용자가 전체 SDK 공용 메서드를 호출할 때 다음과 같은 추가 함수 컨텍스트 정보를 개발자 콘솔에 출력합니다.

• type: 이 컨텍스트의 범주입니다. 예를 들어 "공용 메소드 호출".
• name: 호출된 함수의 이름입니다(예: "track").
• args: 호출된 함수의 인수입니다.
• stacktrace: 호출된 함수의 스택트레이스입니다.
• time: 함수 호출의 시작 및 종료 타임스탬프입니다.
• states: 함수 호출 전후의 유용한 내부 상태 스냅샷입니다.

성능

브라우저 SDK 2는 이벤트 일괄 처리, 비동기 처리 및 번들 크기 최적화를 통해 페이지 성능에 미치는 영향을 최소화합니다.

번들 크기

브라우저 SDK 2 번들 크기는 설치 방법과 사용하는 기능에 따라 달라집니다.

최신 번들 크기 정보는 npm 패키지 페이지 또는 BundlePhobia를 확인하세요.

런타임 성능

브라우저 SDK 2는 비동기식으로 실행되며 이벤트 트래킹 다음 기간동안 메인 스레드를 차단하지 않습니다. 성능 특성은 다음과 같습니다.

• 이벤트 트래킹: 이벤트 트래킹 작업은 차단되지 않으며 일반적으로 각 이벤트에 대해 1ms 이내에 완료됩니다.
• 네트워크 요청: SDK는 이벤트를 일괄 처리하여 비동기적으로 전송하므로 네트워크 오버헤드가 최소화됩니다. 기본 구성은 최대 30개의 이벤트를 일괄 처리하거나 1초마다 전송합니다 (둘 중 먼저 발생하는 경우).
• 메모리 사용량: SDK는 이벤트 일괄 처리를 위해 작은 인메모리 큐를 유지합니다. 메모리 사용량은 대기열에 있는 이벤트 수에 따라 증가합니다(기본값: 최대 30개의 이벤트).
• CPU 영향: 이벤트 처리 및 일괄 처리 작업은 CPU에 미치는 영향이 최소화되며, 일반적으로 정상 작동 다음 기간동안 CPU 시간의 1% 미만입니다.

최적화 팁

성능을 더욱 최적화하려면:

• flushQueueSize과 flushIntervalMillis를 조정하여 네트워크 효율성과 메모리 사용량 간의 균형을 맞추십시오.
• 네트워크 상태가 좋지 않을 때는 offline 모드를 사용하여 이벤트 업로드를 연기하십시오.
• 대량의 이벤트 트래킹을 위해 useBatch 모드를 활성화하여 HTTP 요청 수를 줄이십시오.

자동 캡처(defaultTracking 대체)

SDK 버전 2.10.0부터는 브라우저 SDK를 활성화하면 이벤트를 자동으로 캡처할 수 있으며 자동으로 캡처된 이벤트 수집을 제어하기 위한 구성을 추가합니다. 브라우저 SDK는 다음과 같은 이벤트 유형을 자동으로 캡처할 수 있습니다.

• 어트리뷰션
• 페이지 뷰 수
• 세션
• 양식 상호작용
• 파일 다운로드
• 요소 상호 작용
• 페이지 URL 보강
• 네트워크 추적
• 웹 바이탈

원격 구성

자동 캡처는 원격 구성을 지원합니다. 자세한 내용은 자동 캡처 설정을 참조하십시오.

자동 캡처 비활성화

자동 캡처를 비활성화하려면 다음 코드 샘플을 참조하십시오.

// Disable individual default tracked events
amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    attribution: false,
    pageViews: false,
    sessions: false,
    formInteractions: false,
    fileDownloads: false,
    elementInteractions: false,
    pageUrlEnrichment: false,
    webVitals: false,
  },
});
// Disable all default tracked events
amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: false,
});

마케팅 기여도 추적

Amplitude는 기본적으로 마케팅 기여도를 추적합니다. 브라우저 SDK 2는 UTM 매개변수, 리퍼러 정보 및 클릭 ID를 캡처합니다.

SDK가 캠페인 기여 데이터를 유지하는 방법을 선택할 수 있습니다.

• 사용자 속성 추적(기본값): 퍼스트 터치 및 멀티 터치 기여에 대한 Identify 이벤트를 통해 캠페인 매개변수를 사용자 속성으로 추적합니다.
• 이벤트 속성 추적: 캠페인 매개변수를 각 이벤트의 속성에 연결하여 이벤트 수준의 속성 세분화를 제공합니다. 영구 속성과 함께 사용하면 다양한 속성 모델을 선택할 수 있습니다.

마케팅 어트리뷰션 추적을 비활성화하려면 config.autocapture.attribution을 false로 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    attribution: false,
  },
});

마케팅 어트리뷰션 추적을 위한 고급 구성

이벤트 속성 추적

사용자 속성 대신(또는 사용자 속성에 추가하여) 모든 이벤트 속성에 캠페인 매개변수를 첨부하도록 SDK를 구성하십시오. 이를 통해 이벤트 수준의 속성 세분화를 얻을 수 있습니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    attribution: {
      trackingMethod: "eventProperty",
    },
  },
});

이벤트 속성 추적을 통해 SDK는 다음을 수행합니다.

• 페이지 로드 및 SPA 탐색에 대한 캠페인 매개 변수를 파싱합니다(pushState, replaceState, popstate와 같은 History API 변경).
• 추적되는 모든 이벤트의 event_properties에 캠페인 필드를 첨부합니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    attribution: {
      trackingMethod: ["userProperty", "eventProperty"],
    },
  },
});

대체 속성 이벤트

이벤트 속성 추적을 사용할 때는 사용자가 다른 이벤트를 트리거하지 않을 때에도 Amplitude가 캠페인 데이터를 캡처하도록 fallbackAttributionEvent을 활성화하십시오. 이렇게 하면 각 페이지 보기 및 SPA 탐색에 대한 [Amplitude] Attribution이벤트가 전송됩니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    attribution: {
      trackingMethod: "eventProperty",
      fallbackAttributionEvent: true,
    },
  },
});

내부 추천자 제외

트래픽을 내부 탐색(동일한 도메인 또는 하위 도메인)에 귀속시키지 않으려는 경우 excludeInternalReferrers사용합니다. SDK는 document.referrer 및 location.hostname이 동일한 도메인으로 확인될 때 리퍼러를 내부로 간주합니다.

• 항상 제외: 내부 리퍼러에 대한 캠페인 정보를 추적하지 않으려면 excludeInternalReferrers: true 또는 excludeInternalReferrers: { condition: 'always' }(으)로 설정하십시오.
• 캠페인이 비어 있는 경우에만 제외: UTM 매개변수나 클릭 ID가 없는 내부 리퍼러에 대한 캠페인 추적을 건너뛰려면 excludeInternalReferrers: { condition: 'ifEmptyCampaign' }(으)로 설정하십시오. 사용자가 UTM 또는 클릭 ID를 사용하여 내부 페이지에서 도착한 경우에도 Amplitude는 여전히 캠페인 데이터를 추적합니다(excludeReferrers가 추천자를 제외하지 않는 경우).

추천자 제외

기본값은 쿠키 저장소가 활성화된 최상위 도메인입니다. config.autocapture.attribution.excludeReferrers예를 들어, https://www.docs.developers.amplitude.com/에서 SDK를 초기화하면 SDK는 먼저 amplitude.com을 확인합니다. amplitude.com에서 쿠키 저장이 허용되지 않으면 SDK는 developers.amplitude.com 및 후속 하위 도메인을 확인합니다. 도메인에서 쿠키 저장이 허용되면 SDK는 excludeReferrers를 amplitude.com의 모든 하위 도메인(예: data.amplitude.com 및 analytics.amplitude.com)의 추적 리퍼러와 일치시키고 이를 제외하는 RegExp 객체 /amplitude\.com$/로 설정합니다.

기본 구성에서 참조자를 제외하는 것 외에도 사용자 지정 excludeReferrers을 설정하여 다른 도메인을 추가할 수 있습니다. Custom ${ placeholder excludeReferrers}은 기본값을 재정의합니다. 예를 들어 google.com에서 추천자를 제외하려면 excludeReferrers로 설정하십시오[/amplitude\.com$/, 'google.com'].

페이지 뷰 추적

Amplitude는 기본적으로 페이지 뷰 이벤트를 추적합니다. 기본 동작은 초기화 시 페이지 뷰 이벤트를 전송합니다. 이 이벤트의 이벤트 유형은 [Amplitude] Page Viewed입니다.

페이지 뷰 추적을 비활성화하려면 config.autocapture.pageViews을 false로 설정합니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    pageViews: false,
  },
});

페이지 뷰 추적을 위한 고급옵션 구성

고급옵션 구성을 사용하여 SDK가 페이지 뷰 이벤트를 전송할 시기를 제어하십시오.

예를 들어 URL 경로에 특정 하위 문자열이 포함되어 있을 때만 페이지 뷰를 추적하도록 Amplitude를 구성할 수 있습니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    pageViews: {
      trackOn: () => {
        return window.location.pathname.includes("home");
      },
    },
  },
});

Browser SDK는 페이지 뷰 이벤트에서 다음 정보를 추적합니다.

이 예제를 검토하여 페이지 뷰 추적과 함께 더 많은 속성을 추가하는 등 기본 페이지 뷰 이벤트를 개선하는 방법을 이해하십시오.

페이지 제목 마스킹

Amplitude를 사용하면 [Amplitude] Page Title 속성이 포함된 이벤트에서 페이지 제목을 마스킹할 수 있습니다. 이렇게 하면 민감한 페이지 제목 정보가 보호됩니다. <title>요소의 data-amp-mask속성을 사용하여 이 속성에서 실제 페이지 제목을 제외하십시오.

<title>``data-amp-mask요소에 속성이 있으면 Amplitude는 페이지 제목 정보를 캡처하는 모든 이벤트에서 페이지 제목을 마스킹된 값으로 바꿉니다. 예를 들면 다음과 같습니다.

<head>
  <!-- This page title will be masked in all events that capture page titles -->
  <title data-amp-mask>John Doe - Personal Banking Dashboard</title>
</head>

<head>
  <!-- Works with any attribute value -->
  <title data-amp-mask="true">Sensitive Customer Information</title>
</head>

세션 추적

Amplitude는 기본적으로 세션 이벤트를 추적합니다. 세션은 사용자가 귀하의 웹사이트를 열어 놓은 상태의 기간입니다. 자세한 내용은 Amplitude가 세션을 정의하는 방법을 참조하십시오. 새 세션이 시작될 때, Amplitude는 세션의 첫 번째 이벤트인 세션 시작 이벤트를 추적합니다. 세션 시작에 대한 이벤트 유형은 [Amplitude] Start Session입니다. 기존 세션이 종료될 때, Amplitude는 세션의 마지막 이벤트인 세션 종료 이벤트를 추적합니다. 세션 종료에 대한 이벤트 유형은 [Amplitude] End Session입니다.

config.autocapture.sessions로 설정하여 세션 이벤트 추적을 거부할 수 있습니다false. 다음 코드 샘플을 참조하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    sessions: false,
  },
});

양식 상호 작용 추적

Amplitude는 기본적으로 양식 상호작용 이벤트를 추적합니다. SDK는 사용자가 처음에 form 요소와 상호 작용할 때를 [Amplitude] Form Started추적합니다. 초기 상호 작용은 텍스트 입력, 라디오 버튼 또는 드롭다운에 대한 첫 번째 변경일 수 있습니다. SDK는 사용자가 양식을 제출할 때 [Amplitude] Form Submitted를 추적합니다. 사용자가 양식 필드에 대해 초기 변경 사항이 없는 상태에서 양식을 제출하면 Amplitude는 [Amplitude] Form Started및 [Amplitude] Form Submitted 이벤트를 모두 추적합니다.

Amplitude는 태그와 중첩된 태그로 구성된 <form>양식을 추적할 수 있습니다.<input> 예를 들면 다음과 같습니다.

<form id="subscriber-form" name="subscriber-form" action="/subscribe">
  <input type="text" />
  <input type="submit" />
</form>

양식 상호 작용 추적 비활성화

양식 상호 작용 추적을 비활성화하려면 false로config.autocapture.formInteractions 설정합니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    formInteractions: false,
  },
});

양식 제출 추적 제어

shouldTrackSubmit 콜백과 FormInteractionsOptions 객체를 전달하여 Amplitude가 [Amplitude] Form Submitted 이벤트를 추적하는 시점을 제어할 수 있습니다.

기본적으로 Amplitude는 모든 양식 제출 이벤트를 추적합니다. 그러나 양식에 novalidate 속성이 설정된 경우, 브라우저 제출 이벤트가 기본 유효성 검사 작업을 수행하지 않고 발생합니다. 즉, 양식이 비어 있거나 잘못된 데이터가 포함되어 있더라도 제출 이벤트가 트리거됩니다. 이러한 경우, shouldTrackSubmit을 사용하여 사용자 지정 유효성 검사 로직을 구현하고 Amplitude가 제출 이벤트를 추적하는 시점을 제어할 수 있습니다.

shouldTrackSubmit 콜백은 양식 제출 이벤트를 수신하고, 제출 이벤트를 추적하려면 true를, 추적을 건너뛰려면 false를 반환합니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    formInteractions: {
      shouldTrackSubmit: (event) => {
        // Only track submit if form is valid
        const form = event.target;
        return form.checkValidity();
      },
    },
  },
});

파일 다운로드 추적

Amplitude는 기본적으로 파일 다운로드 이벤트를 추적합니다. 사용자가 파일에 링크된 앵커 또는 <a> 태그를 클릭할 때 SDK는 [Amplitude] File Downloaded를 추적합니다. 파일 확장자가 다음 정규 표현식과 일치하는 경우 Amplitude는 앵커 또는 <a> 태그가 파일에 링크된 것으로 판단합니다.

pdf|xlsx?|docx?|txt|rtf|csv|exe|key|pp(s|t|tx)|7z|pkg|rar|gz|zip|avi|mov|mp4|mpe?g|wmv|midi?|mp3|wav|wma

파일 다운로드 추적을 비활성화하려면 config.autocapture.fileDownloads을 false로 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    fileDownloads: false,
  },
});

요소 상호 작용 추적

요소 상호작용 추적을 활성화하여 페이지의 요소에 대한 클릭 및 변경 사항을 캡처할 수 있습니다. 이는 시각적 라벨링에 필요하며 정의된 페이지 영역 내의 참여도를 분석하기 위해 Zoning Insights를 지원합니다. 이러한 이벤트로 수집된 데이터에 대한 자세한 내용은 자동 캡처 개인 정보 보호 및 보안을 참조하십시오.

config.autocapture.elementInteractions을 true로 설정하여 요소 클릭 및 변경 추적을 활성화하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    elementInteractions: true,
  },
});

요소 상호 작용을 위한 고급옵션 구성

고급옵션을 사용하여 요소 상호 작용 추적을 제어하십시오.

예를 들어, 다음과 같이 사이트의 블로그 페이지에서 클래스가 amp-tracking인 요소에 대한 클릭만 캡처하도록 Amplitude를 구성할 수 있습니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    elementInteractions: {
      cssSelectorAllowlist: [".amp-tracking"],
      // When you use `cssSelectorAllowlist` to target specific elements, set `actionClickAllowlist`
      // to ensure that Amplitude tracks interactions with non-standard clickable elements during page transitions or DOM updates.
      actionClickAllowlist: [],
      pageUrlAllowlist: [new RegExp("https://amplitude.com/blog/*")],
    },
  },
});

기본적으로 이러한 설정을 사용하지 않을 경우 Amplitude는 플러그인을 활성화한 모든 페이지에서 기본 선택기를 추적합니다.

import { DEFAULT_CSS_SELECTOR_ALLOWLIST } from "@amplitude/plugin-autocapture-browser";
const selectors = [
  ...DEFAULT_CSS_SELECTOR_ALLOWLIST,
  ".class-of-a-thing-i-want-to-track",
];

불만 유발 상호작용 추적

불만 유발 상호작용 추적을 활성화하여 레이지 클릭과 데드 클릭, 오류 클릭, 스래시 커서를 캡처하십시오. Amplitude는 이러한 이벤트를 다음과 같이 정의합니다.

• 레이지 클릭: 사용자가 1초 이내에 50픽셀 이내의 동일한 요소를 4회 클릭하는 경우입니다.
• 데드 클릭: 사용자가 상호작용이 가능한 요소를 클릭하지만 탐색이 변경되지 않으며 DOM도 변경되지 않습니다.
• 에러 클릭: 사용자가 요소를 클릭하고 클릭 후 2초 첫 사용 후 브라우저 오류가 발생합니다.
• 스래시 커서: 사용자의 커서가 짧은 시간 첫 사용 후 빠르게 앞뒤로 움직이므로 잠재적 불만을 나타냅니다.

config.autocapture.frustrationInteractions을 true로 설정하여 데드 클릭과 레이지 클릭 캡처를 활성화하십시오.

config.autocapture.frustrationInteractions.rageClicks을 true로 설정하여 레이지 클릭 캡처를 활성화하십시오.

config.autocapture.frustrationInteractions.deadClicks을 true로 설정하여 데드 클릭 캡처를 활성화하십시오.

config.autocapture.frustrationInteractions.errorClicks을 true로 설정하여 오류 클릭 캡처를 활성화하십시오.

config.autocapture.frustrationInteractions.thrashedCursor을 true로 설정하여 스래시 커서 캡처를 활성화하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    frustrationInteractions: true,
  },
});

좌절 상호 작용을 위한 고급옵션 구성

고급옵션 구성을 사용하여 좌절 상호 작용 추적을 제어하십시오.

오류 클릭 추적

오류 클릭 추적은 사용자가 요소를 클릭할 때 캡처되며 클릭 후 2초 첫 사용 후 브라우저 오류가 발생합니다. 이를 통해 애플리케이션에서 오류를 유발할 수 있는 사용자 상호 작용을 식별할 수 있습니다.

오류 클릭 추적 활성화:

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    frustrationInteractions: {
      errorClicks: true,
    },
  },
});

오류 클릭 추적을 활성화하면 다음 속성을 포함하는 이벤트가 발생[Amplitude] Error Click합니다.

• [Amplitude] Kind: 오류의 유형(발견되지 않은 예외, 콘솔 오류, 처리되지 않은 프로미스 거부 중 하나)입니다.
• [Amplitude] Message: 오류 메시지입니다.
• [Amplitude] Stack: 오류 스택 추적입니다.
• [Amplitude] Filename: 오류가 발생한 파일 이름입니다.
• [Amplitude] Line Number: 오류가 발생한 행 번호입니다.
• [Amplitude] Column Number: 오류가 발생한 열 번호입니다.
• 클릭된 요소의 요소 속성(예: [Amplitude] Element Text, [Amplitude] Element Tag Name).

스래시된 커서를 추적합니다.

스래시 커서 추적은 사용자의 커서가 짧은 시간 첫 사용 후 여러 방향으로 변경되어 앞뒤로 빠르게 움직일 때 캡처합니다. 이를 통해 사용자가 좌절감이나 혼란을 겪고 있는 영역을 식별할 수 있습니다.

스래시 커서 추적 활성화:

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    frustrationInteractions: {
      thrashedCursor: true,
    },
  },
});

[Amplitude] Thrashed Cursor라는 이벤트를 발생시킵니다.

네트워크 요청 추적

네트워크 요청이 실패할 경우 추적합니다(XHR 및 fetch만 해당). 기본적으로 500-599 범위의 응답 코드를 가진 네트워크 요청을 추적하며, amplitude.com 도메인에 대한 요청은 제외됩니다.

네트워크 요청 추적을 활성화하려면 config.autocapture.networkTracking을 true로 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    networkTracking: true,
  },
});

이 설정을 활성화하면 애플리케이션이 네트워크 요청을 할 때마다 Amplitude는 [Amplitude] Network Request 이벤트를 추적합니다.

네트워크 추적을 위한 고급옵션 구성

config.autocapture.networkTracking을 NetworkTrackingOptions 객체로 설정하여 어떤 네트워크 요청을 추적할지 구성하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    networkTracking: {
      captureRules: [
        {
          statusCodeRange: "400-599",
        },
      ],
      ignoreHosts: ["*.example.com"],
      ignoreAmplitudeRequests: true,
    },
  },
});

이 예제에서는 상태 코드가 400~599인 네트워크 요청을 추적하고, *.example.com 도메인에 대한 요청은 무시하며, Amplitude의 자체 요청은 제외합니다. 자세한 내용은 아래의 구성 옵션을 참조하십시오.

안전한 헤더

requestHeaders: true 또는 responseHeaders: true을 설정하면 Amplitude는 안전한 헤더만 캡처하고 인증 자격 증명 또는 개인 식별 정보가 포함될 수 있는 민감한 헤더는 제외합니다.

네트워크 본문 캡처

네트워크 요청 또는 응답 본문이 JSON 형식인 경우 responseBody.allowlist 및 responseBody.blocklist를 구성하여 응답 본문의 일부를 캡처할 수 있습니다. requestBody.allowlist및 requestBody.blocklist를 구성하여 요청 본문의 일부를 캡처할 수 있습니다.

허용목록과 차단목록은 특정 필드를 캡처하는 JSON 포인터와 같은 문자열 목록입니다. (예: ['foo/bar', 'hello/**']). allowlist은 클라이언트에게 캡처할 필드를 알려줍니다. excludelist은 클라이언트에게 캡처에서 필드를 제외하도록 알려줍니다(기본적으로 SDK는 아무 것도 캡처하지 않습니다).

요청/응답 본문 예제

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

웹 바이탈 추적

핵심 웹 바이탈 성능 지표를 자동으로 추적합니다. 이 기능을 활성화하면 Amplitude는 웹 성능 지표를 캡처하여 브라우저 탭이 처음 숨겨질 때(사용자가 다른 페이지로 이동하거나 탭을 닫거나 탭을 전환할 때) 이를 [Amplitude] Web Vitals 이벤트로 전송합니다.

웹 바이탈 추적을 활성화하려면 config.autocapture.webVitals을 true로 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    webVitals: true,
  },
});

측정 항목 수집

웹 바이탈 자동 캡처 기능은 다음과 같은 Core Web Vitals 지표를 캡처합니다.

• INP
• TTFB
• LCP
• FCP
• CLS

이벤트 속성

[Amplitude] Web Vitals 이벤트에는 다음 속성이 포함됩니다.

이벤트 추적

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어, 버튼 클릭 이벤트는 추적하고자 하는 동작일 수 있습니다.

// Track a basic event.
amplitude.track("Button Clicked");
// Track events with optional properties.
const eventProperties = {
  buttonColor: "primary",
};
amplitude.track("Button Clicked", eventProperties);

BaseEvent 객체를 track에 전달할 수도 있습니다. 자세한 내용은 사용 가능한 모든 필드에 대해 BaseEvent 인터페이스를 검토하십시오.

const event_properties = {
  buttonColor: "primary",
};
const event = {
  event_type: "Button Clicked",
  event_properties,
  groups: { role: "engineering" },
  group_properties: { groupPropertyKey: "groupPropertyValue" },
};
amplitude.track(event);

여러 프로젝트에 대한 이벤트 추적

기본적으로 Amplitude SDK는 데이터를 하나의 Amplitude 프로젝트로 전송합니다. 데이터를 둘 이상의 프로젝트에 전송하려면 데이터를 수신하려는 각 프로젝트에 대해 Amplitude SDK의 인스턴스를 추가하십시오. 그런 다음 Amplitude를 호출하려는 모든 위치에 인스턴스 변수를 전달하십시오. 각 인스턴스는 독립적인 apiKey, userId, deviceId 및 settings 값을 허용합니다.

const defaultInstance = amplitude.createInstance();
defaultInstance.init(API_KEY_DEFAULT);
const envInstance = amplitude.createInstance();
envInstance.init(API_KEY_ENV, {
  instanceName: "env",
});

사용자 속성

사용자 속성은 기기 세부 정보, 사용자 환경설정, 언어와 같은 세부 정보로, 사용자가 앱에서 작업을 수행했을 때 이를 이해하는 데 도움을 줍니다.

Identify 는 전체 이벤트를 전송하지 않고 특정 사용자의 사용자 속성을 설정합니다. SDK는 개별 사용자 속성에 대한 set, setOnce, unset, add, append, prepend, preInsert, postInsert, remove 및 clearAll 작업을 지원합니다. 제공된 Identify 인터페이스를 통해 작업을 선언합니다. 단일 Identify 객체에서 여러 작업을 함께 연결할 수 있습니다. 그런 다음 Identify 객체를 Amplitude 클라이언트에 전달하여 서버로 전송합니다.

사용자 속성 설정

Identify 객체는 사용자 속성을 설정하기 위한 컨트롤을 제공합니다. 사용자 속성을 설정하려면 다음과 같이 하십시오.

1. Identify 객체를 인스턴스화합니다.
2. 해당 객체에 대한 메소드를 호출합니다.
3. SDK가 Identify 객체를 사용하여 호출하도록 지시합니다.

const identifyEvent = new amplitude.Identify();
// Use methods in the following sections to update the Identify object
amplitude.identify(identifyEvent);

Identify.set

이 메서드는 사용자 속성의 값을 설정합니다. 예를 들어 사용자의 역할 속성을 설정할 수 있습니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.set("location", "LA");
amplitude.identify(identifyEvent);

Identify.setOnce

이 메서드는 사용자 속성의 값을 한 번만 설정합니다. setOnce()를 사용하는 후속 호출은 무시됩니다. 예를 들어 사용자의 초기 로그인 방법을 설정할 수 있습니다. setOnce()는 이후의 호출을 무시합니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.setOnce("initial-location", "SF");
identify(identifyEvent);

Identify.add

이 메서드는 사용자 속성을 숫자 값으로 증가시킵니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 값을 증가시키기 전에 해당 값을 0로 초기화합니다. 예를 들어 사용자의 여행 수행 회수를 추적할 수 있습니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.add("travel-count", 1);
amplitude.identify(identifyEvent);

Identify.unset

이 메서드는 사용자 프로필에서 사용자 속성을 제거합니다. 특성이 더 이상 필요하지 않거나 완전히 제거하려는 경우 unset을 사용하십시오.

const identifyEvent = new amplitude.Identify();
identifyEvent.unset("location");
amplitude.identify(identifyEvent);

사용자 속성의 배열

배열을 사용자 속성으로 사용하려면 prepend, append, preInsert 또는 postInsert 메서드를 호출하십시오.

Identify.prepend

이 메서드는 사용자 속성 배열 앞에 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 앞에 추가하기 전에 IT를 빈 목록으로 초기화합니다.

const identifyEvent = new Identify();
identifyEvent.prepend("visited-locations", "LAX");
identify(identifyEvent);

Identify.append

이 메서드는 사용자 속성 배열에 하나 이상의 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 추가하기 전에 해당 속성을 빈 목록으로 초기화합니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.append("visited-locations", "SFO");
amplitude.identify(identifyEvent);

Identify.postInsert

이 메서드는 사용자 속성에 값이 아직 존재하지 않는 경우 해당 값을 사용자 속성에 사후 삽입합니다. 사후 삽입은 주어진 목록의 끝에 값을 삽입하는 것을 의미합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우, SDK는 새 값을 사후 추가하기 전에 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있는 경우 이 메서드는 no-op입니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.postInsert("unique-locations", "SFO");
amplitude.identify(identifyEvent);

Identify.remove

이 메서드는 사용자 속성에 값이 존재하는 경우 해당 사용자 속성에서 값 또는 값들을 제거합니다. 제거는 주어진 목록에서 기존 값을 제거한다는 의미입니다. 사용자 속성에 기존 값이 있는 경우 이 메서드는 no-op입니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.remove("unique-locations", "JFK");
amplitude.identify(identifyEvent);

Identify.clearAll

이 메서드는 사용자로부터 모든 사용자 속성을 제거합니다. clearAll은 되돌릴 수 없으므로 주의해서 사용하십시오.

const identifyEvent = new amplitude.Identify();
identifyEvent.clearAll();
amplitude.identify(identifyEvent);

사용자 그룹

Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 수행하는 것을 지원합니다. 그룹 구성원 중 적어도 한 명이 특정 이벤트를 수행한 경우 해당 그룹도 수행 회수가에 포함됩니다.

예를 들어 'orgId'를 사용하여 사용자가 속한 조직을 기준으로 사용자를 그룹화하려는 경우가 있습니다. Joe는 'orgId' '10'에 있고 Sue는 'orgId' '15'에 있습니다. Sue와 Joe는 둘 다 특정 이벤트를 수행합니다. 이벤트 세분화 차트에서 해당 조직을 쿼리할 수 있습니다.

그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예시에서 'orgId'는 groupType이고 '10'과 '15'는 groupName에 대한 값입니다. groupType의 또 다른 예로는 'tennis' 및 'baseball'과 같은 groupName 값을 가진 'sport'가 있을 수 있습니다.

그룹을 설정하면 groupType:groupName도 사용자 속성으로 설정되며, 해당 사용자의 groupType에 대해 설정된 모든 기존 groupName 값과 해당 사용자 속성 값이 덮어쓰여집니다. groupType은 문자열이고, groupName는 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 배열일 수 있습니다.

// set group with a single group name
amplitude.setGroup("orgId", "15");

// set group with multiple group names
amplitude.setGroup("sport", ["soccer", "tennis"]);

이벤트 수준 그룹을 설정하려면 groups와 함께 Event 객체를 Track 호출에 전달하십시오. 이벤트 수준 그룹의 경우 그룹 지정은 기록된 특정 이벤트에만 적용되며 setGroup를 사용하여 명시적으로 설정하지 않는 한 사용자에게 지속되지 않습니다.

amplitude.track({
  event_type: "event type",
  event_properties: { eventPropertyKey: "event property value" },
  groups: { orgId: "15" },
});

그룹 속성

Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 이러한 업데이트는 이 시점 이후의 이벤트에만 영향을 줍니다.

이 groupIdentify() 메서드는 그룹 유형 및 그룹 이름 문자열 매개변수와 SDK가 그룹에 적용하는 Identify 객체를 허용합니다.

const groupType = "plan";
const groupName = "enterprise";
const groupIdentifyEvent = new amplitude.Identify();
groupIdentifyEvent.set("key1", "value1");
amplitude.groupIdentify(groupType, groupName, groupIdentifyEvent);

매출 추적

사용자의 수익을 추적하는 선호되는 방법은 제공된 Revenue 인터페이스와 함께 revenue()을 사용하는 것입니다. Revenue 인스턴스는 각 수익 거래를 저장하며, Amplitude의 이벤트 세분화 및 LTV(Lifetime Value) 차트에서 사용하는 여러 특수 수익 속성(예: revenueType 및 productId)을 정의할 수 있도록 합니다. 이러한 Revenue 인스턴스 객체를 revenue()에 전달하여 Amplitude에 수익 이벤트로 전송하십시오. 이를 통해 Amplitude는 플랫폼의 수익과 관련된 데이터를 자동으로 표시할 수 있습니다. 이 기능을 사용하여 앱 내 구매와 앱 내 이외의 구매를 모두 추적할 수 있습니다.

사용자의 수익을 추적하려면 사용자가 수익을 창출할 때마다 수익을 호출하십시오. 이 예시에서 사용자는 3.99달러짜리 제품 3개를 구입했습니다.

const event = new amplitude.Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3)
  .setRevenueType("purchase");
amplitude.revenue(event);

이 예에서는 통화 유형을 사용하여 수익을 추적하는 방법을 보여 줍니다.

const event = new amplitude.Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3)
  .setRevenueType("purchase")
  .setCurrency("JPY");
amplitude.revenue(event);

이 예에서는 추가 속성을 사용하여 수익을 추적하는 방법을 보여 줍니다.

const event = new amplitude.Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3)
  .setRevenueType("purchase")
  .setEventProperties({
    category: "electronics",
    brand: "Acme",
  });
amplitude.revenue(event);

수익 인터페이스

수익 객체는 다음과 같은 속성을 지원합니다. 해당 세터 메소드를 사용하여 값을 할당하십시오.

이벤트 버퍼 플러시

이 flush 메서드는 클라이언트가 버퍼링된 이벤트를 즉시 전송하도록 트리거합니다.

amplitude.flush();

기본적으로 Browser SDK는 일정 간격마다 flush을 자동으로 호출합니다. 모든 이벤트를 플러시하려면 선택적 Promise 인터페이스를 사용하여 비동기 흐름을 제어하십시오. 예를 들어:

amplitude.init(API\_KEY).promise.then(function() {
  amplitude.track('Button Clicked');
  amplitude.flush();
});

사용자 정의 사용자 식별자

애플리케이션에 사용자를 추적하는 로그인 시스템이 있는 경우 setUserId를 호출하여 사용자의 식별자를 업데이트하십시오.

amplitude.setUserId("user@amplitude.com");

사용자 정의 세션 식별자

setSessionId를 사용하여 새 세션 ID를 할당합니다. 사용자 지정 세션 ID를 설정할 때는 값이 에포크 이후 밀리초 단위인지 확인하십시오(Unix 타임스탬프).

amplitude.setSessionId(Date.now());

사용자 지정 장치 식별자

deviceId를 사용하여 새 장치 ID를 할당합니다. 사용자 지정 장치 ID를 설정할 때는 값이 충분히 고유한지 확인하십시오. Amplitude는 UUID 사용을 권장합니다.

amplitude.setDeviceId(uuid());

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

reset을 바로 가기로 사용하여 로그아웃한 후 사용자를 익명화하십시오. reset은 다음을 수행합니다.

1. userId을 undefined로 설정합니다.
2. 새 UUID 값으로 deviceId설정합니다.

userId이 정의되지 않고 deviceId가 새 값인 경우, 해당 사용자는 Amplitude에 새 사용자로 표시됩니다.

amplitude.reset();

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

특정 사용자에 대한 로깅을 비활성화하려면 setOptOut을 true로 설정하십시오.

amplitude.setOptOut(true);

setOptOut가 활성화되어 있는 동안 Amplitude는 이벤트를 저장하거나 서버로 전송하지 않습니다. 이 설정은 페이지가 로드될 때에도 유지됩니다.

로깅을 다시 활성화하려면 setOptOut을 false로 설정하십시오.

amplitude.setOptOut(false);

추적 옵션

기본적으로 SDK는 이러한 속성을 자동으로 추적합니다. SDK를 초기화할 때 trackingOptions라는 구성을 전달하고 해당 옵션을 false로 설정하여 이 동작을 재정의할 수 있습니다.

amplitude.init(AMPLITUDE_API_KEY, {
  trackingOptions: {
    ipAddress: false,
    language: false,
    platform: false,
  },
});

콜백

모든 비동기 API는 선택적으로 Promise 인터페이스를 통해 대기할 수 있습니다. 이 인터페이스는 콜백 인터페이스로도 사용됩니다.

amplitude.init("apikey", "12321.com").promise.then(function () {
  // init callback
});
amplitude.track("Button Clicked").promise.then(function (result) {
  result.event; // {...} (The final event object sent to Amplitude)
  result.code; // 200 (The HTTP response status code of the request.
  result.message; // "Event tracked successfully" (The response message)
});

플러그인

플러그인을 사용하면 이벤트 속성을 수정하거나(풍부화 플러그인), 타사 엔드포인트로 전송하는 등의 방법으로 Amplitude SDK의 동작을 확장할 수 있습니다(목적지 플러그인). 플러그인은 선택적 필드 name 및 type과 메서드 setup(), execute(), teardown()을 가진 Object입니다.

추가

add 메서드는 Amplitude에 플러그인을 추가합니다.

amplitude.add(new Plugin());

제거

remove 메서드는 클라이언트 인스턴스에 지정된 플러그인 이름이 있는 경우 해당 이름을 제거합니다.

amplitude.remove(plugin.name);

사용자 지정 플러그인 만들기

플러그인 예제

const enrichPageUrlPlugin = (): EnrichmentPlugin => {
  return {
    execute: async (event: Event) => {
      event.event_properties = {
        ...event.event_properties,
        page_url: location.href,
      };
      return event;
    },
  };
};
amplitude.add(enrichPageUrlPlugin());
amplitude.init(API_KEY);

사용 가능한 플러그인

Amplitude는 브라우저 SDK 기능을 확장하기 위한 몇 가지 공식 플러그인을 제공합니다.

페이지 URL 강화 플러그인

자동 캡처는 기본적으로 페이지 URL 보강 플러그인을 활성화합니다. 이 플러그인은 현재 페이지 정보, 이전 페이지 위치, 페이지 유형 분류 등 페이지 URL 관련 속성을 모든 이벤트에 자동으로 추가합니다.

페이지 URL 보강을 비활성화하려면 autocapture.pageUrlEnrichment을 false로 설정하십시오.

amplitude.init(API_KEY, {
  autocapture: {
    pageUrlEnrichment: false,
  },
});

사용자 지정 구성을 위해 또는 자동 캡처를 완전히 비활성화한 경우에도 플러그인을 수동으로 추가할 수 있습니다.

import { pageUrlEnrichmentPlugin } from "@amplitude/plugin-page-url-enrichment-browser";
const pageUrlEnrichment = pageUrlEnrichmentPlugin();
amplitude.add(pageUrlEnrichment);
amplitude.init(API_KEY);

문제 해결 및 디버깅

브라우저에서 디버깅하면 코드 구현과 관련된 문제뿐만 아니라 사용 중인 SDK 첫 사용 후 잠재적 문제를 식별하는 데 도움이 됩니다. 다음은 디버깅을 위해 브라우저에 내장된 개발자 도구(DevTools)를 사용하는 방법에 대한 기본 가이드입니다.

콘솔

_검사 > 콘솔_에서 JavaScript 오류를 찾을 수 있습니다. 이 오류에는 문제를 일으킨 코드 줄과 파일에 대한 세부 정보가 포함되어 있을 수 있습니다. 또한 콘솔을 사용하면 JavaScript 코드를 실시간으로 실행할 수 있습니다.

• 다음 지침에 따라 디버그 모드를 활성화하십시오. 그런 다음 기본 로거를 사용하면 SDK가 전체 SDK 공용 메서드를 호출할 때 추가 함수 컨텍스트 정보를 개발자 콘솔에 출력하므로 디버깅에 도움이 될 수 있습니다.
• Amplitude는 SDK 지연 초기화를 지원합니다. SDK는 초기화 호출 후 초기화 전에 추적된 이벤트를 디스패치합니다. 이벤트를 전송할 수 없으나 브라우저 콘솔에서 amplitude.init(API_KEY, 'USER_ID')을 입력한 후 성공적으로 이벤트를 전송할 수 있다면, 코드베이스에서 amplitude.init 호출이 트리거되지 않았거나, 초기화 중에 올바른 Amplitude 인스턴스를 사용하고 있지 않을 수 있습니다. 따라서 구현을 확인하십시오.

네트워크 요청

검사 > 네트워크 탭을 사용하여 페이지에서 수행한 모든 네트워크 요청을 확인할 수 있습니다. Amplitude 요청을 검색합니다.

응답 코드를 확인하고 응답 페이로드가 예상대로인지 확인하십시오.

계측 익스플로러 Chrome 확장 프로그램

Amplitude Instrumentation 익스플로러는 Google Chrome 웹 스토어에서 사용할 수 있는 확장 프로그램입니다. 이 확장 기능은 사용자가 트리거하는 각 Amplitude 이벤트를 캡처하여 확장 기능 팝업에 표시합니다. SDK가 이벤트를 성공적으로 전송했는지 확인하고 이벤트 페이로드의 컨텍스트를 확인하십시오.

일반적인 문제

다음은 브라우저 SDK와 관련된 일반적인 문제입니다. 보다 일반적인 문제에 대해서는 SDK 문제 해결 및 디버깅을 참조하십시오.

광고 차단 프로그램

Ad Blocker 이벤트가 삭제될 수 있습니다. 다음 오류는 추적에 영향을 Ad Blocker미쳤음을 나타냅니다. 스크립트 태그를 통해 로드할 때 SDK 스크립트를 로드하는 동안 콘솔이나 네트워크 탭에 오류가 나타날 수 있습니다. npm 패키지와 함께 로드될 때 서버에 이벤트를 전송하려고 할 때 네트워크 탭에 오류가 발생할 수 있습니다. 오류는 브라우저에 따라 다를 수 있습니다.

• 크롬(우분투, 맥OS) 콘솔: error net::ERR_BLOCKED_BY_CLIENT 네트워크: 상태(차단됨:기타)
• Firefox (Ubuntu) 콘솔: 오류 텍스트에 차단 관련 정보가 전체적으로 포함되어 있지 않습니다 네트워크: 전송된 열에는 uBlock Origin에 의해 차단된 플러그인 이름이 포함됩니다
• 사파리 (맥 OS) 콘솔: 오류에 텍스트가 포함되어 있습니다. 콘텐츠 차단기로 인해 프레임 ... 이 ...에서 리소스를 로드할 수 없습니다. 네트워크: IT 차단된 요청이 나열되지 않은 것 같습니다. 이들을 보여줄 수 있을지 확신할 수 없습니다.

Amplitude는 이러한 상황을 피하기 위해 프록시 서버를 사용할 것을 권장합니다.

쿠키 관련

다음은 SDK가 쿠키에 저장하는 정보입니다. 이는 쿠키를 비활성화하거나 개인 브라우저, 창 또는 탭을 사용하는 것과 같은 클라이언트의 행동이 쿠키에 불러오기 이러한 값의 지속성에 영향을 미친다는 것을 의미합니다. 이러한 값이 지속되지 않거나 1씩 증가하지 않는 경우 이것이 원인일 수 있습니다.

CORS

Cross-Origin Resource Sharing (CORS)는 웹 페이지가 다른 도메인으로부터 리소스를 요청할 수 있는 방법을 제한하기 위해 브라우저가 구현하는 보안 조치입니다. setServerURL을 사용한 경우 이 문제가 발생할 수 있습니다.

Access to fetch at 'xxx' from origin 'xxx' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

Cross-origin resource sharing (CORS)는 악의적인 사이트가 다른 사이트의 데이터를 권한 없이 읽는 것을 방지합니다. 이 오류 메시지는 액세스하려는 서버가 사용자의 출처에서 요청된 리소스에 액세스하는 것을 허용하지 않고 있음을 나타냅니다. 이는 서버의 응답에 Access-Control-Allow-Origin헤더가 없기 때문입니다.

• 서버에 대한 제어 권한이 있는 경우 서버의 CORS 정책을 업데이트할 수 있습니다. 서버의 응답에 Access-Control-Allow-Origin 헤더를 추가하십시오. 이렇게 하면 사용자의 출처에서 요청을 보낼 수 있습니다. Access-Control-Allow-Origin의 값은 모든 오리진을 허용하도록 설정할 수도 있고 웹 페이지의 특정 URL일 수도 있습니다*.
• 서버에 대한 제어 권한이 없는 경우 필요한 CORS 헤더를 추가하는 프록시 서버를 설정할 수 있습니다. 웹 페이지는 프록시에 요청을 전송하며, 프록시는 실제 서버에 요청을 전송합니다. 프록시는 응답을 웹 페이지로 다시 전송하기 전에 응답에 Access-Control-Allow-Origin헤더를 추가합니다.

API 프록시를 설정했는데 선택한 플랫폼에서 그와 관련된 구성 문제가 발생했다면, 이는 더 이상 SDK 문제가 아니라 애플리케이션과 서비스 공급자 대상 구간 연동 문제입니다.

이벤트가 발생했지만 네트워크 요청이 없음

로거 수준을 "디버그"로 설정하고 개발자 콘솔에서 추적 호출이 표시되면 코드가 track() 메서드를 호출한 것입니다. Amplitude, Amplitude Instrumentation 익스플로러 Chrome 확장 프로그램 또는 브라우저의 네트워크 요청 탭에서 해당 이벤트를 볼 수 없다면 SDK가 해당 이벤트를 Amplitude로 전송하지 않은 것입니다. SDK는 호출이 성공할 때 이벤트를 발생시켜 내부 대기열에 넣지만, track()때로는 이러한 대기열에 저장된 이벤트가 성공적으로 전송되지 않을 수도 있습니다. 이는 브라우저가 진행 중인 HTTP 요청을 취소할 때 발생할 수 있습니다. 예를 들어 브라우저를 닫거나 페이지를 떠나는 경우입니다.

이 문제는 새 페이지를 즉시 로드하는 로그인 이벤트와 같이 리디렉션 또는 탐색 직전에 이벤트가 발생할 때 가장 자주 발생합니다. 이 문제를 해결하는 방법은 몇 가지가 있습니다.

1. 기본적으로 fetch 전송 방식은 keepalive를 사용하여 이벤트를 전송하므로 페이지가 언로드된 후에도 요청이 완료될 수 있습니다. 이 기능은 최대 16KB의 요청 본문에 대해 대부분의 탐색 사례를 자동으로 처리합니다. keepalive가 비활성화되어 있지 않은지, 이벤트 배치가 크기 제한 첫 사용 후 있는지 확인하십시오. 자세한 내용은 keepalive를 사용한 페이지 탐색 유지 섹션을 참조하십시오.
2. keepalive 제한보다 큰 페이로드의 경우, 초기화 시 또는 페이지 종료 시 전송 방식을 beacon로 설정하십시오. sendBeacon은 백그라운드에서 이벤트를 전송하지만 4xx 또는 5xx과 같은 서버 응답을 반환하지 않으므로 실패 시 재시도하지 않습니다. 자세한 내용은 sendBeacon 섹션을 참조하십시오.
3. track()을 동기식으로 만들려면 호출 앞에 await 키워드를 추가하십시오.

고급옵션 항목

도메인 간 추적

두 개의 다른 도메인에서 익명의 행동을 추적할 수 있습니다. Amplitude는 익명 사용자를 장치 ID로 식별하며, 이 ID는 도메인 간에 전달되어야 합니다. 동일한 세션을 유지하고 지속적인 사용자 여정을 보장하려면 세션 ID도 다른 도메인에 전달해야 합니다.

예를 들면 다음과 같습니다.

• 사이트 1: www.example.com
• 사이트 2: www.example.org

사이트 1에서 시작한 다음 사이트 2로 이동하는 사용자는 사이트 1에서 생성된 디바이스 ID를 매개변수로 사이트 2로 전달해야 합니다. 그런 다음 사이트 2는 디바이스 ID를 사용하여 SDK를 초기화해야 합니다. deviceId가 URL 쿼리 매개변수에 포함되어 있는 경우 SDK는 URL 매개변수를 자동으로 파싱할 수 있습니다.

v2.8.0부터 SDK는 URL에서 세션 ID를 자동으로 가져와 동일한 세션을 유지하고 지속적인 사용자 여정을 보장할 수 있습니다.

1. 사이트 1에서 getDeviceId()에서 장치 ID를, getSessionId()에서 세션 ID를 가져옵니다.
2. 사용자가 탐색할 때 장치 ID와 세션 ID를 URL 매개변수를 통해 사이트 2에 전달합니다(예: www.example.com?ampDeviceId=device_id_from_site_1&ampSessionId=1716245958483).
3. 사이트 2에서 init('API_KEY', null)를 사용하여 Amplitude SDK를 초기화합니다.

init('API_KEY', null, { deviceId: 'custom-device-id', sessionId: 1716245958483 })에서 deviceId과 sessionId을 설정하지 않으면 SDK는 이를 대체하여 자동으로 각각의 URL 매개변수를 사용합니다.

ampTimestamp가 포함된 평가 창

보안을 강화하고 유효하지 않은 세션 또는 장치 ID의 사용을 방지하려면 평가 창 역할을 하는 ampTimestamp 매개 변수를포함할 수 있습니다. SDK는 ampTimestamp 값이 미래(현재 시간보다 큰 값)인 경우에만 ampSessionId 및 ampDeviceId URL 매개변수를 사용합니다.

예를 들면 다음과 같습니다.

www.example.com?ampDeviceId=device_id&ampSessionId=session_id&ampTimestamp=1640995500000

ampTimestamp이 만료되면(현재 시간보다 작은 값), SDK는 ampSessionId 및 ampDeviceId 매개변수를 무시합니다. SDK는 새 값을 생성하거나 쿠키에서 저장된 값을 사용하는 것으로 되돌아갑니다. ampTimestamp를 제공하지 않으면 SDK는 이전 버전과의 호환성을 위해 이전과 동일하게 동작합니다.

이 기능을 사용하면 도메인 간 추적 매개변수가 제한된 시간 동안만 유효하게 유지됩니다. 이를 통해 추적 매개 변수가 내장된 수명이 긴 URL에서 발생할 수 있는 잠재적인 보안 문제를 방지할 수 있습니다.

Amplitude는 Date.now()을 사용하는 Browser SDK와 동일한 세션 ID 형식을 따를 것을 권장합니다. SDK는 이벤트를 추적할 때마다 이벤트가 세션에 있는지 확인하기 때문입니다. 예를 들면 다음과 같습니다.

// if session ID is set to 12345
// https://www.example.com?ampDeviceId=my-device-id&ampSessionId=12345
amplitude.init(API_KEY);
// session ID is set to 12345 after init()
amplitude.track("event");
// session ID is set back to Date.now()
// because the tracked "event" is not in the previous session 12345

사용자 지정 HTTP 요청 헤더

transport 구성 옵션을 사용하여 사용자 지정 HTTP 헤더를 이벤트 업로드 요청에 첨부하십시오. 전송 이름 문자열을 전달하는 대신 transport 및 headers 속성을 가진 객체를 전달하십시오. 이 기능은 특정 헤더가 필요한 프록시 서버를 통해 요청을 라우팅하는 등의 시나리오에 유용합니다.

amplitude.init(API_KEY, {
  transport: {
    type: "fetch",
    headers: {
      "X-Custom-Header": "custom-value",
      Authorization: "Bearer your-token",
    },
  },
});

xhr 전송을 사용자 지정 헤더와 함께 사용할 수도 있습니다.

amplitude.init(API_KEY, {
  transport: {
    type: "xhr",
    headers: {
      "X-Custom-Header": "custom-value",
    },
  },
});

요청 본문 압축

브라우저 SDK는 이벤트 업로드 요청 본문에 대해 gzip 압축을 지원하여 대역폭 사용량을 줄이고 업로드 성능을 향상시킵니다. 압축은 대량의 이벤트를 전송할 때 특히 유용합니다.

압축 작동 방식

SDK는 다음과 같은 경우 요청 본문을 자동으로 압축합니다.

• 페이로드 크기가 2KB 이상입니다.
• 브라우저는 CompressionStream API를 지원합니다(최신 브라우저에서 사용 가능).
• 전송 유형은 fetch 또는 xhr입니다(SDK는 beacon 전송 방식에서 압축을 지원하지 않습니다).

Amplitude의 기본 수집 엔드포인트(https://api2.amplitude.com)를 사용하는 경우 SDK는 자동으로 압축을 활성화합니다. 사용자 지정 serverUrl(예: 프록시 서버)을 사용하는 경우 enableRequestBodyCompression를 true로 설정하여 압축을 명시적으로 활성화해야 합니다.

사용자 지정 서버에 대한 압축 활성화

사용자 지정 프록시 서버를 통해 이벤트를 라우팅하는 경우 enableRequestBodyCompression를 true로 설정하여 압축을 활성화하십시오.

amplitude.init(API_KEY, {
  serverUrl: "https://your-proxy.example.com/events",
  enableRequestBodyCompression: true,
});

프록시 서버는 gzip으로 압축된 요청 본문을 지원해야 하며 Content-Encoding: gzip 헤더를 처리할 수 있어야 합니다.

브라우저 호환성

요청 본문 압축에는 CompressionStream API가 필요하며, 다음 브라우저에서 사용할 수 있습니다.

• Chrome 80+
• Edge 80+
• Safari 16.4+
• Firefox 113 이상

CompressionStream을 지원하지 않는 브라우저의 경우 SDK는 자동으로 압축되지 않은 페이로드를 전송합니다.

Keepalive를 이용한 페이지 탐색 유지

기본적으로 Browser SDK는 keepalive 플래그가 활성화된 fetch 전송 방식을 통해 이벤트를 전송합니다. 브라우저는 키프얼라이브 요청을 시작한 페이지가 언로드된 후에도 이를 완료할 수 있도록 허용합니다. 결과적으로 리디렉션 또는 탐색 직전에 발생한 이벤트는 취소되지 않고 Amplitude에 도달합니다. 일반적인 예로는 사용자를 즉시 다른 페이지로 이동시키는 로그인 이벤트가 있습니다.

Keepalive는 fetch 전송 방식에만 적용됩니다. beacon전송과 달리 IT는 gzip 압축, 사용자 지정 헤더, 서버 응답 및 재시도를 유지합니다.

Keepalive 크기 제한

Fetch 사양은 문서의 모든 전송 중인 킵얼라이브 요청에 대해 64KiB의 공유 예산을 적용합니다. 이 예산에는 Amplitude 애널리틱스, 세션 리플레이 및 사용자 코드가 생성하는 모든 keepalive 요청이 포함됩니다. 예산 첫 사용 후 유지하기 위해 SDK는 요청 본문이 16KB 이하인 경우에만 킵얼라이브를 적용합니다. 더 큰 페이로드는 크기 제한이 없는 표준 fetch요청으로 전송되지만, 이러한 요청은 페이지 이동 시 유지되지 않으며 이는 이전 버전의 동작과 동일합니다. 일반적인 이벤트 배치의 크기는 이 제한보다 훨씬 작으므로 거의 모든 트래픽이 혜택을 받습니다.

세션 도중에 공유 예산이 소진되어 브라우저가 keepalive 요청을 거부하는 경우, SDK는 다음 플러시 시 해당 요청을 재시도합니다. 그 결과 데이터 손실이 아니라 지연이 발생합니다.

keepalive 비활성화

keepalive는 기본적으로 활성화되어 있습니다. 이 기능을 비활성화하려면 전송 구성에서 enableKeepalive을 false로 설정하십시오. 이 옵션은 fetch 전송에만 적용됩니다.

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

keepalive를 지원하지 않는 브라우저에서는 SDK가 이 옵션을 무시하고 요청을 정상적으로 전송합니다.

sendBeacon 사용

표준 네트워크 요청과 달리, sendBeacon는 사용자가 브라우저를 닫거나 페이지를 떠나더라도 백그라운드에서 이벤트를 전송합니다.

모든 이벤트에 대해 sendBeacon을 사용하도록 전송 설정

sendBeacon를 사용하여 이벤트를 전송하려면 다음 두 가지 방법 중 하나를 사용하여 전송 SDK 옵션을 beacon로 설정하십시오.

amplitude.init(API_KEY, "user@amplitude.com", {
  transport: TransportType.SendBeacon,
  // To make sure the SDK schedules the event right away.
  flushIntervalMillis: 0,
  flushQueueSize: 1,
});

페이지를 종료할 때만 beacon을 사용하도록 전송 방식을 설정하십시오.

Amplitude는 pagehide 이벤트에 대한 자체 이벤트 리스너를 추가할 것을 권장합니다.

window.addEventListener("pagehide", () => {
  amplitude.setTransport("beacon");
  // Sets https transport to use `sendBeacon` API
  amplitude.flush();
});

콘텐츠 보안 정책(CSP)

보안상의 이유로 웹 앱에 엄격한 콘텐츠 보안 정책(CSP)이 구성되어 있는 경우, Amplitude 도메인을 허용하도록 정책을 조정하십시오.

• "스크립트 로더"를 사용할 때는 https://*.amplitude.com를 script-src에 추가하십시오.
• https://*.amplitude.com을 connect-src에 추가하십시오.

쿠키 관리

Browser SDK는 동일한 도메인의 여러 하위 도메인이 공유하려고 할 가능성이 있는 정보를 유지하기 위해 쿠키 저장소를 사용합니다. 여기에는 사용자 세션 및 마케팅 캠페인과 같은 정보가 포함되며, SDK는 이를 별도의 쿠키 항목에 저장합니다.

쿠키 접두사

• AMP: SDK는 AMP 접두사와 API 키의 처음 10자리 숫자 AMP_{first_ten_digits_API_KEY}를 사용하여 사용자 세션 쿠키를 생성합니다.
• AMP_MKTG: SDK는 AMP_MKTG와 API 키의 처음 10자리 숫자 AMP_MKTG_{first_ten_digits_API_KEY}를 사용하여 마케팅 캠페인 쿠키를 생성합니다.
• AMP_TEST: 초기화 시 SDK는 쿠키 저장소가 제대로 작동하는지 확인하기 위해 AMP_TEST 접두사를 가진 쿠키를 생성합니다. 그런 다음 SDK는 값을 현재 시간으로 설정하고 키를 사용하여 쿠키를 검색한 다음 검색된 값이 원래 설정된 시간과 일치하는지 확인합니다. 어떤 이유로든 SDK가 AMP_TEST 접두사 쿠키를 성공적으로 삭제하지 못한 경우, 해당 쿠키를 안전하게 삭제할 수 있습니다.
• AMP_TLDTEST: 초기화 시 SDK는 쿠키 저장을 지원하는 하위 도메인을 찾기 위해 AMP_TLDTEST 접두사가 붙은 쿠키를 생성합니다. 예를 들어, https://analytics.amplitude.com/amplitude/home에서 쿠키 지원 여부를 확인할 때 SDK는 먼저 루트 도메인(amplitude.com)과 일치하는 하위 도메인을 찾으려고 시도하고, 실패하면 전체 도메인(analytics.amplitude.com)으로 되돌아갑니다. 어떤 이유로든 SDK가 **** 접두사 쿠키를 성공적으로 삭제하지 못한 경우, 해당 쿠키를 안전하게 삭제AMP_TLDTEST할 수 있습니다.

쿠키 도메인

기본적으로 SDK는 이러한 쿠키를 쿠키 저장을 지원하는 최상위 도메인에 할당합니다. SDK는 여러 하위 도메인에서 쿠키를 공유할 수 있으므로 모든 하위 도메인에서 일관된 사용자 경험을 제공할 수 있습니다.

예를 들어, 사용자가 SDK를 초기화하는 한 하위 도메인(data.amplitude.com)에서 웹사이트에 로그인하는 경우를 생각해 보겠습니다. 초기화 시 SDK는 쿠키를 .amplitude.com에 할당합니다. 그 후 사용자가 다른 하위 도메인(analytics.amplitude.com)으로 이동하면, 공유 쿠키를 통해 하위 도메인 간에 로그인 정보가 공유됩니다.

쿠키 데이터

SDK는 사용자 세션 쿠키와 마케팅 캠페인 쿠키의 두 가지 유형의 쿠키를 생성합니다.

쿠키 비활성화

identityStorage을 localStorage로 설정하여 쿠키 사용을 거부하면 SDK가 LocalStorage을 대신 사용합니다. LocalStorage는 유용한 대안이지만, LocalStorage에 대한 액세스가 하위 도메인별로 제한되므로 제품의 하위 도메인 간에 익명의 사용자를 추적할 수 없습니다(예: www.amplitude.com 대 analytics.amplitude.com).

amplitude.init("api-key", null, {
  identityStorage: "localStorage",
});

오프라인 모드

버전 2.4.0부터 Amplitude Browser SDK는 오프라인 모드를 지원합니다. SDK는 이벤트를 추적할 때마다 네트워크 연결을 확인합니다. 장치가 네트워크에 연결되어 있으면 SDK에서 플러시를 예약합니다. 그렇지 않은 경우 이벤트를 스토리지에 저장합니다. 또한 SDK는 네트워크 연결 상태 변화를 감지하고 장치가 다시 연결될 때 config.flushIntervalMillis 설정에 따라 저장된 모든 이벤트를 플러시하도록 예약합니다.

오프라인 모드를 비활성화하려면 다음 예시와 같이 amplitude.init() 호출에 offline: amplitude.Types.OfflineDisabled을 추가하십시오.

amplitude.init(AMPLITUDE_API_KEY, {
  offline: amplitude.Types.OfflineDisabled,
});

마케팅 속성 추적

Amplitude는 마케팅 속성을 추적하며 기본적으로 하위 도메인에서 모든 추천자를 제외합니다. 추천자 제외 및 내부 추천자 제외에 대해 자세히 알아보십시오. 마케팅 어트리뷰션 추적을 활성화하면 Amplitude는 특정 시나리오에서 캠페인 값을 사용자 속성으로 할당하기 위해 identify 이벤트를 생성합니다. Amplitude가 마케팅 속성을 추적하고 사용자 속성을 업데이트하는 시기에 대해 알아보려면 다음 섹션을 참조하십시오.

추적 시나리오

Amplitude는 SDK 초기화 및 이벤트 처리의 두 가지 시나리오 다음 기간동안 마케팅 속성의 변화를 추적합니다.

Amplitude SDK 초기화(페이지 강제 새로 고침)

• 세션 시작 시점에 추천인은 제외되지 않으며 캠페인에 전체 변경 사항이 있거나 고객의 첫 방문이 있는 경우입니다.
• 세션 도중에도 추천자는 제외되지 않으며 직접 트래픽도 아니고 캠페인에 전체 변화가 있습니다.

디버깅을 위해서는 브라우저 콘솔에 document.referrer을 입력하여 리퍼러를 확인하고, 이를 config.autocapture.attribution.excludeReferrers와 비교할 수 있습니다. document.referrer이 비어 있으면 Amplitude는 IT를 직접 트래픽으로 간주합니다. Amplitude Chrome 확장 프로그램의 쿠키 탭의 AMP_{last 10 digits of your API key}에서 세션 ID를 확인할 수 있으며, AMP_MKTG_{last 10 digits of your API key}에 저장된 이전 캠페인 정보도 확인할 수 있습니다.

이벤트 처리 중

• 세션이 시작될 때 리퍼러는 제외되지 않으며 캠페인에 전체 변화가 있습니다.

자세한 내용은 Amplitude가 마케팅 속성을 추적할 때와 추적하지 않을 때를 보여주는 아래에 설명된 시나리오를 참조하세요. 이러한 예제는 단순한 설명일 뿐 완전한 예는 아닙니다.

추적은 다음 중 하나가 적용될 때 발생합니다.

Amplitude는 전체 다음과 같은 조건에서 마케팅 속성을 추적하지 않습니다.

SPA(단일 페이지 애플리케이션)의 악성 리퍼럴 문제

방문자가 사이트에 들어온 후에는 일반적으로 SPA에서 실질적인 페이지 로딩을 경험하지 못합니다. 이는 내부 링크를 클릭할 때 추천자 정보가 업데이트되지 않음을 의미합니다. UTM 매개변수는 SPA 리디렉션 다음 기간동안 삭제될 수 있지만 리퍼럴은 변경되지 않은 상태로 유지됩니다. 이는 업계에서 알려진 문제입니다. 이 문제를 해결하려면 다음 중 하나를 수행하십시오.

• 페이지 및 위치 매개 변수를 제어하거나
• 첫 번째 히트 후 리퍼러의 설정을 해제합니다.

원격 구성

버전 2.10.0부터 Amplitude Browser SDK는 원격 구성을 지원합니다.

자동 캡처는 기본 이벤트를 추적하기 위한 원격 구성 옵션을 지원합니다. 원격 구성을 활성화하면 Amplitude 서버의 설정이 로컬 SDK 구성과 병합되며 원격 설정이 우선합니다. _데이터 > 설정 > 자동 캡처_에서 원격 구성 옵션을 찾으십시오.

원격 구성 활성화 또는 비활성화

SDK 버전 2.16.1 이상: 원격 구성은 기본적으로 활성화되어 있습니다. 비활성화하려면 fetchRemoteConfig: false를 명시적으로 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, {
  fetchRemoteConfig: false, // Disable remote config
});

SDK 버전 2.10.0~2.16.0의 경우: 원격 구성은 기본적으로 비활성화되어 있습니다. 활성화하려면 fetchRemoteConfig: true를 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, {
  fetchRemoteConfig: true, // Enable remote config (only needed for versions < 2.16.1)
});

Amplitude에서 _데이터 > 설정 > Autocapture_로 이동하여 원격 구성을 추가하거나 업데이트합니다.

프록시 원격 구성 요청

자체 서버를 통해 원격 구성 요청을 프록시하려면(예: 광고 차단기를 우회하기 위해), remoteConfig 옵션을 구성하십시오.

amplitude.init(AMPLITUDE_API_KEY, {
  remoteConfig: {
    serverUrl: "https://your-proxy.example.com/config",
  },
});

remoteConfig.serverUrl을 설정하면 SDK는 Amplitude의 엔드포인트 대신 사용자 지정 URL로 원격 구성 요청을 전송합니다. 분석 이벤트는 여전히 serverUrl 또는 기본 Amplitude 엔드포인트를 사용합니다.