ブラウザ 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",
});

デバッグ

SDKがコンソールに出力するログのレベルを、以下のlogLevel設定で制御します：

パラメータ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を「Debug」に設定することでデバッグモードを有効にします。次に例を示します：

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

デフォルトのロガーでは、SDKのパブリックメソッドを呼び出すと、SDKは開発者コンソールに以下の追加の関数コンテキスト情報を出力します：

• type：このコンテキストのカテゴリーです。たとえば、「パブリックメソッドの呼び出し」などです。
• name：呼び出された関数の名前です。たとえば「追跡する」などです。
• 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モードを使用します。
• 大量のイベントトラッキングでHTTPリクエストの数を減らすには、useBatchモードを有効にします。

自動キャプチャ（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がキャンペーンアトリビューションデータを保持する方法を選択できます。

• ユーザープロパティ追跡（デフォルト）：ファーストタッチおよびマルチタッチアトリビューションのイベントを識別することにより、キャンペーンのパラメータをユーザープロパティとして追跡します。
• イベントプロパティの追跡: キャンペーンのパラメータを各イベントのプロパティに結びつけることで、イベントレベルのアトリビューションを細かく把握できます。 永続化されたプロパティと一緒に使用すると、さまざまなアトリビューションモデルを選択できます。

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 などの履歴 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に使用します。 document.referrerとlocation.hostnameが同じドメインに解決される場合、SDKはリファラーを内部リファラーとして扱います。

• excludeInternalReferrers: true``excludeInternalReferrers: { condition: 'always' }常に除外：内部リファラーのキャンペーン情報を一切追跡しないようにするには、またはを設定してください。
• キャンペーンが空の場合のみ除外: UTM パラメータやクリック ID excludeInternalReferrers: { condition: 'ifEmptyCampaign' }がない場合、内部リファラーのキャンペーンの追跡をスキップするように設定します。 ユーザーがUTMまたはクリックIDを使用して内部ページから到着した場合でも、Amplitudeは引き続きキャンペーンデータを追跡します（excludeReferrersがリファラーを除外していない場合）。

リファラーを除外する

config.autocapture.attribution.excludeReferrersのデフォルト値は、Cookieストレージが有効になっている最上位ドメインです。 たとえば、https://www.docs.developers.amplitude.com/ で SDK を初期化した場合、SDK はまず amplitude.com をチェックします。 amplitude.comがCookieの保存を許可していない場合、SDKはdevelopers.amplitude.comとそれ以降のサブドメインをチェックします。 ドメインがCookieの保存を許可している場合、SDKはexcludeReferrersを、data.amplitude.comやanalytics.amplitude.comなどのamplitude.comのすべてのサブドメインからのトラッキングリファラーと一致して除外するRegExpオブジェクト/amplitude\.com$/に設定します。

リファラーをデフォルト設定から除外することに加えて、カスタム excludeReferrers を設定することで他のドメインを追加することもできます。 カスタム 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");
      },
    },
  },
});

ブラウザ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 は、ユーザーがフォーム要素と最初にやり取りしたタイミングを追跡します[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>

フォームインタラクション追跡を無効にする

フォームインタラクションの追跡を無効にするには、config.autocapture.formInteractionsをfalseに設定します。

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

コントロールフォーム送信追跡

Amplitudeが[Amplitude] Form Submittedイベントを追跡するタイミングを制御するには、shouldTrackSubmitコールバック付きのFormInteractionsOptionsオブジェクトを渡します。

デフォルトでは、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はデフォルトでファイルダウンロードイベントを追跡します。 SDKは、ユーザーがファイルにリンクされているアンカーや<a>タグをクリックした[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,
  },
});

要素のインタラクションを追跡する

エレメントインタラクショントラッキングを有効にすることで、ページ上のエレメントに対するクリックや変更をキャプチャできます。これはビジュアルラベリングに必要なものであり、ゾーニングインサイトを活用して定義済みのページ領域内のエンゲージメントを分析できます。 これらのイベントで収集されるデータについての詳細は、『自動キャプチャのプライバシーとセキュリティ』を参照してください。

