ブラウザ SDK 1

ブラウザSDKを使用すると、Amplitudeにイベントを送信できます。

SDKの初期化

イベントを計測する前に、SDKを初期化してください。AmplitudeプロジェクトのAPIキーが必要です。 この呼び出しでは、オプションのユーザーIDと設定オブジェクトを渡すことができます。初期化後は、アプリケーション内のどこでも SDK を使用できます。

// Option 1, initialize with API_KEY only
amplitude.init(API_KEY);
// Option 2, initialize with user ID if it's already known
amplitude.init(API_KEY, "user@amplitude.com");
// Option 3, initialize with configuration
amplitude.init(API_KEY, "user@amplitude.com", options);

SDK を設定する

基本的な設定オプションに加えて、アトリビューションを設定することもできます。

バッチ処理の動作を設定する

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 trackメソッドは、記録されたすべてのイベントをメモリにキューイングします。SDKはバックグラウンドで、イベントをバッチ単位でフラッシュします。flushQueueSizeおよびflushIntervalMillisを使用してバッチ動作をカスタマイズできます。 デフォルトでは、serverUrlはhttps://api2.amplitude.com/2/httpapiです。一度に大量のデータを送信するには、useBatchをtrueに設定し、setServerUrlをバッチイベントアップロードAPIhttps://api2.amplitude.com/batchに設定します。通常モードとバッチモードの両方で、同じイベント アップロードしきい値とフラッシュ タイム間隔を使用します。

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  // Events queued in memory will flush when number of events exceed upload threshold
  // Default value is 30
  flushQueueSize: 50,
  // Events queue will flush every certain milliseconds based on setting
  // Default value is 10000 milliseconds
  flushIntervalMillis: 20000,
  // Using batch mode with batch API endpoint, `https://api2.amplitude.com/batch`
  useBatch: true,
});

EU域内のデータレジデンシー

クライアントを初期化してAmplitudeのEUサーバーにデータを送信するときにサーバーゾーンを設定します。 SDKはサーバーゾーンが設定されている場合、サーバーゾーンに基づいてデータを送信します。

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

デバッグ

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

パラメータlogLevelを設定します。

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

デフォルトのロガーは、ログを開発者コンソールに出力します。 カスタマイズ用の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: 呼び出された関数の名前です。たとえば "track" です。
• args：呼び出された関数の引数です。
• stacktrace：呼び出された関数のスタックトレースです。
• time：関数呼び出しの開始と終了のタイムスタンプです。
• states：関数呼び出し前後の有用な内部状態のスナップショットです。

イベントを追跡する

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。 たとえば、「ボタンがクリックされました」というアクションは、追跡したいアクションかもしれません。

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

デフォルトイベントを追跡

SDK バージョン 1.9.1 以降、ブラウザ SDK はデフォルトイベントを追跡し、デフォルトイベントの収集を制御するための設定を追加しています。 ブラウザ SDK は次のデフォルトイベントを追跡します。

• ページビュー数

• セッション。

• フォームの操作

• ファイルのダウンロード

• config.defaultTracking.pageViews

  • 値：オプションですboolean。
  • 説明：
    • デフォルトのページビュートラッキングを有効にします。 値が trueの場合、Amplitudeは初期化時にページビューイベントを追跡します。デフォルト値は false です。
    • 追跡されるイベントプロパティには、[Amplitude] Page Domain、[Amplitude] Page Location、[Amplitude] Page Path、[Amplitude] Page Title、[Amplitude] Page URLがあります。
    • 詳細については、「ページビューの追跡」を参照してください。

• config.defaultTracking.sessions

  • 値：オプションですboolean。
  • 説明：
    • セッショントラッキングを有効にします。値が true の場合、Amplitude はセッション開始イベントとセッション終了イベントを追跡します。 デフォルト値は false です。
    • 詳細については、「セッションの追跡」を参照してください。

