Browser SDK 2のインストルメントと設定

このガイドでは、Get started後のBrowser SDK 2の使用方法について説明します。独自のイベントの追跡、IDとセッションの管理、Autocapture機能の選択、イベントのAmplitudeへの到達方法の制御などです。 正確なシグニチャとすべてのオプションについては、リファレンスを参照してください。 機能が追加または変更されたリリースを確認するには、Browser SDK 2のリリースノートを参照してください。

イベントを追跡

Browser SDK 2は、カスタムイベント、ユーザープロパティ、グループメンバーシップ、グループプロパティ、収益という5種類のデータを送信します。 それぞれには独自のメソッドがあり、各メソッドは{ promise }を返します。このメソッドはアップロード試行後に解決されます。 トラッキングプランで定義されたイベントには、これらのメソッドを使用してください。ページビュー、クリック、フォームインタラクション、およびSDKがコードなしで収集できるその他のイベントについては、Autocaptureを参照してください。

カスタムイベントを追跡する

イベント名を渡します。オプションで、イベントプロパティのオブジェクトを渡します。

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オブジェクトを渡します。 このフォームでは、HTTP V2 APIで受け入れ可能groupsな、 、 time、 app_version、 などのすべてのフィールドを受け入れますinsert_id。

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

同じイベントが2回送信される可能性がある場合(たとえば、独自のコードから再試行された場合など)insert_idに設定します。Amplitudeは、同じ「insert_id」insert_idおよび「event_id」を持つ2番目のイベントをdevice_id7日以内の期間で無視します。

1つのイベントのIDを上書きする

3番目の引数であるイベントオプションに、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はイベントを約1秒間に1回バッチでアップロードします。 コードがtrack()の直後にページを離れる場合は、まず promise を待機してください:

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

デフォルトのfetchトランスポートはすでにkeepaliveでを送信するため、ほとんどのイベントは待機しなくてもナビゲーションをまたいで維持されます。次のページが読み込まれる前にイベントが到着する必要がある場合は、待機してください。アンロード動作の詳細については、データ配信を参照してください。

ユーザープロパティを設定する

ユーザープロパティはユーザーを記述し、変更されるまで、以降の各イベントに関連付けられたままです。 Identifyオブジェクトを作成し、1 つ以上の操作を追加して、それを渡します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オブジェクトごとに1つの操作にのみ表示されます。SDKは同じキーに対する2番目の操作を黙認的に無視するため、競合する操作を2つのidentify()呼び出しで分割します。

初期化の一環としてユーザープロパティを設定し、最初の自動キャプチャイベントの前に適用されるようにするには、Identifyオブジェクトを渡init()します。

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

SDKは、新しいセッションが開始されるたびに、セッションの開始イベントの前にこのidentifyを送信します。このidentifyオプションには、Browser SDK 2.25.0以降が必要です。

ユーザーをグループに割り当てる

グループを使用すると、アカウントまたは組織レベルで行動を分析できます。 グループ分析には、Accountsアドオンが必要です。

setGroup() は、現在のユーザーを、1つ以上のタイプのグループに割り当てます。 この割り当ては、ユーザープロパティのようにユーザーに永続化されます。

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

ユーザーのグループを変更することなく、1つのイベントのみをグループに関連付けるには、そのイベントに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()を呼び出した場合は、その呼び出しによってtotalが直接設定されます。quantityはデフォルトで1であり、setQuantity()は0以下の値を無視します。setPrice()は、例えば払い戻しのために負の値を受け入れます。収益の検証には setRevenueType()と setReceiptSig()が必要です。 すべての設定値について、APIリファレンスのRevenueに移動してください。

Amplitudeは、currencyを設定した場合にのみ、収益をプロジェクトの通貨に変換します。 通貨コンバージョンの詳細と収益イベントの設定については、収益の追跡を参照してください。

収益データを最大限に活用するには、product配列メソッドを使用してプロダクトを追跡することもできます。

ビデオ再生を追跡

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();
  }
}

1回のtrackVideo()呼び出しによるすべてのイベントには、同じview_session_id(SDKが生成するUUID)と、お客様のextraEventPropertiesプラスが含まれます。trackVideo()は、プレーヤーにアタッチできない場合、関数ではなくErrorを返します。

イベントを複数のプロジェクトに送信する

各Amplitudeプロジェクトには独自のAPIキーがあります。 2つのプロジェクトに送信するには、createInstance()を使用して2番目のインスタンスを作成し、別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クッキーを共有しているため、各プロジェクトに独自のキーを割り当てます。