config.autocapture.elementInteractionsをtrueに設定すると、要素のクリックと変更の追跡が有効になります。

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

要素のインタラクションに関する高度な設定

高度な設定を使用して、要素のインタラクション追跡を制御します。

たとえば、次のようにAmplitudeを設定することで、サイトのブログページにおいて、amp-trackingのあるクラスの要素に対するクリックのみをキャプチャするようにできます。：

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はこれらのイベントを次のように定義しています。

• 怒りのクリック:ユーザーが50ピクセル以内の同じ要素を1秒以内に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：エラーの種類（未検出の例外、コンソールエラー、未処理のPromise拒否のいずれか）。
• [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とフェッチのみ）。 デフォルトでは、amplitude.comドメインへのリクエストを除き、レスポンスコードが500-599の範囲にあるネットワークリクエストを追跡します。

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.blocklistおよびrequestBody.allowlistを設定することで、リクエスト本文の一部をキャプチャできます。

許可リストとブロックリストは、特定のフィールドをキャプチャする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,
  },
});

取得されたメトリック

ウェブバイタル自動キャプチャ機能は、以下のコアウェブバイタル指標をキャプチャします。

• 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は1つの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. Identifyオブジェクトを使用して呼び出しを行うようSDKに指示します。

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

このメソッドは、ユーザープロパティの値を1回だけ設定します。以降の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は新しい値を先頭に追加する前にそのプロパティを空のリストに初期化します。

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は新しい値を事後挿入する前にそのプロパティを空のリストに初期化します。ユーザープロパティに既存の値がある場合、このメソッドは動作しません。

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

Identify.remove

このメソッドは、ユーザープロパティに値が存在する場合に、その値をユーザープロパティから削除します。 削除は指定されたリストから既存の値を削除することを意味します。 ユーザープロパティに既存の値がある場合、このメソッドは動作しません。

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では、ユーザーをグループに割り当てたり、それらのグループに対して「ユニーク数による集計」などのクエリを実行したりすることができます。 グループの少なくとも1人のメンバーが特定のイベントを実行した場合、そのグループはカウントに含まれます。

たとえば、「orgId」を使用して、ユーザーが所属する組織に基づいてユーザーをグループ化したい場合などです。 Joeは'orgId' '10'に属し、Sueは'orgId' '15'に属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。

グループを設定する際には、groupTypeとgroupNameを定義してください。 前の例では、「orgId」はgroupTypeで、「10」と「15」はgroupNameの値です。 groupTypeのもう1つの例としては、「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 ${ IT } を使用して明示的に設定しない限り、ユーザーに永続することはありません。

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インターフェイスを組み合わせて使用することです。 収益インスタンスには各収益トランザクションが保存され、Amplitudeの「イベントセグメンテーション」や「レベニューLTV」チャートで使用されるいくつかの特別な収益プロパティ（revenueTypeやproductIdなど）を定義することができます。 これらの収益インスタンスオブジェクトをrevenue()に渡して、収益イベントとしてAmplitudeに送信します。 これにより、Amplitudeはプラットフォーム内の収益に関連するデータを自動的に表示できます。 これを使用して、アプリ内購入とアプリ内以外の購入の両方を追跡できます。

ユーザーからの収益を追跡するには、ユーザーが収益を生成するたびに、収益を呼び出します。 この例では、ユーザーはプロダクトを3ユニット3.99ドルで購入しました。

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

収益インターフェイス

収益オブジェクトは次のプロパティをサポートしています。 値を割り当てるには、対応するsetterメソッドを使用してください。

イベントバッファのフラッシュ

flushメソッドは、クライアントがバッファーされたイベントを即座に送信するようにトリガーします。

amplitude.flush();

デフォルトでは、ブラウザ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. deviceIdを新しいUUID値に設定します。