• config.defaultTracking.formInteractions

  • 値：オプションですboolean。
  • 説明：
    • フォームのインタラクション追跡を有効にします。 値が true の場合、Amplitude はフォームの開始とフォームの送信イベントを追跡します。 デフォルト値は false です。
    • 追跡されるイベントプロパティには、[Amplitude] Form ID、[Amplitude] Form Name、[Amplitude] Form Destinationがあります。
    • 詳細については、「フォームのインタラクションを追跡する」を参照してください。

• config.defaultTracking.fileDownloads

  • 値：オプションですboolean。
  • 説明：
    • ファイルのダウンロード追跡を有効にします。 値が true の場合、Amplitude はファイルダウンロードイベントを追跡します。 デフォルト値は false です。
    • 追跡されるイベントプロパティには、[Amplitude] File Extension、[Amplitude] File Name、[Amplitude] Link ID、[Amplitude] Link Text、[Amplitude] Link URLがあります。
    • 詳細については、「ファイルのダウンロードを追跡」を参照してください。

次のコードサンプルを使用して、すべてのデフォルトイベントの追跡を開始してください。 または、デフォルトイベントを無効にしておくために設定を省略してください。

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    pageViews: true,
    sessions: true,
    formInteractions: true,
    fileDownloads: true,
  },
});

すべてのデフォルトイベントを追跡するには、config.defaultTrackingをtrueに設定することもできます。この設定により、SDKはAmplitudeが追加する可能性のある新しいデフォルトイベントを追跡できます。

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: true,
});

ページビューの追跡

config.defaultTracking.pageViewstrueに設定すると、Amplitudeはデフォルトのページビュートラッキング動作を使用します。この設定は初期化時にページビューイベントを送信します。これはAmplitudeに「[Amplitude] Page Viewed」として表示されます。

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    pageViews: true,
  },
});

ページビューを追跡するための高度な設定

高度な設定を使用すると、SDK がページビューイベントを送信するタイミングをより適切に制御できます。

• config.defaultTracking.pageViews.trackOn
  • 値: オプションです。"attribution" または () => boolean。
  • 説明：
    • SDK がページビューイベントを追跡するタイミングを高度に制御できます。
    • 初期化時にページビューイベントを追跡するには、値を省略するか undefinedに設定します。
    • Amplitudeがウェブアトリビューションを追跡する場合にのみページビューイベントを追跡するように、値を"attribution" に設定します。
    • この値を論理値 (trueまたは false) を返す関数に設定して、基準に基づいてページビューイベントを追跡します。
• config.defaultTracking.pageViews.trackHistoryChanges
  • 値: オプションです。"pathOnly" または "all"。
  • 説明：
    • SDK がページビューを追跡するタイミングについて、シングルページアプリケーションの高度な制御を提供します。
    • 単一ページアプリケーション内の URL ナビゲーション変更時のページビューイベントを追跡するには、この値を省略するか "all"に設定します。 たとえば、https://amplitude.com/#company から https://amplitude.com/#blog への移動などです。
    • この値を"pathOnly" に設定すると、単一ページのアプリケーション内でのみ URL パスのナビゲーション変更に関するページビューイベントが追跡されます。 たとえば、https://amplitude.com/company から https://amplitude.com/blog への移動などです。
• config.defaultTracking.pageViews.eventType
  • 値：オプションですstring。
  • 説明：ページビューイベント用にevent_type をカスタマイズします。

たとえば、URL パスに home などの特定のサブ文字列が含まれている場合にのみページビューを追跡するように Amplitude を設定できます。

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

Amplitudeはページビューイベントを使用して以下の情報を追跡します。

ページビュー追跡とともにプロパティを追加するなど、デフォルトのページビューイベントを強化する方法の例については、この例を参照してください。

セッションを追跡する

trueに設定すると、Amplitudeがセッションを追跡できるようになりますconfig.defaultTracking.sessions。

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    sessions: true,
  },
});

セッションとは、ユーザーがウェブサイトを開いている状態にある時間のことです。 詳細については、「Amplitudeがセッションをどのように定義するか」を参照してください。 新しいセッションが開始されると、Amplitudeはセッション開始イベントをセッションの最初のイベントとして追跡します。 セッション開始のイベントタイプは [Amplitude] Start Session です。 既存のセッションが終了すると、Amplitudeはセッションの最後のイベントである [Amplitude] End Sessionsを追跡します。