IDとセッション

Browser SDK 2は、すべてのイベントに3つの識別子を割り当てます:デバイスID、オプションのユーザーID、セッションID。Amplitudeはこれらを使用して、イベントをユーザーとセッションにマージします。SDKは、これら3つすべてとオプトアウトフラグを、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. 最後のイベントが期間内であった場合sessionTimeoutのAMP_クッキー。
  5. Date.now()。

SDKは、ampTimestampパラメータが存在し、かつ現在の時刻より前の場合、URLパラメータを無視します。ドメイン間でのユーザーの追跡に移動します。

ユーザーIDを設定する

ユーザーがサインインしたときにsetUserId()呼び出してください。データベースIDなど、システムからの安定した一意の識別子を使用してください。 メールアドレスが変更される可能性がある場合は、使用しないでください。

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

新しいユーザーIDは、以降のイベントごとに適用され、クッキー内に残ります。 ユーザーIDとデバイスIDは5文字以上である必要があります。そうでない場合、Amplitudeはイベントを拒否します。 より短いIDを許可するには、minIdLength設定を行ってくださいinit()。

ページの読み込み時にユーザーIDがわかっている場合は、代わりにそれを渡します。そうすれば、最初の自動キャプチャされたイベントにそのIDが伝送されます:init()

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

ユーザーがログアウトしたときにIDをリセットする

ユーザーがサインアウトしたときにreset()呼び出してください。この操作により、ユーザーIDを設定し、新しいデバイスIDを生成するため、このブラウザ上でのその後のアクティビティは、サインアウト済みユーザーにundefinedマージされません。

ts
amplitude.reset();

reset()新しいセッションを開始したり、Amplitudeのサーバー上のユーザープロパティをクリアしたり、オプトアウトを変更したりすることはありません。プラグインは、onReset()フックを通じてそれに反応できます。

デバイスIDを設定する

SDKはデバイスIDとしてランダムなUUIDを生成します。サーバーやモバイルアプリと共有されている場合など、安定した匿名識別子がすでに存在する場合にのみ、独自の識別子を設定します。

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

デバイスごとに一意で、長さが 5 文字以上の値を使用します。 同じデバイスIDを持つ2つのブラウザがAmplitudeの1つのユーザーに統合されます。

IDの読み取りと更新を同時に行う

getIdentity() は、現在のデバイスID、ユーザーID、およびSDKがこのページロードで追跡したユーザープロパティを返します。 Browser SDK 2.18.0以降が必要です。

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

setIdentity() は、3つの任意の組み合わせを更新します。 userPropertiesを含めると、SDKは$set各キーを特定の値に設定する$identifyイベントを送信します。setIdentity()にはBrowser 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のサーバーからユーザープロパティを読み取ることはありません。

セッションの仕組み

セッションは、ユーザーが1回の訪問でトリガーするイベントをグループ化します。 その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を新しいセッションに置き換えます。setSessionId()は、IDが現在のセッションIDと等しい場合、何も行いません。

ドメイン間でのユーザーの追跡

このAMP_クッキーは、www.example.com1つの登録可能なドメインとそのサブドメインを対象とapp.example.comしています。2つの異なるドメイン間で1つの匿名ユーザーとセッションを保持するにはexample.com、example-shop.comリンクURL内の識別子を渡します。ampDeviceIdおよびampSessionIdパラメータには、Browser 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は、現在ampTimestamp時刻より後の場合ampDeviceIdにampSessionIdのみ使用されます。ampTimestampがない場合、パラメータは有効期限切れになりません。そのため、共有リンクまたはブックマークされたリンクは、関連性のない訪問者を1つのデバイスにマージすることができます。ampTimestampには、Browser SDK 2.21.1以降が必要です。

ユーザーを追跡から除外する

setOptOut(true) SDKがこのブラウザのイベントを追跡またはアップロードすることを停止します。 この設定はAMP_クッキーに残ります。

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

オプトアウトが有効になっている間:

  • すべてのトラッキング呼び出しは、code 0と Event skipped due to optOut configを使用して即座に解決されます。
  • SDKはセッションを開始しません。init()オプトアウト状態で実行した場合、SDKはセッションを延期し、呼び出したときにセッションを開始しますsetOptOut(false)。
  • ページビューとアトリビューション追跡は、オプトアウトがオフになると開始されます。

