Browser SDK 2リファレンス
このリファレンスでは、@amplitude/analytics-browserのすべてのパブリックエクスポートと、init()に渡すことができるすべてのオプションをバージョン2.48.1と照合して検証したことを文書化しています。 スクリプトローダーを使用すると、同じメンバーがグローバルamplitudeオブジェクトで使用できます。 オプションについては、設定オプションを参照してください。 機能が追加または変更されたリリースを確認するには、Browser SDK 2のリリースノートを参照してください。
import * as amplitude from "@amplitude/analytics-browser";
トップレベルの関数はデフォルトのインスタンスで動作します。 createInstance()の各インスタンスには同じメソッドがあります。
戻り値
非同期動作を実行するメソッドは、AmplitudeReturn<T>を返します。これは、1つのプロパティを持つオブジェクトですpromise。 Awaitpromise(待機)であり、戻り値自体ではありません。
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()行われた呼び出しはキューで待機し、その後、順次実行されます。それらのPromiseは、処理が終了し、アップロードが完了したinit()後に解決されます。
セットアップ
init
インスタンスを初期化します。 インスタンスごとに1回呼び出してください。終了後に再びを呼び出すと、追加したプラグインを含むすべてのプラグインが破棄され、最初からやり直されます。
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 | オプションです。設定リファレンスを参照してください。 |
promiseSDKがリモート設定を取得し、プラグインをインストールして、キューに入れられた呼び出しを実行した後、解決されます。
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)インスタンスも登録されるため、SDKがロードされる前に行われた呼び出しはname、そのインスタンスに到達します。
追加する
プラグインを追加します。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 | イベント名、または BaseEvent オブジェクト(event_type とその他のイベントフィールドを含む)。 |
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
ユーザープロパティを更新する$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
groupssetを使用して$identifyイベントを送信することにより、現在のユーザーをグループに割り当てます。
setGroup(groupType: string, groupName: string | string[], eventOptions?: EventOptions): AmplitudeReturn<Result>
amplitude.setGroup("company", "Acme Inc");
groupIdentify
1つのグループのプロパティを更新する$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() は Browser 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
オプトアウトの読み取りまたは設定を行います。オプトアウトが有効な間true、SDK はすべてのイベントをドロップします。この値はIDストレージに保持されます。getOptOut() は Browser SDK 2.18.0 以降を必要とします。
getOptOut(): boolean | undefined
setOptOut(optOut: boolean): void
amplitude.setOptOut(true);
Identify
Identify は、identify() 、groupIdentify() 、およびidentify init オプションに対するユーザープロパティまたはグループプロパティ操作を構築します。各メソッドは同じオブジェクトを返すため、メソッドチェーンが可能です。各プロパティは、オブジェクトごとに1つの操作のみを実行できます。 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() | 該当なし | 操作オブジェクトを返します(例:{ $set: { plan: "pro" } })。 |
値は、文字列、数値、ブール値、配列、またはそれらの型のオブジェクトを受け入れます。
収益
revenue_amount イベントのプロパティを構築します。Revenue 各セッターは同じオブジェクトを返します。
const revenue = new amplitude.Revenue();
| メソッド | イベントプロパティ | デフォルト | 概要 |
|---|---|---|---|
setProductId(id: string) | $productId | "" | プロダクト識別子。 |
setPrice(price: number) | $price | 0 | 1つのアイテムの価格。 負の値である可能性があります。 |
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) | いいえ | プラグインのインストール時に一度実行されます。resolved BrowserConfigとインスタンスを受け取ります。 |
execute(event) | 送信先:はい | Beforeプラグインおよびenrichmentプラグインは、イベントを(変更される可能性がある状態で)返すか、またはnull破棄します。送信先プラグインはイベントを送信し、Resultを返します。 |
teardown() | いいえ | remove()~init()の際に実行され、~が再び実行されるときに実行されます。ここでリスナーを削除します。 |
flush() | いいえ | 送信先プラグインのみ。 amplitude.flush()で実行されます。 |
onIdentityChanged(identity) | いいえ | 、、setDeviceId()、setIdentity()、reset()、およびの後に実行setUserId()されますidentify()。 ベストエフォート。 |
onSessionIdChanged(sessionId) | いいえ | 新しいセッションの開始時に実行されます。 |
onOptOutChanged(optOut) | いいえ | setOptOut()値が変更されたときに実行されます。 |
onReset() | いいえ | reset()で実行されます。 |
各イベントについて、SDKはすべてのBeforeプラグインを実行し、次にすべてのenrichmentプラグイン、最後にすべての送信先プラグインを実行します。同じタイプのプラグインは、追加した順序で実行されます。 ~init()の前に追加されたプラグインは、組み込みの autocapture プラグインより先にインストールされるため、最初に実行されます。
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);
イベントを独自の endpoint に転送する送信先プラグイン:
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は、Page URL enrichmentやCustom enrichmentなどの既成のプラグインを公開しています。 詳細については、SDKプラグインを参照してください。
種類
amplitude.Types TypeScript の型と定数をエクスポートします(以下を含む):
| エクスポート | 概要 |
|---|---|
BrowserOptions | init()optionsオブジェクト。 |
BaseEvent, Event, EventOptions | イベントの型。 |
Result | トラッキング Promise の解決済み値。 |
Plugin、BeforePlugin、EnrichmentPlugin、DestinationPlugin | プラグインの型。 |
LogLevel | Enum:None、Error、Warn、Verbose、Debug。 |
OfflineDisabled | 接続検出をオフにするofflineオプションの値。 |
TransportType | "fetch" | "xhr" | "beacon". 列挙型ではなく、文字列型。 |
ServerZoneType | "US" | "EU". |
IdentityStorageType | "cookie" | "localStorage" | "sessionStorage" | "none". |
AutocaptureOptions, AttributionOptions, ElementInteractionsOptions | Autocaptureオプションの形状。 |
DEFAULT_CSS_SELECTOR_ALLOWLIST, DEFAULT_ACTION_CLICK_ALLOWLIST, DEFAULT_DATA_ATTRIBUTE_PREFIX | リストを拡張するための要素インタラクションのデフォルト設定。 |
連携エクスポート
これらのエクスポートは、他のAmplitudeパッケージにも存在します。 ほとんどのアプリでは、これらの設定は必要ありません。
| エクスポート | 目的 |
|---|---|
AmplitudeBrowser | Clientクラス。@amplitude/unifiedその上に構築されています。代わりにcreateInstance()を使用してください。 |
runQueuedFunctions | スクリプトローダーのスニペットによってキューに配置された呼び出しを再生します。 |
_setDiagnosticsSampleRate | 内部テストのみ。 予告なしに変更されることがあります。 |
設定オプション
このセクションでは、BrowserOptionsBrowser SDK 2.48.1時点におけるinit()、渡される設定オブジェクトのすべてのオプションを記載します。すべてのオプションはオプションです。 非推奨とマークされたオプションは引き続き機能します。
amplitude.init(apiKey: string, options?: BrowserOptions);
amplitude.init(apiKey: string, userId?: string, options?: BrowserOptions);
Identityとセッション
| オプション | タイプ | デフォルト | 概要 |
|---|---|---|---|
userId | string | undefined | すべてのイベントのユーザーID。 init()のuserId引数と同じです。 両方を渡した場合、引数が優先されます。 |
deviceId | string | URL、クッキー、または新しいUUIDから | すべてのイベントのデバイスID。 ampDeviceIdURLパラメータと格納値を上書きします。 |
sessionId | number | URL、Cookie、または Date.now() | セッションID。Unixタイムスタンプ(ミリ秒単位)。 このセッションをロード時に開始します。 |
sessionTimeout | number | 1800000(30分) | 非アクティブ状態(ミリ秒単位)。この期間の後、次のイベントが新しいセッションを開始します。 |
optOut | boolean | ストアド値、または false | trueの場合、SDKはすべてのイベントをドロップし、セッションを開始しません。 IDストレージに永続化します。 |
identify | Identify | undefined | SDKが各セッションの開始時、session_startの前に送信するIdentifyオブジェクト。2.25.0 以降が必要です。 |
identityStorage | "cookie" | "localStorage" | "sessionStorage" | "none" | "cookie" | SDKはデバイスID、ユーザーID、セッション状態、およびオプトアウトを永続化します。"none"メモリ内にこれらを保持します。 |
cookieOptions | CookieOptions | クッキーオプションを参照してください。 | アイデンティティクッキーとキャンペーンクッキーの属性。 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 | CookieDomain属性。 ホスト専用のCookie""に設定します。 |
cookieOptions.expiration | number | 365 | クッキーの有効期限(日単位)。 |
cookieOptions.sameSite | "Strict" | "Lax" | "None" | "Lax" | クッキーSameSite属性。"None"が必要ですsecure: true。 |
cookieOptions.secure | boolean | false | Secure属性を追加します。これにより、ブラウザはHTTPS経由でのみクッキーを送信します。 |
cookieOptions.upgrade | boolean | true | メンテナンスJavaScript SDK(amp_プレフィックス)によって設定されたCookieからIDを読み取り、削除します。 |
SDKは次のCookieを設定します:
| クッキー | 内容 |
|---|---|
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 | クッキーのサポートをテストし、init()クッキーのドメインを見つけるために、SDKが書き込みおよび削除する一時的なCookie |
データ収集
| オプション | タイプ | デフォルト | 概要 |
|---|---|---|---|
autocapture | boolean | AutocaptureOptions | デフォルトはon | 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 | プロジェクトのリモート設定からエンリッチメント関数を実行するカスタムエンリッチメントプラグインをインストールします。 試験的機能。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開始値。 |
Delivery
| オプション | タイプ | デフォルト | 概要 |
|---|---|---|---|
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 | SDK からnavigator.onLine管理されます。接続検出をオフ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 | 圧縮後に測定された、ボディが 16 KB 以下の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()します。 |
カスタム実装は、すべてのILoggerメソッドloggerProviderを実装する必要があります。この例では、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 は、false、true、またはこれらのキーを持つオブジェクトを受け入れます。 動作と例については、Autocaptureを参照してください。
| キー | タイプ | デフォルト | 概要 |
|---|---|---|---|
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 以降が必要です。 |
performanceTracking を除くすべてのキーが有効になります。autocapture: true 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"と同じ) | どのpushStateURLおよびpopstateURLの変更でページビューを送信するか。 |
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[] } | オン、すべての要素 | 1秒の期間内に50ピクセル以内での4回のクリック。 |
deadClicks | boolean | { cssSelectorAllowlist?: string[] } | オン、 DEFAULT_DEAD_CLICK_ALLOWLIST | 3秒の期間内にDOMまたはURLの変更を伴わないクリック。 |
errorClicks | boolean | { cssSelectorAllowlist?: string[] } | オフ。 オンになっている場合:DEFAULT_ERROR_CLICK_ALLOWLIST | 2秒以内の期間にエラーが続くクリック。 |
thrashedCursor | boolean | { directionChanges?: number; threshold?: number } | オフ。 オンになっている場合:directionChanges: 20(最小5)、threshold: 2000(最大4000)ms。 | 急速なポインタ方向の変更。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[] | 1つのルール:すべての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.