フォームのインタラクションを追跡

config.defaultTracking.formInteractionsに設定すると、trueAmplitudeがフォームのインタラクションを追跡できるようになります。

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    formInteractions: true,
  },
});

Amplitudeはユーザーがフォームと最初にやり取りしたタイミングを追跡します[Amplitude] Form Started。 初期のインタラクションとは、テキスト入力欄、ラジオボタン、またはドロップダウンに対する最初の変更を指す場合があります。

Amplitudeはユーザーがフォームを送信したタイミングを追跡します[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>

ファイルダウンロードの追跡

trueに設定すると、Amplitudeがファイルダウンロードを追跡できるようになりますconfig.defaultTracking.fileDownloads。

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    fileDownloads: true,
  },
});

Amplitudeは、ユーザーがファイルにリンクされているアンカーや<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

ユーザープロパティ

ユーザープロパティとは、デバイスの詳細、ユーザー設定、言語などの詳細情報で、ユーザーがアプリでアクションを実行した時点でのユーザーの理解に役立ちます。

Identifyを使用すると、イベントを送信することなく特定のユーザーのユーザープロパティを設定できます。SDK は、個々のユーザー プロパティに対する set、setOnce、unset、add、append、prepend、preInsert、postInsert、removeなどの操作をサポートしています。 指定された Identify インターフェイスを使用して操作を宣言します。 単一の Identify オブジェクト内で複数の操作をチェーンできます。 IdentifyオブジェクトをAmplitudeクライアントに渡してサーバーに送信します。

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

Identifyオブジェクトは、ユーザープロパティの設定を制御します。まず、Identifyオブジェクトをインスタンス化し、そのオブジェクトに対してIdentifyメソッドを呼び出します。最後に、クライアントはIdentifyオブジェクトを使用してコールを発信できます。

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

Identify.set

このメソッドは、ユーザープロパティの値を設定します。 たとえば、ユーザーのロールプロパティを設定できます。

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

Identify.setOnce

このメソッドは、ユーザープロパティの値を1回だけ設定します。SDK は setOnce() を使用した後続の呼び出しを無視します。 たとえば、ユーザーの初期ログイン方法を設定できます。初期値のみが追跡されるため、setOnce() はそれ以降の呼び出しを無視します。

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

Identify.add

このメソッドは、ユーザープロパティを何らかの数値で増分します。ユーザープロパティに値がまだ設定されていない場合、SDKはプロパティを0に初期化してから値を増やします。たとえば、ユーザーの旅行回数を追跡できます。

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

ユーザープロパティ内の配列

配列をユーザープロパティとして使用できます。配列を直接設定するか、prepend, append, preInsert and 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.preInsert

このメソッドは、値がユーザープロパティにまだ存在しない場合に、ユーザープロパティに1つまたは複数の値を事前に挿入します。事前挿入とは、指定されたリストの先頭に値を挿入することを意味します。 ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を事前に挿入する前にそのプロパティを空のリストに初期化します。 ユーザープロパティに既存の値がある場合、このメソッドは動作しません。

const identifyEvent = new amplitude.Identify();
identifyEvent.preInsert("unique-locations", "LAX");
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);

ユーザーグループ

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

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

グループを設定する際には、groupTypeとgroupNameを定義してください。 前の例では、「orgId」は groupType であり、「10」と「15」は groupName の値です。 a のもう 1 つの例としては、「sport」であり、「tennis」や「baseball」のようなgroupName値を持つこともできます。groupType

グループを設定すると、groupType:groupName もユーザー プロパティとして設定され、そのユーザーに設定されている既存groupTypeの値と対応するユーザー プロパティ値が上書きされます。groupName は文字列です。groupTypeこれは、ユーザーが複数のグループに属していることを示す文字列またはgroupName文字列の配列のいずれかを指定できます。

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

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