未定義の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 メソッドは、指定されたプラグイン名が IT 存在する場合、クライアントインスタンスからその名前を削除します。

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のパブリックメソッドを呼び出した際、デバッグに役立つ追加の関数コンテキスト情報が開発者コンソールに出力されます。
• AmplitudeはSDKの遅延初期化をサポートしています。 SDK は、初期化呼び出しの後、初期化前に追跡されたイベントをディスパッチします。 イベントを送信できないものの、ブラウザのコンソールにamplitude.init(API_KEY, 'USER_ID')と入力すると正常にイベントを送信できる場合は、コードベース内でamplitude.initの呼び出しがトリガーされていないか、初期化時に正しいAmplitudeインスタンスを使用していない可能性があります。 したがって、実装を確認してください。

ネットワークリクエスト

_[Inspect] > [Network]_タブを使用して、ページで行われたすべてのネットワークリクエストを表示します。Amplitudeリクエストを検索します。

応答コードを確認し、応答ペイロードが期待どおりであることを確認してください。

Instrumentation エクスプローラー Chrome 拡張機能

Amplitude Instrumentation エクスプローラーは、Google Chromeウェブストアで入手できる拡張機能です。この拡張機能は、ユーザーがトリガーする各 Amplitude イベントをキャプチャし、それを拡張機能のポップアップに表示します。 SDK がイベントを正常に送信したことを確認し、イベントペイロード内のコンテキストを確認してください。

一般的な問題

以下は、ブラウザSDKに固有の一般的な問題です。 より一般的な問題については、「SDKのトラブルシューティングとデバッグ」を参照してください。

広告ブロッカー

Ad Blocker イベントがドロップされる原因となる可能性があります。 以下のエラーは、トラッキングに影響があったことを示しています。 Ad Blockerスクリプトタグを使用してロードする場合、SDKスクリプトのロード中にコンソールまたはネットワークタブにエラーが表示されることがあります。 npm パッケージとともにロードされた場合、サーバーにイベントを送信しようとしたときにネットワークタブにエラーが発生する可能性があります。 エラーはブラウザによって異なる場合があります。

• Chrome（Ubuntu、MacOS） コンソール： error net::ERR_BLOCKED_BY_CLIENT ネットワーク：ステータス（ブロック：その他）
• Firefox（Ubuntu） コンソール：エラーテキストにブロック固有の情報が含まれていません ネットワーク：転送された列には、uBlockオリジンによってブロックされているプラグインの名前が含まれています
• Safari（MacOS） コンソール：エラーにはテキストが含まれています コンテンツブロッカーにより、フレーム ... は ... からリソースをロードできませんでした ネットワーク：ブロックされたリクエストはリストにないようです。 それらを表示できるかどうかは不明です。

Amplitudeは、この状況を回避するためにプロキシサーバーを使用することを推奨しています。

Cookie関連

以下は、SDKがCookieに保存する情報です。 つまり、Cookieを無効にしたり、プライベートモードのブラウザ、ウィンドウ、またはタブを使用したりといったクライアント側の動作は、Cookieに保存されたこれらの値の保持期間に影響を与えます。 これらの値が持続していない場合や、1 つずつ増加していない場合は、それが原因である可能性があります。

CORS