ユーザーの同意を得るまでオプトアウト状態で開始するには、optOut: trueにinit()を渡します。同意バナー、初期化の遅延、クッキーのないストレージについては、クッキーと同意管理を参照してください。

SDKがIDを保存する場所を選択する

identityStorageSDKがデバイスID、ユーザーID、セッションID、オプトアウトフラグを保持する場所を制御します。

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

デフォルトでは、SDKは可能な限り最上位のドメイン(例:.example.com)にCookieを書き込むため、サブドメイン間でIDが共有されます。各レベルでAMP_TLDTESTクッキーを書き込み、削除することで、そのドメインを検出します。 ドメインを固定したり、他のクッキー属性を変更したりするには、cookieOptionsを設定します。 クッキーオプションに移動します。

自動キャプチャ

Autocaptureは、Browser SDK 2がインストール時にコードなしinit()で一般的なブラウザイベントを追跡するためにインストールする一連のプラグインです。これらはautocaptureオプションで制御でき、Amplitudeプロジェクトのリモート設定によって機能ごとに上書きできます。一般的な紹介については、Autocaptureを参照してください。

開始点を選択する

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

Chrome拡張機能では、SDKはデフォルト設定をオフにします。 各機能を true に設定します。このデフォルトは2.42.1で変更されました。

autocaptureは、非推奨の defaultTrackingオプションを置き換えます。両方を設定した場合、autocaptureが優先されます。

機能とイベント

すべてのサブオプションとデフォルトについては、設定リファレンスの Autocapture オプションを参照してください。

リモート設定はローカル設定を上書きします

デフォルトでは、プラグインをインストールする前に、init()Amplitudeからプロジェクトのリモート設定を取得します。 リモート設定を編集するには、_データ > 設定 > Autocapture_で行います。 リモート設定で設定された各機能について、その値はお客様の設定した値に置き換えられます。設定されていない機能は、ローカル値を保持します。 リモート設定には、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.comEUの場合は)に移動します。SDKはブラウザにレスポンスをキャッシュし、キャッシュまたはネットワークのいずれか先に到着したものを適用します。 広告ブロッカーまたはコンテンツセキュリティポリシーがリクエストをブロックした場合、SDKはキャッシュされたコピーを使用します。または、キャッシュが存在しない場合にはローカル設定を使用します。 独自のサーバー経由でルーティングするには、remoteConfig.serverUrl(Browser SDK 2.28.0以降)を設定します。

マーケティング アトリビューション

アトリビューションは、ページがロードされると、UTMパラメータ、クリックID、リファラーを読み取ります。 それは2つの独立した方法でそれらを記録し、これらはattribution.trackingMethodによって制御されます。両方ともデフォルトで実行されます。 このeventPropertyメソッドにはBrowser 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(または{ condition: "always" })に設定すると常にこれらを無視するか、URLにUTMパラメータやクリックIDがない場合にのみ無視するように{ condition: "ifEmptyCampaign" }設定します。Browser SDK 2.36.0以降が必要です。
  • initialEmptyValue は、キャンペーン値を持たないinitial_*プロパティの値です。 デフォルトは "EMPTY" です。
  • resetSessionOnNewCampaignキャンペーンが変更されると、新しいセッションが開始されます。

fallbackAttributionEvent はトラッキングにeventPropertyのみ適用されます。 すべてのページビューで[Amplitude] Attributionイベントが送信されるように設定すれば、ユーザーが他のイベントをトリガーしなかった場合でもキャンペーンデータが到着trueします。

シングルページアプリはキャンペーンのコンテキストを失います

シングルページアプリでは、最初のロード後にURLが変更されず、多くの場合、ルーターがクエリ文字列を削除します。document.referrer2つの結果:

  • userProperty トラッキングは、期間中にのみキャンペーンを読み取りますinit()。 pushState以降に表示されるキャンペーンでは、ユーザープロパティは更新されません。
  • eventProperty トラッキングは、各ナビゲーションのキャンペーンを置き換えます。 ユーザーが /?utm_source=newsletterから/pricing に移動した後、それ以降のイベントに utm_sourceはありませんが、オリジナルのreferrer は保持されます。

ルーターがURLを書き換える前にSDKを初期化し、キャンペーンパラメータをサーバー側のリダイレクトに設定したままにしてください。 ランディングページの後にリファラーを削除するには、エンリッチメントプラグインを追加します。

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イベントを通じて変更された際(back、forward、hashの変更時)に送信を行います。history.replaceState()これらはページビューをトリガーしません。