また、groupsを含むEventオブジェクトをtrackに渡すことで、イベントレベルのグループを設定することもできます。 イベントレベルのグループの場合、グループの指定は特定のログイベントにのみ適用され、setGroupを使用して明示的に設定しない限り、ユーザーに永続することはありません。

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

収益の追跡

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

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

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

収益インターフェイス

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

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

amplitude.flush();

デフォルトでは、SDK は一定の間隔で自動的にflush呼び出されます。 イベントを完全にフラッシュするには、オプションのPromiseインターフェイスを使用して非同期フローを制御します。例：

amplitude.init(API_KEY).promise.then(function () {
  amplitude.track("Button Clicked");
  amplitude.flush();
});

カスタムユーザーID

アプリに独自のログインシステムがあり、ユーザーを追跡したい場合は、いつでもsetUserIdを呼び出してください。

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

ユーザー ID を引数として init 呼び出しに割り当てることもできます。

amplitude.init(API_KEY, "user@amplitude.com");

カスタムセッションID

setSessionIdを使用して新しいセッション ID を割り当てることができます。 カスタムセッションIDを設定する際は、値がエポックからのミリ秒単位であることを確認してください（Unixタイムスタンプ）。

amplitude.setSessionId(Date.now());

カスタムデバイスID

deviceIdを使用して、新しいデバイスIDを割り当てることができます。 カスタムデバイスIDを設定する場合は、値が十分に一意であることを確認してください。AmplitudeはUUIDの使用を推奨しています。

amplitude.setDeviceId(uuid());

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

resetは、ログアウト後にユーザーを匿名化するためのショートカットです。以下の方法で行います：

• userIdをundefinedに設定します。
• 新しい UUID 値を設定しています。deviceId

未定義userIdかつ完全に新しい deviceIdの場合、現在のユーザーはダッシュボードに新しいユーザーとして表示されます。

amplitude.reset();

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

setOptOutに設定することで、特定のユーザーのログをオフにtrueすることができます。

amplitude.setOptOut(true);

setOptOutが有効になっている間は、Amplitudeはイベントをサーバーに保存または送信しません。また、この設定はページ読み込み後も継続します。

setOptOutに設定してfalseログを再度有効にします。

amplitude.setOptOut(false);

オプションの追跡

デフォルトでは、SDKはこれらのプロパティを自動的に追跡します。この動作を上書きするには、SDKの初期化時にtrackingOptionsという名前の設定を渡して、該当するオプションをfalseに設定します。

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  trackingOptions: {
    deviceManufacturer: false,
    deviceModel: false,
    ipAddress: false,
    language: false,
    osName: false,
    osVersion: false,
    platform: false,
  },
});

コールバック

任意で、Promise インターフェイスを通じてすべての非同期 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)
});

プラグイン

プラグインを使用すると、イベントプロパティの変更（エンリッチメントタイプ）やサードパーティAPIへの送信（送信先タイプ）などを行うことで、Amplitude SDK の動作を拡張できます。プラグインとは、メソッドsetup()とexecute()を持つオブジェクトです。

add

addメソッドは、Amplitudeにプラグインを追加します。プラグインはイベントの処理と送信を支援できます。

amplitude.add(new Plugin());

remove

この remove メソッドは、指定されたプラグイン名が存在する場合、クライアントインスタンスからその名前を削除します。

amplitude.remove(plugin.name);

カスタムプラグインを作成する

プラグインのセットアップ

このメソッドには、使用するためにプラグインを準備するためのロジックが含まれており、パラメータとして config を受け取ります。 期待される戻り値は未定義です。 このメソッドの一般的な使用方法は、設定から設定をコピーしたり、プラグインの依存関係をインスタンス化したりすることです。SDKは、amplitude.add()を通じてプラグインをクライアントに登録する際に、このメソッドを呼び出します。

Plugin.execute

このメソッドにはイベントを処理するためのロジックが含まれており、イベントをパラメータとして受け取ります。 拡張タイプのプラグインとして使用する場合、期待される戻り値は変更されたイベントまたは拡張されたイベントです。 宛先タイプのプラグインとして使用する場合、期待される戻り値は、キーevent（BaseEvent）、code（number）、message（string）を含むマップです。 SDK は、Identify、GroupIdentify、および Revenue イベントなど、クライアントインターフェイスを通じて計測される各イベントに対してこのメソッドを呼び出します。