クロスオリジンリソース共有(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.

クロスオリジンリソース共有(CORS)は、悪意のあるサイトが権限なく他サイトのデータを読み取ることを防ぎます。このエラーメッセージは、アクセスしようとしているサーバーが、オリジンがリクエストされたリソースにアクセスすることを許可していないことを示しています。 これは、サーバーの応答にAccess-Control-Allow-Originヘッダーが不足しているためです。

• サーバーを制御できる場合は、サーバーのCORSポリシーを更新できます。サーバーの応答にAccess-Control-Allow-Originヘッダーを追加します。 これにより、オリジンがリクエストを行うことができます。 Access-Control-Allow-Originの値はすべてのオリジンを許可することにすることも、*ウェブページの特定の URL にすることもできます。
• サーバーを制御できない場合は、必要な CORS ヘッダーを追加するプロキシサーバーを設定できます。 ウェブページはプロキシにリクエストを送信し、プロキシが実際のサーバーにリクエストを送信します。 プロキシはレスポンスにAccess-Control-Allow-Originヘッダーを追加した後で、そのレスポンスをウェブページに返送します。

APIプロキシを設定済みで、選択したプラットフォーム上でそれに関連する設定上の問題に遭遇した場合、それはもはやSDKの問題ではなく、アプリケーションとサービスプロバイダー間の連携の問題です。

イベントが発生したが、ネットワークリクエストが発生しなかった

ロガーを「デバッグ」レベルに設定し、開発者コンソールにtrack呼び出しが表示されている場合、コードはそのtrack()メソッドを呼び出しています。Amplitude、Amplitude Instrumentation エクスプローラーChrome拡張機能、またはブラウザのネットワークリクエストタブに該当するイベントが表示されない場合、SDKはイベントをAmplitudeに送信していません。SDK は、呼び出しが成功するとイベントを発生させ、内部キューに格納しますが、これらのキューイングされたイベントが正常に送信されない場合があります。 track()これは、ブラウザが進行中のHTTPリクエストをキャンセルした場合に発生することがあります。 たとえば、ブラウザを閉じたり、ページを離れたりした場合などです。

これは、新しいページをただちにロードするログインイベントなど、リダイレクトやナビゲーションの直前にイベントが発生する場合に最もよく発生します。 この問題に対処するには、いくつかの方法があります。

1. デフォルトでは、fetchトランスポートはkeepaliveを使用してイベントを送信するため、ページがアンロードされた後もリクエストを完了させることができます。 これにより、最大16KBまでのリクエスト本文について、ほとんどのナビゲーションケースが自動的に処理されます。 キープアライブが無効になっていないこと、およびイベントバッチがサイズ制限内であることを確認してください。詳細については、キープアライブを使用したページナビゲーションの維持セクションを参照してください。
2. キープアライブ制限を超えるペイロードの場合、初期化時またはページ終了時にトランスポートをbeacon に設定してください。sendBeacon IT はバックグラウンドでイベントを送信しますが、4xx または 5xxなどのサーバー応答を返さないため、失敗しても再試行しません。詳細については、「sendBeacon」セクションを参照してください。
3. track()を同期処理にするには、呼び出しの前にawaitキーワードを追加してください。

高度なトピック

クロスドメイン追跡

2つの異なるドメインにわたって匿名の行動を追跡できます。 Amplitudeは、ドメイン間で渡される必要があるデバイスIDによって匿名ユーザーを識別します。 同じセッションを維持し、ユーザージャーニーを継続的に実行できるようにするには、セッションIDも他のドメインに渡します。

例えば：

• サイト 1：www.example.com
• サイト 2：www.example.org

サイト 1 で作業を開始し、サイト 2 に移動するユーザーは、サイト 1 から生成されたデバイス ID をパラメータとしてサイト 2 に渡す必要があります。その後、サイト 2 はデバイス ID を使用してSDKを初期化する必要があります。 URLのクエリパラメータにdeviceIdが含まれている場合、SDKは自動的にそのURLパラメータを解析できます。

v2.8.0以降、SDKはURLからセッションIDを自動的に取得できるようになり、同じセッションを維持し、ユーザーの継続的なジャーニーを確保できるようになりました。

1. サイト1から、getDeviceId()のデバイスIDとgetSessionId()のセッションIDを取得します。
2. ユーザーがナビゲートするときに、URLパラメータを通じてデバイスIDとセッションIDをサイト2に渡します（例：www.example.com?ampDeviceId=device_id_from_site_1&ampSessionId=1716245958483）。
3. init('API_KEY', null)を使用してサイト2でAmplitude SDKを初期化します。

init('API_KEY', null, { deviceId: 'custom-device-id', sessionId: 1716245958483 })でdeviceIdとsessionIdを設定していない場合、SDKは自動的にそれぞれURLパラメータを使用するように切り替わります。

ampTimestamp を使用した評価ウィンドウ

セキュリティを強化し、有効期限が切れたセッションIDやデバイスIDの使用を防ぐために、評価ウィンドウとして機能するampTimestampパラメータを含めることができます。 SDKは、ampTimestampの値が将来の日時（現在時刻より大きい）である場合にのみ、ampSessionIdおよびampDeviceIdのURLパラメータを使用します。

例えば：

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

ampTimestampの有効期限が切れた場合（現在時刻より前の場合）、SDKはampSessionIdおよびampDeviceIdのパラメータを無視します。 SDKは、新しい値を生成するか、Cookieに保存されている値を使用するようにフォールバックします。 を指定しない場合、SDK は下位互換性のためにampTimestamp以前と同じように動作します。

この機能により、クロスドメイントラッキングパラメータは、一定の時間枠内のみ有効になります。これにより、トラッキングパラメータが組み込まれた長期間存在する URL による潜在的なセキュリティ問題を防ぐことができます。

Amplitudeでは、イベントを追跡するたびにイベントがセッション内にあるかどうかを確認するため、Date.now()を使用する際は、ブラウザSDKと同じセッションID形式に従うことを推奨しています。 例えば：

// 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 は以下の場合にリクエスト本文を自動的に圧縮：

• ペイロード サイズが 2 KB 以上です。
• ブラウザは CompressionStreamAPI をサポートしています（最新のブラウザでも利用可能です）。
• トランスポートタイプは 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が必要です。このAPIは以下で利用できます：

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

CompressionStreamをサポートしていないブラウザの場合、SDKは非圧縮ペイロードを自動的に送信します。

キープアライブでページナビゲーションを継続する

fetchkeepaliveデフォルトでは、ブラウザSDKはフラグが有効な状態でトランスポート上でイベントを送信します。ブラウザでは、キープアライブリクエストを開始したページがアンロードされた後も、そのリクエストを完了させることができます。 その結果、リダイレクトやナビゲーションの直前に発生したイベントはキャンセルされるのではなく、Amplitudeに到達します。 一般的な例としては、ユーザーをすぐに別のページに誘導するログインイベントがあります。

キープアライブはfetchトランスポートにのみ適用されます。 beaconトランスポートとは異なり、ITはgzip圧縮、カスタムヘッダー、サーバー応答、および再試行を保持します。

キープアライブのサイズ制限

Fetch仕様では、ドキュメント内のすべてのフライト中のキープアライブリクエストに対して64 KiBの共有予算が適用されます。この予算には、Amplitude Analytics、セッションリプレイ、および独自のコードが作成するキープアライブリクエストが含まれます。予算内に留まるため、SDKはリクエスト本文が16 KB以下の場合にのみキープアライブを適用します。より大きなペイロードはサイズ制限のない標準fetchリクエストとして送信されますが、これらのリクエストはナビゲーションを経由しても生き残りません。これは以前のバージョンの動作と一致しています。 一般的なイベントバッチは制限値を大幅に下回っているため、ほぼすべてのトラフィックで効果が得られます。

セッション中に共有予算が枯渇したためにブラウザがキープアライブリクエストを拒否した場合、SDKは次のフラッシュ時に再試行します。その結果、遅延が発生しますが、データ損失が発生することはありません。

キープアライブを無効にする

キープアライブはデフォルトでオンになっています。 オフにするには、トランスポート設定でenableKeepaliveをfalseに設定します。 このオプションはfetchトランスポートにのみ適用されます。

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

キープアライブをサポートしていないブラウザでは、SDK はこのオプションを無視し、通常どおりリクエストを送信します。

sendBeaconを使用する

標準的なネットワークリクエストとは異なり、sendBeaconはユーザーがブラウザを閉じたりページを離れたりしても、バックグラウンドでイベントを送信します。

すべてのイベントにsendBeaconを使用するようにトランスポートを設定する

sendBeaconを使用してイベントを送信するには、次の2つの方法のいずれかで、トランスポート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,
});