マルチステップフォーム

URLを変更することなくその場で更新されるマルチステップフォームは、1つのページビューを生成します。各ステップを追跡するには、Google Tag Managerなどを使用して、各ステップのURLにハッシュを追加します。

各ページビューには以下が含まれます:

オプション:

  • trackOn ページビューを送信するタイミングを制御します。 これを省略して、ロードとURLの変更ごとに送信します。 アトリビューションがキャンペーンを送信する場合にのみページビューを送信するように"attribution"設定します。 truesendを返す関数を設定します。
  • trackHistoryChanges どのURLの変更がカウントされるかを制御します。 デフォルトでは、URLに任意の変更が発生したときに、クエリ文字列とハッシュを含むページビューが送信されます。 同じオリジンとパスを保つ変更を無視するように"pathOnly"設定します。
  • eventType イベントの名前を変更します。
ts
amplitude.init("YOUR_API_KEY", {
  autocapture: {
    pageViews: {
      trackOn: () => location.pathname.startsWith("/app"),
      trackHistoryChanges: "pathOnly",
    },
  },
});

ページビューイベントに独自のプロパティを追加するには、エンリッチメントプラグインを使用します。 動作する例については、GitHub上のpage-view-tracking-enrichmentを参照してください。

単一ページアプリのページタイトル

SDKは、document.title返されたpushState()直後に読み取ります。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は実行されます。どの送信をカウントするかを決定するには、pass 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を送信します。これは、load後に追加されたリンクも監視します。

プロパティ:[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エンリッチメントプラグインを参照してください。Browser SDK 2.22.0 以降が必要であり、Browser SDK 2.29.0 ではデフォルトが on に変更されています。

Autocaptureをオフにしても、このプラグインを自分で追加できます:

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 を送信します。ビジュアルラベル付けとゾーニングインサイトは、これらのイベントに依存しています。 収集されるデータとテキストマスキングの仕組みについては、Autocaptureのプライバシーとセキュリティを参照してください。

デフォルトでは、SDKはa、button、input、select、textarea、label、video、audio、[contenteditable="true"]、[data-amp-default-track]、および.amp-default-trackでのクリックと変更を追跡します。また、クリックによってDOMが変更されるか、ナビゲーションが発生する場合、div、span、およびh1からh6までのクリックも追跡します。

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_ALLOWLIST を広げます。amplitude.Types.DEFAULT_CSS_SELECTOR_ALLOWLISTを@amplitude/analytics-browserからインポートしてください。@amplitude/plugin-autocapture-browserはそれをエクスポートしません。
  • actionClickAllowlist は、ページを変更するクリックの、div、span、および見出しリストを置き換えます。 [] を設定して cssSelectorAllowlist を絞り込めば、セレクターのみが有効になります。
  • pageUrlAllowlist およびpageUrlExcludelistページURLごとにトラッキングを制限します。 除外リストが優先されます。
  • shouldTrackEventResolver は要素ごとに決定します。 このフィールドを設定すると、SDKは許可リストを無視します。
  • data- は、一致するdataAttributePrefix属性をプロパティとしてキャプチャします。 デフォルトはdata-amp-track-なので、data-amp-track-plan="pro"はplanプロパティになります。
  • maskTextRegex SDKの組み込みマスク機能に加えて、パターンに一致するテキストをマスクします。
  • shadowDomEnabled (experimental)は、オープンシャドウルート内のインタラクションを、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 レイジクリックとデッドクリックを有効にします。 エラークリックとスラッシングカーソルは、個別にオンにするまでオフになっています。フラストレーションのインタラクションには、Software Development Kit (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 },
    },
  },
});

Dead clickおよびerror clickcssSelectorAllowlistでは、interactive-element listsDEFAULT_DEAD_CLICK_ALLOWLISTを使用します。ただし、設定しない限り、DEFAULT_ERROR_CLICK_ALLOWLIST上記が使用されます。セレクターについては、GitHubのfrustration-interactions.tsを参照してください。

各シグナルは、 pageUrlAllowlist、 pageUrlExcludelist、 shouldTrackEventResolver、dataAttributePrefix および frustrationInteractionsをmaskTextRegex レベルでも受け入れます。

ネットワーク追跡