プラグインの例

送信先タイプのプラグイン

以下は、お好みの HTTP クライアントを使用して、計測された各イベントをターゲットサーバーの URL に送信するプラグインの例です。

function myDestinationPlugin (serverUrl) {
  const name = 'my-destination-plugin';
  const type = amplitude.Types.PluginType.DESTINATION;
  let amplitudeConfig;
  /**
   * setup() is called on plugin installation
   * example: amplitude.add(new myDestinationPlugin());
   */
  const setup = function (config) {
    amplitudeConfig = config;
  }
  /**
   * execute() is called on each event instrumented
   * example: amplitude.track('New Event');
   */
  const execute = function (event) {
    const payload = {
      key: 'secret',
      data: event,
    };
    return fetch(this.serverUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Accept: '*/*',
      },
      body: JSON.stringify(payload),
    }).then(function(response) {
      return {
        code: response.status,
        event: event,
        message: response.statusText,
      };
    });
  }
  return {
    name,
    type,
    setup,
    execute,
  },
}
amplitude.init(API_KEY);
amplitude.add(myDestinationPlugin('https://custom.domain.com'));

エンリッチメントタイプのプラグイン

以下は、100 から始まる増分整数をイベントのevent_idプロパティに追加することによって、計測対象となる各イベントを変更するプラグインの例です。

const addEventIdPlugin = () => {
  const name = "add-event-id";
  const type = amplitude.Types.PluginType.ENRICHMENT;
  let currentId = 100;
  let amplitudeConfig;
  /**
   * setup() is called on plugin installation
   * example: amplitude.add(new AddEventIdPlugin());
   */
  const setup = function (config) {
    amplitudeConfig = config;
  };
  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  const execute = function (event: Event) {
    event.event_id = currentId++;
    return event;
  };
  return {
    name,
    type,
    setup,
    execute,
  };
};
amplitude.init(API_KEY);
amplitude.add(addEventIdPlugin());

ウェブアトリビューション強化プラグイン

initメソッドを呼び出す前に、plugin-web-attribution-browserパッケージをダウンロードして webAttributionPluginを追加してください。

npm install @amplitude/plugin-web-attribution-browser

プラグインをAmplitudeインスタンスに追加します。

amplitude.add(webAttributionPlugin());
amplitude.init(API_KEY);

設定の詳細については、設定オプションを参照してください。

Webアトリビューションプラグインがサポートする機能の詳細については、プラグインのドキュメントを参照してください。

ベースSDKとの相違点

アトリビューションプラグインを有効にすると、SDKのデフォルトのアトリビューション追跡動作が上書きされます。

SDKに組み込まれているアトリビューション追跡機能は、セッション開始時のアトリビューション追跡のみを行います。つまり、ユーザーがセッションの途中で新しいキャンペーンチャネル（ダイレクトや広告など）を通じてサイトに再アクセスした場合、SDKはこの新しいチャネルを記録しません。

このtrackNewCampaignsオプションをtrueに設定した場合、SDKはキャンペーンを追跡し、新しいキャンペーンを検出するとユーザーのセッションをリセットします。

アトリビューションプラグインは、ユーザーがセッションの開始時にいるかどうかにかかわらず、すべてのキャンペーンを追跡します。

Amplitudeが新しいキャンペーンを検出したときにユーザーのセッションをリセットするには、このresetSessionOnNewCampaignオプションをtrueに設定します。 リファラーがサイトの別のサブドメインである場合、セッションはリセットされません。

ページビューエンリッチメントプラグイン

initメソッドを呼び出す前に、plugin-page-view-tracking-browserをダウンロードしてpageViewTrackingPluginaddしてください。

npm install @amplitude/plugin-page-view-tracking-browser

Amplitudeインスタンスにプラグインを追加します。