ページを終了するときにのみビーコンを使用するように、トランスポートを設定する

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してください。

Cookieの管理

ブラウザSDKは、同じドメイン内の複数のサブドメイン間で共有される可能性がある情報を保持するために、Cookieストレージを使用しています。 これにはユーザーセッションやマーケティングキャンペーンなどの情報が含まれます。これらの情報は、SDKが別個のCookieエントリに保存します。

Cookieプレフィクス

• AMP：SDKは、AMPプレフィックスとAPIキーの最初の10桁を指定したユーザーセッションCookieを作成します：AMP_{first_ten_digits_API_KEY}。
• AMP_MKTG: SDKは、AMP_MKTGAPIキーの最初の10桁を使用してマーケティングキャンペーンCookieを作成します: AMP_MKTG_{first_ten_digits_API_KEY}。
• AMP_TEST: 初期化時に、SDKはプレフィックス付きのCookieを作成し、Cookieの保存がAMP_TEST正常に機能しているかどうかを確認します。 その後、SDK は値を現在の時刻として設定し、キーを使用して Cookie を取得し、取得された値が元の設定時刻と一致しているかどうかを確認します。 何らかの理由で、SDKがAMP_TESTプレフィックスCookieを正常に削除できなかった場合、それらのプレフィックスCookieは安全に削除できます。
• AMP_TLDTEST: 初期化時に、SDKはプレフィックス付きのCookieを作成し、Cookieストレージをサポートするサブドメインを検索します。 AMP_TLDTESTたとえば、https://analytics.amplitude.com/amplitude/homeにCookieサポートがあるかどうかを確認する場合、SDKはまずルートドメイン (amplitude.com) と一致するサブドメインを検索しようとします。その後、フルドメイン (analytics.amplitude.com) に切り替えます。 何らかの理由で、SDKが****プレフィックスCookieを正常に削除AMP_TLDTESTできなかった場合、それらのプレフィックスCookieは安全に削除できます。

