Browser SDK 2 참조
이 참조는 버전 2.48.1에 대해 확인된 @amplitude/analytics-browser의 모든 공개 내보내기와 init()로 전달할 수 있는 모든 옵션을 설명합니다. 스크립트 로더를 사용하면 전역 amplitude 객체에서 동일한 멤버를 사용할 수 있습니다. 옵션을 보려면 구성 옵션으로 이동합니다. 기능이 추가되거나 변경된 릴리즈를 찾으려면 Browser SDK 2 릴리즈 노트를 참조하십시오.
import * as amplitude from "@amplitude/analytics-browser";
최상위 함수는 기본 인스턴스에서 작동합니다. createInstance()의 각 인스턴스는 동일한 메서드를 갖습니다.
반환 값
비동기식 작업을 수행하는 메서드는 하나의 속성을 가진 객체인 AmplitudeReturn<T>를 반환합니다.promise 반환 값 자체가 아닌 promise를 기다립니다.
const result = await amplitude.track("Song Played").promise; // correct
const wrapper = await amplitude.track("Song Played"); // returns { promise }, not a Result
업로드 시도가 완료되면 추적 메서드가 Result로 확인됩니다.
| 속성 | 유형 | 설명 |
|---|---|---|
event | Event | 모든 플러그인이 실행된 후 전송된 이벤트입니다. |
code | number | HTTP 상태 코드이거나, SDK가 이벤트를 건너뛸 때는 0입니다. |
message | string | 결과에 대한 설명입니다(예: Event tracked successfully). |
모든 코드 및 메시지에 대해서는 '업로드 결과 읽기'로 이동하십시오.
init()가 완료되기 전에 수행된 호출은 대기열에서 대기하다가 완료된 후 순서대로 실행됩니다. 해당 프로미스는 init()가 완료되고 업로드가 완료된 후 해결됩니다.
설정
초기화
인스턴스를 초기화합니다. 인스턴스당 한 번씩 호출합니다. 완료된 후 다시 호출하면 추가한 플러그인을 포함한 모든 플러그인이 해제되며 다시 시작됩니다.
init(apiKey: string, options?: BrowserOptions): AmplitudeReturn<void>
init(apiKey: string, userId?: string, options?: BrowserOptions): AmplitudeReturn<void>
| 매개 변수 | 유형 | 설명 |
|---|---|---|
apiKey | string | Amplitude 프로젝트 API 키입니다. |
userId | string | 선택 사항입니다. 이 브라우저의 사용자 ID입니다. options.userId과 동일합니다. |
options | BrowserOptions | 선택 사항입니다. 구성 참조를 참조하십시오. |
promise는 SDK가 원격 구성을 가져오고, 플러그인을 설치하고, 대기열에 있는 호출을 실행한 후 해결됩니다.
await amplitude.init("YOUR_API_KEY", "user-12345", {
serverZone: "EU",
}).promise;
createInstance
자체 구성, ID, 큐 및 플러그인을 사용하여 독립적 인스턴스를 생성합니다. 이를 사용하여 둘 이상의 프로젝트로 데이터를 전송합니다.
createInstance(): BrowserClient
const secondary = amplitude.createInstance();
secondary.init("OTHER_API_KEY", { instanceName: "secondary" });
스크립트 로더를 사용하면 amplitude.createInstance(name)도 인스턴스를 아래에 등록하여 nameSDK가 로드되기 전에 수행된 호출이 해당 인스턴스에 도달하도록 합니다.
추가
플러그인을 추가합니다. setup()인스턴스에서 이미 실행된 경우init() 즉시 실행되고, init()그렇지 않은 경우 실행됩니다. SDK는 이미 추가된 플러그인과 name일치하는 플러그인이 있으면 건너뛰고 경고를 기록합니다.
add(plugin: Plugin): AmplitudeReturn<void>
await amplitude.add({
name: "add-app-section",
execute: async (event) => {
event.event_properties = { ...event.event_properties, section: "checkout" };
return event;
},
}).promise;
플러그인 컨트랙트를 보려면 Plugin으로 이동하십시오.
제거
이름으로 플러그인을 제거하고 해당 플러그인의 함수를 teardown()호출합니다.
remove(pluginName: string): AmplitudeReturn<void>
amplitude.remove("add-app-section");
setTransport
향후 업로드를 위해 HTTP API를 변경합니다.
setTransport(transport: "fetch" | "xhr" | "beacon" | TransportOptions): void
window.addEventListener("pagehide", () => {
amplitude.setTransport("beacon");
amplitude.flush();
});
플러시
이제 대기열에 있는 모든 이벤트를 업로드합니다. 수동 플러시는 실패한 업로드를 재시도하지 않습니다.
flush(): AmplitudeReturn<void>
await amplitude.flush().promise;
추적
추적
사용자 지정 이벤트를 전송합니다. logEvent() 는 동일한 서명을 가진 별칭입니다.
track(eventInput: string | BaseEvent, eventProperties?: Record<string, any>, eventOptions?: EventOptions): AmplitudeReturn<Result>
logEvent(eventInput: string | BaseEvent, eventProperties?: Record<string, any>, eventOptions?: EventOptions): AmplitudeReturn<Result>
| 매개 변수 | 유형 | 설명 |
|---|---|---|
eventInput | string | BaseEvent | 이벤트 이름 또는 event_type 및 기타 이벤트 필드를 포함하는 BaseEvent 객체입니다. |
eventProperties | Record<string, any> | 선택 사항입니다. 이벤트에서 event_properties대체합니다. |
eventOptions | EventOptions | 선택 사항입니다. 이 이벤트에 대해서만 인스턴스 상태를 재정의하는 이벤트 필드(예: user_id, device_id, time, 또는 insert_id). |
amplitude.track(
"Song Played",
{ title: "Here Comes the Sun" },
{ time: Date.now() },
);
식별
사용자 속성을 업데이트하는 $identify이벤트를 보냅니다.user_id 에 device_id 또는 eventOptions 가 포함된 경우, SDK는 이를 사용하여 setUserId() 또는 setDeviceId() 를 호출합니다.
identify(identify: Identify, eventOptions?: EventOptions): AmplitudeReturn<Result>
amplitude.identify(new amplitude.Identify().set("plan", "pro"));
setGroup
groups 가 설정된 $identify이벤트를 전송하여 현재 사용자를 그룹에 할당합니다.
setGroup(groupType: string, groupName: string | string[], eventOptions?: EventOptions): AmplitudeReturn<Result>
amplitude.setGroup("company", "Acme Inc");
groupIdentify
한 그룹의 속성을 업데이트하는 $groupidentify이벤트를 보냅니다. 업데이트는 해당 시점 이후의 이벤트에만 적용됩니다.
groupIdentify(groupType: string, groupName: string | string[], identify: Identify, eventOptions?: EventOptions): AmplitudeReturn<Result>
amplitude.groupIdentify(
"company",
"Acme Inc",
new amplitude.Identify().set("seats", 250),
);
매출
객체Revenue에서 생성된 revenue_amount이벤트를 보냅니다.
revenue(revenue: Revenue, eventOptions?: EventOptions): AmplitudeReturn<Result>
amplitude.revenue(
new amplitude.Revenue().setProductId("pro-annual").setPrice(99.99),
);
trackVideo
실험적. <video> 요소 또는 player.js 내장 플레이어의 트랙 Video Content Started및 Video Content Stopped이벤트를 추적합니다. Browser SDK 2.39.0 이상이 필요합니다.
trackVideo(amplitude: BrowserClient, video: HTMLVideoElement | EmbeddedVideoPlayer, options?: VideoCaptureOptions): (() => void) | Error
| 매개 변수 | 유형 | 설명 |
|---|---|---|
amplitude | BrowserClient | 이벤트를 전송하는 인스턴스. |
video | HTMLVideoElement | EmbeddedVideoPlayer | 관찰해야 하는 플레이어. |
options.vendor | VideoVendor | 선택 사항입니다. 내장 플레이어 공급업체. |
options.extraEventProperties | Record<string, string | number | boolean> | 선택 사항입니다. 생성된 view_session_id과 함께 모든 비디오 이벤트에 추가된 속성. |
추적을 중단하는 함수를 반환하거나, SDK가 연결할 수 없는 경우 Error를 반환합니다.
const stop = amplitude.trackVideo(amplitude, document.querySelector("video")!);
아이덴티티
getUserId 및 setUserId
향후 이벤트를 위해 사용자 ID를 읽거나 설정합니다. setUserId(undefined)이를 지우려면 사용하세요.
getUserId(): string | undefined
setUserId(userId: string | undefined): void
amplitude.setUserId("user-12345");
getDeviceId 및 setDeviceId
향후 이벤트를 위해 장치 ID를 읽거나 설정합니다.
getDeviceId(): string | undefined
setDeviceId(deviceId: string): void
amplitude.setDeviceId("2f9d6a1e-4b7c-4f0e-9a51-0c3e8b7d5a12");
재설정
사용자 ID를 지우고 새 장치 ID를 생성합니다. 사용자가 로그아웃할 때 사용하십시오. 새 세션을 시작하지는 않습니다.
reset(): void
amplitude.reset();
getIdentity 및 setIdentity
장치 ID, 사용자 ID 및 사용자 속성을 함께 읽거나 업데이트합니다. setIdentity()이(가) userProperties을(를) 수신하면 각 키를 $set(으)로 설정하는 $identify 이벤트를 전송합니다. userProperties은(는) 이 페이지 로드에서 설정된 속성만 보관합니다. getIdentity()은(는) 브라우저 SDK 2.18.0 이상이 필요하며, setIdentity()은(는) 2.35.0 이상이 필요합니다.
getIdentity(): { deviceId?: string; userId?: string; userProperties?: Record<string, any> }
setIdentity(identity: { deviceId?: string; userId?: string; userProperties?: Record<string, any> }): void
amplitude.setIdentity({
userId: "user-12345",
userProperties: { plan: "pro" },
});
세션
getSessionId 및 setSessionId
현재 세션 ID를 읽거나, 현재 세션을 종료하고 지정된 ID로 세션을 시작합니다. Unix 타임스탬프를 밀리초 단위로 전달합니다. 옵트아웃된 인스턴스는 ID를 저장하고 옵트아웃이 꺼지면 세션을 시작합니다.
getSessionId(): number | undefined
setSessionId(sessionId: number): void
amplitude.setSessionId(Date.now());
extendSession
이벤트를 전송하지 않고 세션을 현재 활성화로 표시합니다.
extendSession(): void
amplitude.extendSession();
개인정보 보호
getOptOut 및 setOptOut
읽거나 옵트아웃을 설정합니다. 옵트아웃 상태인 동안 trueSDK는 모든 이벤트를 삭제합니다. 값은 ID 저장소에 유지됩니다. getOptOut()브라우저 SDK 2.18.0 이상이 필요합니다.
getOptOut(): boolean | undefined
setOptOut(optOut: boolean): void
amplitude.setOptOut(true);
Identify
Identify identify()는 groupIdentify(), 및 identifyinit 옵션에 대한 사용자 속성 또는 그룹 속성 작업을 구축합니다. 각 메서드는 동일한 객체를 반환하므로 호출을 체이닝할 수 있습니다. 각 속성은 객체당 하나의 작업만 수행할 수 있습니다. SDK는 동일한 속성에 대한 이후 작업 및 그 clearAll()이후의 모든 작업을 무시합니다.
const identify = new amplitude.Identify();
| 메서드 | 작업 | 설명 |
|---|---|---|
set(property, value) | $set | 값을 설정합니다. |
setOnce(property, value) | $setOnce | 속성에 값이 없는 경우 값을 설정합니다. |
add(property, value: number) | $add | 숫자 값에 추가합니다. 숫자가 아닌 항목은 무시합니다. |
append(property, value) | $append | 목록에 추가합니다. |
prepend(property, value) | $prepend | 목록 앞에 추가합니다. |
postInsert(property, value) | $postInsert | 리스트에 아직 없는 값을 추가합니다. |
preInsert(property, value) | $preInsert | 목록에 없는 값을 앞에 추가합니다. |
remove(property, value) | $remove | 리스트에서 값을 제거합니다. |
unset(property) | $unset | 속성을 제거합니다. |
clearAll() | $clearAll | 모든 속성을 제거합니다. 이 명령은 취소할 수 없습니다. |
getUserProperties() | 해당 없음 | operations 객체를 반환합니다(예: { $set: { plan: "pro" } }). |
값은 문자열, 숫자, 부울, 배열 또는 해당 유형의 객체를 허용합니다.
매출
Revenue revenue_amount는 이벤트의 속성을 구축합니다. 각 setter는 동일한 객체를 반환합니다.
const revenue = new amplitude.Revenue();
| 메서드 | 이벤트 속성 | 기본값 | 설명 |
|---|---|---|---|
setProductId(id: string) | $productId | "" | 제품 식별자입니다. |
setPrice(price: number) | $price | 0 | 한 항목의 가격입니다. 음수일 수 있습니다. |
setQuantity(quantity: number) | $quantity | 1 | 항목 수입니다. 0또는 그 이하의 값을 무시합니다. |
setRevenue(revenue: number) | $revenue | undefined | 총 수익. 설정되지 않은 경우 Amplitude는 price * quantity를 계산합니다. |
setRevenueType(type: string) | $revenueType | undefined | 범주(예: subscription 또는 refund). 수익 확인에 필요합니다. |
setCurrency(code: string) | $currency | undefined | 전환을 위한 ISO 4217 통화 코드입니다. |
setReceipt(receipt: string) | $receipt | undefined | 구매 영수증. |
setReceiptSig(signature: string) | $receiptSig | undefined | 영수증 서명. 수익 확인에 필요합니다. |
setEventProperties(properties: object) | 이벤트 속성에 병합됨 | undefined | 추가 속성. SDK는 undefined값을 삭제하고 유효하지 않은 객체를 무시합니다. |
getEventProperties() | 해당 없음 | 해당 없음 | SDK가 전송하는 이벤트 속성을 반환합니다. |
플러그인
플러그인은 SDK가 모든 이벤트에 대해 실행하는 객체입니다. add()에 전달합니다.
| 회원 | 필수 | 설명 |
|---|---|---|
name | 아니요 | 고유 이름입니다. remove()에 의해 사용됩니다. SDK에서 이를 생략하면 UUID를 생성하고 경고를 표시합니다. |
type | 아니요 | "before", "enrichment" (기본값), 또는 "destination". |
setup(config, client) | 아니요 | 플러그인이 설치될 때 한 번 실행됩니다. 확인된 항목과 인스턴스를 BrowserConfig받습니다. |
execute(event) | 목적지: yes | Before 플러그인과 enrichment 플러그인은 변경된 이벤트를 반환하거나 null(을)를 반환합니다. 목적지 플러그인은 이벤트를 전송하고 Result를 반환합니다. |
teardown() | 아니요 | remove()항목에서 실행되며 해당 항목이 다시 실행될 때 init()실행됩니다. 여기에서 리스너를 제거합니다. |
flush() | 아니요 | 목적지 플러그인만 amplitude.flush()에서 실행됩니다. |
onIdentityChanged(identity) | 아니요 | setUserId(), setDeviceId(), setIdentity(), reset(), 및 identify()후에 실행됩니다. 최선을 다합니다. |
onSessionIdChanged(sessionId) | 아니요 | 새 세션이 시작될 때 실행됩니다. |
onOptOutChanged(optOut) | 아니요 | 값이 변경될 때 setOptOut()실행됩니다. |
onReset() | 아니요 | reset()에서 실행됩니다. |
각 이벤트에 대해 SDK는 모든 이전 플러그인, 그 다음 모든 강화 플러그인, 마지막으로 모든 목적지 플러그인을 순서대로 실행합니다. 동일한 유형의 플러그인은 추가한 순서대로 실행됩니다. Plugins는 내장된 자동 캡처 플러그인보다 먼저 설치되므로, init()먼저 실행됩니다.
const lowercaseUserId: amplitude.Types.BeforePlugin = {
name: "lowercase-user-id",
type: "before",
execute: async (event) => {
if (event.user_id) event.user_id = event.user_id.toLowerCase();
return event;
},
};
amplitude.add(lowercaseUserId);
이벤트를 자체 엔드포인트로 전달하는 목적지 플러그인:
const forwardToWarehouse = (
url: string,
): amplitude.Types.DestinationPlugin => ({
name: "forward-to-warehouse",
type: "destination",
execute: async (event) => {
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(event),
});
return { event, code: response.status, message: response.statusText };
},
});
amplitude.add(forwardToWarehouse("https://collect.example.com/events"));
Amplitude는 페이지 URL 강화 및 사용자 정의 강화와 같은 기성 플러그인을 게시합니다. 자세한 내용은 SDK 플러그인을 참조하십시오.
유형
amplitude.Types 다음을 포함하여 TypeScript 유형 및 상수를 내보냅니다.
| 내보내기 | 설명 |
|---|---|
BrowserOptions | init()옵션 객체입니다. |
BaseEvent, Event, EventOptions | 이벤트 형태. |
Result | 추적 프로미스의 해결된 값(resolved value). |
Plugin, BeforePlugin, EnrichmentPlugin, DestinationPlugin | 플러그인 형태. |
LogLevel | Enum: None, Error, Warn, Verbose, Debug. |
OfflineDisabled | 연결 감지를 해제하는offline 옵션에 대한 값입니다. |
TransportType | "fetch" | "xhr" | "beacon". enum이 아닌 문자열 유형입니다. |
ServerZoneType | "US" | "EU". |
IdentityStorageType | "cookie" | "localStorage" | "sessionStorage" | "none". |
AutocaptureOptions, AttributionOptions, ElementInteractionsOptions | 자동 캡처 옵션 모양. |
DEFAULT_CSS_SELECTOR_ALLOWLIST, DEFAULT_ACTION_CLICK_ALLOWLIST, DEFAULT_DATA_ATTRIBUTE_PREFIX | 목록 확장을 위한 요소 상호 작용 기본값. |
연동 내보내기
이러한 내보내기는 다른 Amplitude 패키지에 대해 존재합니다. 대부분의 앱에서는 이러한 기능이 필요하지 않습니다.
| 내보내기 | 목적 |
|---|---|
AmplitudeBrowser | 클라이언트 클래스는 @amplitude/unified이 클래스 위에 구축됩니다. 대신 createInstance()을 사용하십시오. |
runQueuedFunctions | 스크립트 로더 스니펫에 의해 대기열에 넣은 호출을 재생합니다. |
_setDiagnosticsSampleRate | 내부 테스트만 가능합니다. 예고 없이 변경될 수 있습니다. |
구성 옵션
이 섹션에서는 브라우저 SDK 2.48.1 기준으로, BrowserOptions에 전달하는 구성 객체의 모든 옵션을 init()나열합니다. 모든 옵션은 선택 사항입니다. 지원 중단된 옵션은 여전히 작동합니다.
amplitude.init(apiKey: string, options?: BrowserOptions);
amplitude.init(apiKey: string, userId?: string, options?: BrowserOptions);
Identity 및 session
| 옵션 | 유형 | 기본값 | 설명 |
|---|---|---|---|
userId | string | undefined | 모든 이벤트의 사용자 ID입니다. init()의 userId인수와 동일합니다. 두 인수를 모두 전달하면 가 승리합니다. |
deviceId | string | URL, 쿠키 또는 새 UUID에서 | 모든 이벤트의 장치 ID입니다. ampDeviceIdURL 매개 변수와 저장된 값을 재정의합니다. |
sessionId | number | URL, 쿠키 또는 Date.now()에서 | 세션 ID(밀리초 단위의 Unix 타임스탬프)입니다. 로드 시 이 세션을 시작합니다. |
sessionTimeout | number | 1800000 (30분) | 새 세션이 시작되기 전까지의 비활성 시간(밀리초 단위)입니다. |
optOut | boolean | 저장된 값, 또는 false | true인 경우, SDK는 모든 이벤트를 삭제하고 세션을 시작하지 않습니다. ID 스토리지에 지속됩니다. |
identify | Identify | undefined | IdentifySDK가 모든 세션 시작 시 전에 전송하는 객체입니다session_start. 2.25.0 이상이 필요합니다. |
identityStorage | "cookie" | "localStorage" | "sessionStorage" | "none" | "cookie" | SDK가 장치 ID, 사용자 ID, 세션 상태 및 옵트아웃을 유지하는 위치이며, "none"메모리에 보관합니다. |
cookieOptions | CookieOptions | 쿠키 옵션을 참조하십시오. | ID 및 캠페인 쿠키의 속성. identityStorage가 "cookie"인 경우 적용됩니다. |
minIdLength | number | undefined(Amplitude가 적용5) | user_id및 device_id에 허용되는 최소 길이입니다. SDK는 각 업로드 시 이를 함께 options.min_id_length전송합니다. |
instanceName | string | "$default_instance" | 이 인스턴스의 이름입니다. 각 인스턴스에 고유한 이름을 지정합니다createInstance(). |
쿠키 옵션
| 옵션 | 유형 | 기본값 | 설명 |
|---|---|---|---|
cookieOptions.domain | string | 가장 높은 쓰기 가능 도메인, .example.com | Cookie Domain 속성. 호스트 전용 쿠키로 ""설정합니다. |
cookieOptions.expiration | number | 365 | 쿠키 수명 (일 단위)입니다. |
cookieOptions.sameSite | "Strict" | "Lax" | "None" | "Lax" | 쿠키 SameSite 속성. "None" 는 secure: true를 필요로 합니다. |
cookieOptions.secure | boolean | false | HTTPS를 통해서만 쿠키를 전송하도록 Secure속성을 추가합니다. |
cookieOptions.upgrade | boolean | true | 유지 관리 JavaScript SDK(amp_ 접두사)에서 설정한 쿠키에서 ID를 읽은 다음 삭제합니다. |
SDK는 다음과 같은 쿠키를 작성합니다.
| 쿠키 | 내용 |
|---|---|
AMP_<first 10 characters of API key> | 장치 ID, 사용자 ID, 세션 ID, 마지막 이벤트 시간, 마지막 이벤트 ID, 옵트아웃 및 페이지 카운터를 Base64로 인코딩된 URI로 인코딩된 JSON 형식으로 제공합니다. |
AMP_MKTG_<first 10 characters of API key> | 어트리뷰션이 기록한 마지막 캠페인 |
AMP_TEST, AMP_TLDTEST | SDK가 쿠키 지원을 테스트하고 쿠키 도메인을 찾기 위해 init()중에 작성하고 삭제하는 임시 쿠키 |
데이터 수집
| 옵션 | 유형 | 기본값 | 설명 |
|---|---|---|---|
autocapture | boolean | AutocaptureOptions | 기본값으로 설정된 | SDK가 자동으로 추적하는 이벤트입니다. 자동 캡처 옵션을 참조하십시오. |
defaultTracking | boolean | DefaultTrackingOptions | undefined | 더 이상 사용되지 않습니다. autocapture을(를) 사용하십시오. attribution, fileDownloads, formInteractions, pageViews, 및 sessions을(를) 허용합니다. autocapture이 설정된 경우 무시됩니다. |
trackingOptions.ipAddress | boolean | true | ip: "$remote"를 전송하므로 Amplitude는 요청 IP를 기록합니다. |
trackingOptions.language | boolean | true | navigator.language에서 language전송합니다. |
trackingOptions.platform | boolean | true | platform: "Web"를 전송합니다. |
appVersion | string | undefined | 모든 이벤트에 대해 app_version설정합니다. |
customEnrichment | boolean | { enabled?: boolean; body: string } | false | 프로젝트의 원격 구성에서 보강 함수를 실행하는 Custom Enrichment 플러그인을 설치합니다. 실험적. 2.37.0 이상이 필요합니다. |
partnerId | string | undefined | partner_id를 설정합니다. 이벤트 수집 통합을 구축하는 파트너를 위한. |
plan | { branch?, source?, version?, versionId? } | undefined | 이벤트에 첨부된 트래킹 플랜 메타데이터입니다. Ampli에서 설정합니다. |
ingestionMetadata | { sourceName?, sourceVersion? } | undefined | 이벤트에 첨부된 수집 소스 메타데이터입니다. Ampli 및 통합에 의해 설정됩니다. |
pageCounter | number | 저장된 값 | 이 세션의 [Amplitude] Page Counter시작 값입니다. |
전송
| 옵션 | 유형 | 기본값 | 설명 |
|---|---|---|---|
serverZone | "US" | "EU" | "US" | 이벤트 업로드 및 원격 구성을 위한 데이터 센터. |
serverUrl | string | serverZone및 useBatch에서 파생됨 | 업로드 엔드포인트. 이벤트에 대한 serverZone및 useBatch를 재정의합니다. |
useBatch | boolean | false | HTTP V2(/2/httpapi) 대신 배치 이벤트 업로드 API(/batch)로 전송합니다. |
flushIntervalMillis | number | 1000 | 첫 번째 대기열에 추가된 이벤트와 업로드 사이의 시간(밀리초)입니다. 또한 브라우저가 다시 온라인 상태가 된 후 업로드하기까지의 지연 시간도 포함됩니다. |
flushQueueSize | number | 30 | 업로드 요청당 최대 이벤트 수입니다. 더 큰 큐는 여러 요청으로 나뉘어 순차적으로 전송됩니다. 이 크기에 도달해도 조기 업로드가 트리거되지 않습니다. |
flushMaxRetries | number | 5 | SDK가 삭제하기 전에 이벤트당 업로드 시도 횟수입니다. |
transport | "fetch" | "xhr" | "beacon" | TransportOptions | "fetch" | 업로드를 위한 HTTP API입니다. 전송 옵션을 참조하십시오. |
enableRequestBodyCompression | boolean | false | 사용자 지정serverUrl에 대해 2KB 이상의 본문을 Gzip 압축합니다. Amplitude의 자체 엔드포인트는 브라우저가 압축을 지원할 때 항상 압축을 사용합니다. 2.36.0 이상이 필요합니다. Amplitude 엔드포인트에 대한 기본값이 2.42.0에서 변경되었습니다. |
offline | boolean | OfflineDisabled | false | navigator.onLine에서 SDK에 의해 관리됩니다. 연결 감지를 끄려면 amplitude.Types.OfflineDisabled를 설정합니다. 2.4.0 이상이 필요합니다. |
storageProvider | Storage<Event[]> | localStorage | unsent-event 큐를 위한 스토리지입니다. 공급자가 사용할 수 없다고 보고할 때 메모리로 폴백합니다. |
전송 옵션
| 옵션 | 유형 | 기본값 | 설명 |
|---|---|---|---|
transport.type | "fetch" | "xhr" | "beacon" | "fetch" | 업로드를 위한 HTTP API입니다. |
transport.headers | Record<string, string> | {} | 추가 요청 헤더. beacon에 의해 무시되었습니다. Content-Type또는 Accept는 대체할 수 없습니다. 2.33.0 이상이 필요합니다. |
transport.enableKeepalive | boolean | true | 압축 후 측정된 본문이 16KB 이하인 요청에 대해 fetch를 설정합니다keepalive. 기본값이 2.43.0에서 변경되었습니다. |
transport.referrerPolicy | ReferrerPolicy | 브라우저 기본값 | fetch 업로드에 대한 리퍼러 정책. 2.44.0 이상이 필요합니다. |
원격 구성 및 진단
| 옵션 | 유형 | 기본값 | 설명 |
|---|---|---|---|
remoteConfig.fetchRemoteConfig | boolean | true | init()중에 프로젝트에서 자동 캡처 및 사용자 지정 강화 설정을 가져옵니다. 원격 값은 기능별로 로컬 값을 재정의합니다. |
remoteConfig.serverUrl | string | Amplitude 엔드포인트 serverZone | 프록시와 같은 원격 구성 요청에 대한 사용자 지정 URL입니다. 2.28.0 이상이 필요합니다. |
fetchRemoteConfig | boolean | true | 더 이상 사용되지 않습니다. 두 위치 중 어디에서든 remoteConfig.fetchRemoteConfig. false을(를) 사용하면 remoteConfig.fetchRemoteConfig 이(가) true. 인 경우를 제외하고 가져오기가 해제됩니다. 2.10.0 이상이 필요합니다. 기본값이 2.16.1에서 변경되었습니다. |
enableDiagnostics | boolean | true | SDK가 자체 오류와 dropped-event 수를 Amplitude에 리포트하도록 합니다. Amplitude는 샘플 속도를 원격으로 설정합니다. 진단에는 이벤트 속성이 아니라 이벤트 이름, 오류 메시지 및 사용자 에이전트가 포함됩니다. |
logLevel | LogLevel | LogLevel.Warn | 콘솔 로그 수준: None (0), Error (1), Warn (2), Verbose (3), Debug (4). |
loggerProvider | ILogger | 콘솔 로거 | enable(level), disable(), log(), warn(), error(), 및 debug() 메서드를 사용하는 사용자 지정 로거입니다. SDK는 logLevel를 enable() 로 호출합니다. |
사용자 지정 loggerProvider은 모든 ILogger 메서드를 구현해야 합니다. 이 예제는 SDK 오류를 자체 오류 보고에 전달하고 기본 콘솔 출력을 유지합니다.
class ErrorReportingLogger implements amplitude.Types.ILogger {
private level = amplitude.Types.LogLevel.Warn;
enable(logLevel: amplitude.Types.LogLevel) {
this.level = logLevel;
}
disable() {
this.level = amplitude.Types.LogLevel.None;
}
log(...args: any[]) {
if (this.level >= amplitude.Types.LogLevel.Verbose) console.log(...args);
}
warn(...args: any[]) {
if (this.level >= amplitude.Types.LogLevel.Warn) console.warn(...args);
}
error(...args: any[]) {
reportError(args.join(" ")); // Your error reporting, at every log level.
if (this.level >= amplitude.Types.LogLevel.Error) console.error(...args);
}
debug(...args: any[]) {
if (this.level >= amplitude.Types.LogLevel.Debug) console.log(...args);
}
}
amplitude.init("YOUR_API_KEY", { loggerProvider: new ErrorReportingLogger() });
자동 캡처 옵션
autocapture 는 true, false또는 이러한 키를 가진 객체를 허용합니다. 동작 및 예제를 보려면 자동 캡처로 이동하십시오.
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
attribution | boolean | AttributionOptions | true | 마케팅 어트리뷰션 |
pageViews | boolean | PageTrackingOptions | true | [Amplitude] Page Viewed 이벤트. |
sessions | boolean | true | session_start 및 session_end 이벤트. |
formInteractions | boolean | FormInteractionsOptions | true | [Amplitude] Form Started 및 [Amplitude] Form Submitted 이벤트. |
fileDownloads | boolean | true | [Amplitude] File Downloaded 이벤트. |
pageUrlEnrichment | boolean | true | 모든 이벤트의 Page 및 previous-page 속성. 실험적. 2.22.0 이상이 필요합니다. 기본값이 2.29.0에서 변경되었습니다. |
elementInteractions | boolean | ElementInteractionsOptions | false | [Amplitude] Element Clicked 및 [Amplitude] Element Changed 이벤트. |
frustrationInteractions | boolean | FrustrationInteractionsOptions | false | Rage click, dead click, error click 및 thrashed cursor 이벤트. 2.24.0 이상이 필요합니다. |
networkTracking | boolean | NetworkTrackingOptions | false | [Amplitude] Network Request 이벤트. 2.17.0 이상이 필요합니다. |
webVitals | boolean | WebVitalsOptions | false | [Amplitude] Web Vitals 이벤트. 실험적. 2.20.0 이상이 필요합니다. |
performanceTracking | boolean | PerformanceTrackingOptions | false | [Amplitude] Main Thread Block 이벤트. autocapture: true에 의해 켜지지 않았습니다. 2.41.0 이상이 필요합니다. |
autocapture: true를 제외한 모든 키를 설정합니다performanceTracking. Chrome 확장 프로그램에서 default-on 키는 설정하지 않으면 꺼져 있습니다. 기본값은 2.42.1에서 변경되었습니다.
AttributionOptions
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
trackingMethod | "userProperty" | "eventProperty" | 둘 다 | ["userProperty", "eventProperty"] | SDK가 캠페인을 기록하는 방법입니다. 잘못된 값은 기본값으로 대체됩니다. "eventProperty"이 기능에는 2.40.0 이상이 필요합니다. 기본값이 2.45.0에서 변경되었습니다. |
excludeReferrers | (string | RegExp)[] | RegExp로 지정된 최상위 도메인 | 무시할 참조 도메인입니다. 문자열이 정확하게 일치합니다. userProperty에만 해당합니다. |
excludeInternalReferrers | boolean | { condition?: "always" | "ifEmptyCampaign" } | false | 페이지의 자체 도메인에 있는 참조자를 무시합니다. true 는 { condition: "always" } 와 같습니다. userProperty 만 해당합니다. 2.36.0 이상이 필요합니다. |
initialEmptyValue | string | "EMPTY" | 캠페인 값이 없는 initial_*사용자 속성의 값입니다. userProperty 만 해당합니다. |
resetSessionOnNewCampaign | boolean | false | 캠페인이 변경될 때 새 세션을 시작합니다. (userProperty 만 해당) |
fallbackAttributionEvent | boolean | false | 모든 페이지 뷰에서 [Amplitude] Attribution 을(를) 전송합니다. (eventProperty 만 해당) |
PageTrackingOptions
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
trackOn | "attribution" | () => boolean | undefined (always) | 페이지 뷰를 전송할 시기입니다. "attribution" 은(는) 새로운 캠페인이 있을 때만 전송합니다. |
trackHistoryChanges | "all" | "pathOnly" | undefined ("all"와 동일) | 어떤 pushState 및 popstate URL 변경 사항이 페이지 뷰를 전송합니까? |
eventType | string | "[Amplitude] Page Viewed" | 페이지 뷰에 대한 이벤트 이름입니다. |
FormInteractionsOptions
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
shouldTrackSubmit | (event: SubmitEvent) => boolean | undefined (always) | 제출을 위해 [Amplitude] Form Submitted 건너뛰려면 false 돌아가기를 누르십시오. Form Started에는 영향을 주지 않습니다. 2.34.0 이상이 필요합니다. |
ElementInteractionsOptions
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
cssSelectorAllowlist | string[] | DEFAULT_CSS_SELECTOR_ALLOWLIST | 추적할 요소입니다. 기본값을 대체합니다. |
actionClickAllowlist | string[] | ["div", "span", "h1", "h2", "h3", "h4", "h5", "h6"] | 클릭이 DOM을 변경하거나 탐색할 때만 추가 요소가 추적됩니다. |
pageUrlAllowlist | (string | RegExp)[] | 모든 페이지 | 추적이 실행되는 페이지 |
pageUrlExcludelist | (string | RegExp | { pattern: string })[] | 없음 | 추적이 실행되지 않는 페이지 허용목록보다 우선합니다. |
shouldTrackEventResolver | (actionType: "click" | "change", element: Element) => boolean | undefined | 요소별 결정. 모든 허용목록을 재정의합니다. |
dataAttributePrefix | string | "data-amp-track-" | data-속성으로 캡처할 속성의 접두사입니다. |
maskTextRegex | (RegExp | { pattern: string; description: string })[] | 없음 | 캡처된 텍스트에서 마스킹할 추가 패턴. |
visualTaggingOptions | { enabled?: boolean } | undefined | 시각적 라벨링 선택기 연동을 제어합니다. |
viewportContentUpdated | { enabled?: boolean; exposureDuration?: number } | { enabled: true, exposureDuration: 150 } | 구역 지정을 위한 뷰포트 노출 추적. exposureDuration 는 밀리초 단위입니다. |
shadowDomEnabled | boolean | false | 열린 섀도우 루트에서 상호 작용을 캡처합니다. 실험적. 다음 페이지가 로드될 때까지 켜져 있습니다. |
maxShadowDomDepth | number | 1 | 교차할 섀도우 경계, 1 에서 10 까지 고정됨. |
exposureDuration | number | 150 | 더 이상 사용되지 않습니다. viewportContentUpdated.exposureDuration를 사용하십시오. |
debounceTime | number | 해당 없음 | 더 이상 사용되지 않습니다. 영향을 주지 않습니다. |
FrustrationInteractionsOptions
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
rageClicks | boolean | { cssSelectorAllowlist?: string[] } | On, 모든 요소 | 1초에 50픽셀 내에서 4번의 클릭이 발생합니다. |
deadClicks | boolean | { cssSelectorAllowlist?: string[] } | On, DEFAULT_DEAD_CLICK_ALLOWLIST | 3초 내에 DOM 또는 URL이 변경되지 않은 상태에서 클릭합니다. |
errorClicks | boolean | { cssSelectorAllowlist?: string[] } | Off. 켜진 경우: DEFAULT_ERROR_CLICK_ALLOWLIST | 클릭 후 2초 내에 오류 발생. |
thrashedCursor | boolean | { directionChanges?: number; threshold?: number } | Off. 켜진 경우: directionChanges: 20 (최소 5), threshold: 2000 ms (최대 4000). | 포인터 방향이 신속하게 변경됩니다. X축 및 Y축 변경 사항은 별도로 계산됩니다. |
pageUrlAllowlist | (string | RegExp)[] | 모든 페이지 | 추적이 실행되는 페이지 |
pageUrlExcludelist | (string | RegExp)[] | 없음 | 추적이 실행되지 않는 페이지입니다. |
shouldTrackEventResolver | (actionType, element) => boolean | undefined | 요소별 결정. 허용 목록을 재정의합니다. |
dataAttributePrefix | string | "data-amp-track-" | 캡처할 data-속성의 접두사입니다. |
maskTextRegex | (RegExp | { pattern: string; description: string })[] | 없음 | 마스킹할 추가 패턴. |
네트워크추적 옵션
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
ignoreAmplitudeRequests | boolean | true | Amplitude에 대한 요청을 건너뜁니다. |
ignoreHosts | string[] | [] | 건너뛰는 호스트입니다. *와일드카드를 지원합니다. |
captureRules | NetworkCaptureRule[] | 하나의 규칙: 모든 URL, 상태 500-599 | 규칙은 마지막에서 처음으로 확인됩니다. |
각 항목은 NetworkCaptureRule다음을 허용합니다.
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
urls | (string | RegExp)[] | 모든 URL | 일치할 URL. *를 지원합니다. hosts보다 우선합니다. |
hosts | string[] | 모든 호스트 | 일치하는 호스트입니다. *를 지원합니다. 새 규칙에 대해 urls사용합니다. |
methods | string[] | 모든 메서드 | 일치할 HTTP 메소드입니다. |
statusCodeRange | string | "500-599" | "0,400-599"쉼표로 구분된 코드 및 범위(예: ). |
requestHeaders, responseHeaders | boolean | string[] | false | true 는 고정된 비민감한 헤더 목록을 캡처합니다. 배열은 명명된 헤더를 캡처합니다. |
requestBody, responseBody | { allowlist?: string[]; excludelist?: string[] } | 아무것도 캡처되지 않음 | JSON 포인터는 캡처 및 제거를 위한 것입니다. blocklist는 excludelist의 사용되지 않는 별칭입니다. |
Amplitude는 BrowserOptions의 최상위 수준에서 networkTrackingOptions을(를) 더 이상 사용하지 않습니다. autocapture.networkTracking를 사용하십시오.
WebVitalsOptions
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
reportSoftNav | boolean | false | 또한 Soft Navigations API를 사용하는 브라우저에서 소프트 탐색에 대한 웹 비탈을 보고합니다. 실험적 기능. |
PerformanceTrackingOptions
| 키 | 유형 | 기본값 | 설명 |
|---|---|---|---|
mainThreadBlock | boolean | { durationThreshold?: number } | 꺼짐. performanceTracking: true을(를) 사용하면 켭니다.durationThreshold: 100 | 최소 밀리초 단위의 메인 durationThreshold스레드 블록을 보고합니다. |
pageUrlAllowlist | (string | RegExp)[] | 모든 페이지 | 추적이 실행되는 페이지 |
pageUrlExcludelist | (string | RegExp)[] | 없음 | 추적이 실행되지 않는 페이지입니다. |
이 내용이 도움이 되었나요?
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.