amplitude.add(pageViewTrackingPlugin());
amplitude.init(API_KEY);

設定の詳細については、設定オプションを参照してください。 ページビュープラグインがサポートする内容の詳細については、プラグインのドキュメントを参照してください。

ベースSDKとの相違点

オプションが attribution.trackPageViews に設定されている場合、Amplitude がユーザーのキャンペーンを追跡するときにベース SDK はページビューイベントを送信しますtrue。

ページビュープラグインは、ユーザーがアクセスする各ページに対して、デフォルトでページビューイベントを送信します。 このプラグインはまた、この動作をカスタマイズするためのオプションを提供します。

トラブルシューティングとデバッグ

ブラウザでのデバッグは、コードの実装に関連する問題や、使用している SDK 内の潜在的な問題を特定するのに役立ちます。 ここでは、デバッグのためにブラウザに標準搭載されている開発者ツール（DevTools）の使い方について、基本的な手順を解説します。

コンソール

JavaScript エラーは、「検査」>「コンソール」で確認できます。このページには、問題を引き起こしたコード行とファイルの詳細情報が含まれている可能性があります。 また、コンソールでは JavaScript コードをリアルタイムで実行することもできます。

• デバッグモードの指示に従って、デバッグモードを有効にします。デフォルトのロガーを使用すると、SDKのパブリックメソッドを呼び出した際、SDKは追加の関数コンテキスト情報を開発者コンソールに出力します。これはデバッグに役立ちます。

• AmplitudeはSDKの遅延初期化をサポートしています。 Amplitudeは、初期化呼び出しの後に、初期化前に追跡されたイベントをディスパッチします。イベントを送信できない場合でも、ブラウザコンソールに入力した後にamplitude.init(API_KEY, 'USER_ID')イベントを正常に送信できるのであれば、コードベースで呼び出しがトリガーされていないか、amplitude.init初期化時に正しいAmplitudeインスタンスを使用していない可能性があります。

ネットワークリクエスト

［*Inspect］＞［Network］*タブを使用して、ページから送信されたすべてのネットワーク要求を表示できます。Amplitudeリクエストを検索します。

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

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

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

詳細については、イベントストリーム分析ガイドを参照してください。

一般的な問題

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

広告ブロッカー

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

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

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

Cookie関連

SDK がクッキーに保存する情報の詳細については、「クッキー管理」のセクションを参照してください。 クッキーを無効にする、プライベートブラウザ、ウィンドウ、タブを使用するなどのクライアントの動作は、クッキーに保存されているこれらの値の持続性に影響します。 これらの値が持続していない場合や、1 つずつ増加していない場合は、それが原因である可能性があります。

CORS

クロスオリジンリソース共有 (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の問題ではなく、アプリケーションとサービスプロバイダー間の連携の問題です。

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

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

この問題に対処するには、次の 2 つの方法があります。

1. 標準的なネットワーク要求を使用する場合は、初期化時にトランスポートを beacon に設定するか、ページ終了時にトランスポートを beacon に設定してください。sendBeacon はバックグラウンドでイベントを送信し、4xx または 5xx のようなサーバー応答を返さないため、この場合は機能しません。その結果、失敗しても再試行しません。sendBeacon はスケジュール済みの要求をバックグラウンドで送信するだけです。詳細については、「sendBeacon」セクションを参照してください。

2. track()を同期させるには、呼び出しの前にキーワードawaitを追加します。

高度なトピック

クロスドメイン追跡

2つの異なるドメインにわたって匿名の行動を追跡できます。 Amplitudeは、ドメイン間で渡される必要があるデバイスIDによって匿名ユーザーを識別します。 例えば：

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

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

URLのクエリパラメータにdeviceIdが含まれている場合、SDKは自動的にそのURLパラメータを解析できます。

1. サイト1で、getDeviceId()からデバイスIDを取得します。
2. ユーザーがナビゲートするときに、URL パラメータを使用してデバイス ID をサイト 2 に渡します。 例：www.example.com?deviceId=device_id_from_site_1。
3. init('API_KEY', null)を使用して、サイト2でAmplitude SDKを初期化します。

deviceIdなどを init と共に提供しない場合、SDK は自動的に URL パラメータの使用にフォールバックします。init('API_KEY', null, { deviceId: 'custom-device-id' })

カスタムHTTPクライアント

カスタマイズのために、transportProviderconfiguration オプションへの Transportinterface の実装を提供できます。 たとえば、カスタマイズされた HTTP リクエストヘッダーを使用してプロキシサーバーにリクエストを送信する場合などです。

class MyTransport {
  send(serverUrl, payload) {
    // check example: https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/analytics-client-common/src/transports/fetch.ts
  }
}
amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  transportProvider: new MyTransport(),
});