ネットワークトラッキング[Amplitude] Network Requestは、 fetchおよび XMLHttpRequest呼び出しを送信します。デフォルトでは、599ステータスが 500から までのレスポンスのみをキャプチャし、Amplitudeへのリクエストは無視されます。Browser 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 (string または RegExp、hosts をサポート) または古い形式の* をサポートしています。すべてのURLに一致するように、両方を省略します。
  • methods、["POST", "PUT"]たとえば。デフォルト:すべて。
  • statusCodeRange、コードと範囲のコンマ区切りリスト。 デフォルト:"500-599". 0は、応答なしで失敗したリクエストに一致します。
  • requestHeaders と responseHeaders: true は、content-type や cache-control といった機密性のないヘッダーの固定セットをキャプチャします。配列は、リストした名前を正確にキャプチャします。
  • requestBody およびresponseBody: JSONボディのみ。allowlist保持するJSONポインタをリストします(*1つのキー、**任意の深さと一致します)。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 Vitalは、タブが最初に非表示になったときに、ページ読み込みごとに1つの[Amplitude] Web Vitalsイベントを送信します。 ブラウザが報告した場合、[Amplitude] LCP、[Amplitude] FCP、[Amplitude] INP、[Amplitude] CLS、および[Amplitude] TTFBにプラスして、ページのドメイン、場所、パス、タイトル、URLが含まれます。メトリクスの定義については、web.devを参照してください:LCP、FCP、INP、CLS、TTFB。 Browser SDK 2.20.0以降が必要です。

単一ページのアプリでは、ソフトナビゲーションごとに1つのイベントも送信するように、webVitals: { reportSoftNav: true }(experimental)を設定します。 これには、Soft Navigations API(Chromium 151以降)が必要です。 他のブラウザは初期ロードのみをレポートします。

パフォーマンスの追跡

パフォーマンス追跡は、メインスレッドが少なくとも100ミリ秒間ビジー状態にある場合に[Amplitude] Main Thread Block送信されます。 この方法では、利用可能な場合に Long Animation Frames APIを使用し、Long Tasksにフォールバックします。autocapture: true本機能はこれを自動的に有効にはしません。Browser SDK 2.41.0以降が必要です。

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

データ配信

Browser SDK 2は、各イベントを追跡するたびに送信するわけではありません。イベントをキューに保存しlocalStorage、バッチでアップロードし、失敗したアップロードを再試行します。このセクションでは、その動作を変更する各設定について説明します。 デフォルトの設定は、ほとんどのサイトに適しています。ナビゲーション時にイベントが欠落している場合、ネットワークがAmplitudeのドメインをブロックしている場合、または特定のデータ領域が必要な場合に変更してください。

SDKがイベントをアップロードする方法

  1. track()イベントをメモリ内キューに追加し、そのキューを、APIキーの最初の10文字をプラスしたAMP_unsent_配下のlocalStorageに書き込みます。
  2. flushIntervalMillis(デフォルト1000)最初のイベントがキューに入った後、SDKはキュー全体を送信し、最大flushQueueSize(デフォルト30)イベントのリクエストに分割します。イベントの順序を維持するため、リクエストは一度に1つずつ送信されます。キューがいっぱいになっても、早期アップロードはトリガーされません。
  3. 200レスポンスが発生すると、SDKはイベントをキューとストレージから削除します。
  4. 障害が発生すると、SDKは再試行します。 ネットワークエラーとレスポンスの後、待ち時間は5xx試行されるごとに1秒ずつ長くなります。 スロットリングされたイベント (429)は、30秒待機します。 A413を半分にします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は、より多くの、より小さなリクエストを送信します。
  • より大きなリクエスト:1回のフラッシュに30を超えるイベントが頻繁に含まれる場合にflushQueueSize値を上げます。各リクエストにはより多くのイベントが含まれるため、ビジーキューに必要なリクエスト数は少なくなります。 リクエストが大きすぎる場合、AmplitudeはflushQueueSizeを返し、SDKは413半分になります。
  • 高トラフィックのソース:より高いレート制限を持つBatch Event Upload APIへ送信するようにuseBatch: true設定します。リクエスト数を減らすことはありません。

現在のバンドルサイズについては、npmパッケージページまたはBundlePhobiaを確認してください。

データ地域を選択する

Amplitude組織のデータセンターserverZoneに設定します。 デフォルトは US です。

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

Batch Event Upload APIに切り替わります(/batch)。このAPIは、高トラフィックのソースに対してより高いレート制限を提供します。useBatch: trueSDKがブラウザでイベントをバッチ処理する方法は変更されません。

コンテンツセキュリティポリシーでAmplitudeを許可する