Cookieドメイン

デフォルトでは、SDKはこれらのCookieをCookieの保存をサポートする最上位ドメインに割り当てます。SDKは複数のサブドメインでCookieを共有できるため、すべてのサブドメインで一貫したユーザー体験を実現できます。

たとえば、ユーザーがサブドメイン(data.amplitude.com)でウェブサイトにログインした場合、そのサブドメインでSDKを初期化します。初期化時に、SDKは.amplitude.comにCookieを割り当てます。 ユーザーが別のサブドメイン (analytics.amplitude.com) に移動した場合、共有 Cookie はサブドメイン間でログイン情報を共有します。

Cookieデータ

SDKは、ユーザーセッションCookieとマーケティングキャンペーンCookieという2種類のCookieを作成します。

Cookieを無効にする

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の初期化時とイベント処理時という2つのシナリオでマーケティングアトリビューションの変更を追跡します。

Amplitude SDKの初期化（ハードページリフレッシュ）

• セッションの開始時点では、リファラーは除外されず、キャンペーンに変更があるか、カスタマーが初めて訪問した場合です。
• セッションの途中で、リファラーは除外されず、ダイレクトトラフィックではなく、キャンペーンに変更がある場合です。

デバッグを行うには、ブラウザのコンソールにdocument.referrerを入力してリファラーを取得し、それをconfig.autocapture.attribution.excludeReferrersと比較できます。 document.referrerが空の場合、Amplitude はこれを直接トラフィックと見なします。 AmplitudeのChrome拡張機能の_Cookie_タブにある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で「_データ」>「設定」>「自動キャプチャ」_に移動して、リモート設定を追加または更新します。

リモート設定リクエストのプロキシ

リモート設定リクエストを自身のサーバー経由でプロキシする（例：広告ブロッカーをバイパスする）には、remoteConfigオプションを次のように設定します：

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

remoteConfig.serverUrlを設定すると、SDKはリモート設定リクエストをAmplitudeのエンドポイントではなくカスタムURLに送信します。アナリティクスイベントでは、引き続きserverUrlまたはデフォルトのAmplitudeエンドポイントを使用します。