sendBeaconを使用する

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

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

sendBeaconを使用してイベントを送信するには、次の 2 つの方法のいずれかで、トランスポート SDK オプションを 'ビーコン' に設定します。

amplitude.init(API_KEY, "user@amplitude.com", {
  transport: TransportType.SendBeacon,
  // To make sure the event will be scheduled 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 は、クッキーストレージを使用して、同じドメインの複数のサブドメインが共有したい可能性がある情報を保持します。 この情報にはユーザーセッションやマーケティングキャンペーンが含まれ、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を取得し、取得された値が元の設定時刻と一致するかどうかを確認します。 何らかの理由でプレフィックス付きCookieが正常に削除されなかった場合でも、AMP_TEST安全に削除できます。
• AMP_TLDTEST: 初期化時に、SDK はプレフィックス付きの Cookie を作成し、Cookie の保存をサポートするサブドメインを検索しますAMP_TLDTEST。 たとえば、https://analytics.amplitude.com/amplitude/homeにCookieサポートがあるかどうかを確認する場合、SDKはまずルートドメイン (amplitude.com) と一致するサブドメインを検索しようとします。その後、フルドメイン (analytics.amplitude.com) に切り替えます。 何らかの理由でプレフィックス付きCookieが正常に削除されなかった場合でも、AMP_TLDTEST安全に削除できます。

Cookieドメイン

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

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

Cookieデータ

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

Cookieを無効にする

Cookieの使用をオプトアウトするには、disableCookiesをtrueに設定します。これによりSDKは代わりにLocalStorageを使用します。LocalStorageは便利な代替手段ですが、LocalStorageへのアクセスはサブドメインごとに制限されるため、製品のサブドメイン間で匿名ユーザーを追跡することはできません（例：www.amplitude.comとanalytics.amplitude.com）。

デバイスIDのライフサイクル

SDKはデバイスIDを次の順序で初期化し、デバイスIDを最初に検出された有効な値に設定します。

1. 初期化時の設定内のデバイス ID。
2. URLパラメータからのdeviceId値（例：http://example.com/?deviceId=123456789）。詳細については、「クロスドメイン トラッキング」を参照してください。
3. クッキーストレージ内のデバイス ID。 詳細については、「クッキー管理」を参照してください。
4. ブラウザSDKのクッキーストレージ内のデバイスID。詳細については、「クッキー管理」を参照してください。
5. ランダムに生成された36文字のUUID。

デバイス ID が変更されるのはいつですか

デバイスIDはさまざまなシナリオで変更されます。

• setDeviceId()を明示的に呼び出します。
• デフォルトでは、SDKはデバイスIDをCookieに保存するため、ユーザーがクッキーをクリアしたり、別のデバイスを使用したり、プライバシーモードを使用したりすると、デバイスIDは変更されます。
• 初期化時には、URLパラメータはデバイスIDdeviceIdとして渡されます。
• reset()呼び出します。

カスタムデバイスID

setDeviceId()を使用して、新しいデバイスIDを割り当てることができます。 カスタムデバイスIDを設定する場合は、値が十分に一意であることを確認してください。AmplitudeはUUIDの使用を推奨しています。

amplitude.setDeviceId(uuid());

デバイスIDを取得する

ヘルパーメソッド getDeviceId() を使用して、現在の deviceId の値を取得できます。

const deviceId = amplitude.getDeviceId();