サイトでContent-Security-Policyヘッダーを送信する場合は、Amplitudeのドメインを許可します:

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

スクリプトローダーを使用してAmplitudeのCDNからSDKをロードする場合にのみscript-src必要です。connect-srcイベントのアップロード、リモート設定、SDK診断を扱います。すべてのトラフィックを独自のドメイン経由でプロキシする場合は、代わりにそのドメインを許可してください。

ページがアンロードされたときにイベントを送信する

ブラウザはページがアンロードされると送信中リクエストをキャンセルします。そのため、リダイレクトするログインなど、ナビゲーションの直前に追跡されたイベントが失われる可能性があります。

デフォルトのfetchトランスポートkeepaliveは、ボディが 16 KB 以下のリクエストに設定するため、ブラウザはページがアンロードされた後にリクエストを終了します。Keepaliveは、圧縮、カスタムヘッダー、レスポンス、再試行を保持します。 ブラウザは、ページ上のすべてのフライト中のリクエストに対して64KBのキープアライブ予算を共有します。そのため、SDKはキープアライブ予算なしでより大きなボディを送信します。SDKは、圧縮後のボディを測定します。予算がいっぱいであることを理由にブラウザがキープアライブリクエストを拒否した場合、SDKは次のフラッシュ時に再試行します。この機能をサポートしていないブラウザは、このフラグをkeepalive無視し、通常のリクエストを送信します。

ボディが16KBを超える場合、ページが非表示になるときにbeacontransportに切り替えます:

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

sendBeaconリクエストをブラウザに渡し、すぐに制御を返します。この方法には次の制限があります。

  • 応答がないため、SDKは障害を再試行できません。 これは、ブラウザが受け入れたリクエストを成功とみなします。
  • カスタムヘッダーがないため、圧縮はありません。
  • リクエスト間の順序付け保証はありません。

キープアライブをオフにするには(たとえばキープアライブ固有の障害をデバッグする場合など)、以下を設定します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各アップロード(fetchおよびxhr)にHTTPヘッダーを追加します。SDKは常にContent-Typeと Acceptを設定しており、ヘッダーはこれらを置き換えることはできません。 カスタムヘッダーはリクエストを単純でないものにするため、サーバーはCORSプリフライトに応答する必要があります。Amplitudeのエンドポイントはこれに対応しています。プロキシを確認してください。 Browser SDK 2.33.0以降が必要です。
  • referrerPolicy アップロードのリファラーポリシーを設定します。fetch Browser SDK 2.44.0以降が必要です。
  • enableKeepalive キープアライブをオンまたはオフにしますfetch。 デフォルトではオンになっています。このデフォルトは2.43.0で変更されました。

init()後のトランスポートを変更するには、setTransport()を呼び出します。

リクエストボディを圧縮する

ブラウザがCompressionStreamをサポートしている場合、SDKは2KB以上のリクエストボディをgzip圧縮し、Content-Encoding: gzipに設定します。これはAmplitudeのエンドポイントでは常にオンになっています。 カスタム の場合、サーバーが gzip ボディを受け入れる必要があるため、enableRequestBodyCompression: trueを設定しない限り無効になります。serverUrl圧縮にはBrowser SDK 2.36.0以降が必要です。Amplitudeのエンドポイントでは、2.42.0からデフォルトの設定値がonに変更されました。

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はリモート設定を個別に取得します。

プロキシは以下である必要があります:

  • プリフライトリクエストに応答し、サイトのOPTIONS を返します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 の後にキューをアップロードします。Browser SDK 2.4.0以降が必要です。

数ミリ秒を大幅に上回る数値にflushIntervalMillis保ちます。 1 のような値の場合、アップロードは onlineイベントが発行されたほぼ瞬間(多くの場合、接続が確立される前)から開始され、Chromeが ERR_NETWORK_CHANGEDを使用してアップロードを失敗させる可能性があります。SDKは失敗したアップロードを再試行します。

接続を自分で制御するには、たとえばonLineWebビューで誤ってレポートが発生する場合など、組み込みのチェックをオフにします。

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

OfflineDisabledSDKは常にアップロードを試み、再試行に依存します。

未送信のイベントを別の場所に保存する

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(),
  },
});

メモリ専用ストレージの場合、ページがアンロードされた時点でキューに残っているイベントは失われます。アイデンティティストレージは別になっています。「SDKがIDを保存する場所を選択 (Choose where the SDK stores identity)」へ移動します。

これは役に立ちましたか?

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.

このページでは