ブラウザSDK 1.0から2.0への移行

Amplitude Browser SDK 2.0（@amplitude/analytics-browser）は、自動キャプチャ、マーケティングアトリビューショントラッキングの改善、簡素化されたインターフェイス、軽量化されたパッケージなどを特徴としています。

Browser SDK 2.0はAmplitude Session Replayと互換性があります。

用語

• @amplitude/analytics-browser@1：ブラウザSDK 1.0
• @amplitude/analytics-browser@2：ブラウザSDK 2.0

依存関係

{
  "dependencies": {
-   "@amplitude/analytics-browser": "^1"
+   "@amplitude/analytics-browser": "^2"
  }
}

自動キャプチャ

Browser SDK 2.10.0以降、Amplitudeはデフォルトで自動キャプチャを有効にしています。自動キャプチャは、Amplitudeがユーザーに代わって実行する暗黙の追跡であり、ページビュー、セッション、ファイルダウンロード、フォームと要素の相互作用、マーケティングアトリビューションなどが含まれます。

デフォルトのトラッキングをオプトアウトするには、options.autocaptureをfalseに設定します。

amplitude.init(API_KEY, undefined, {
  autocapture: false,
});

また、Amplitudeがトラッキングするイベントを選択することもできます。たとえば、マーケティングアトリビューションとページビューに対してのみデフォルトのトラッキングを有効にするには、以下のコードを使用します。

amplitude.init(API_KEY, undefined, {
  autocapture: {
    attribution: true,
    pageViews: true,
    sessions: false,
    fileDownload: false,
    formInteractions: false,
    elementInteractions: false,
  },
});

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

Browser SDK 2.0以降、AmplitudeはBrowser SDKとマーケティング分析SDKを1つのソリューションに統合し、プロダクトとマーケティング分析の両方のユースケースに対応しています。

マーケティングアトリビューショントラッキングでは、リファラーと同じルートドメインのすべてのサブドメインが除外されます。デフォルトでは、Amplitudeはあるサブドメインから別のサブドメインへのトラフィック（例：analytics.amplitude.comからexperiment.amplitude.comへのトラフィック）を追跡しません。

デフォルトでは、Browser SDK 1.0は他のサブドメインをリファラーとして追跡します。この動作を維持するには、以下のコードを参照してください。

非推奨 options.attribution.trackNewCampaigns

Amplitudeがこのオプションを設定不可能なデフォルト動作として採用したため、このオプションはサポートされなくなりました。Amplitudeは、UTM、リファラー、クリックIDなどのキャンペーンパラメータに対するあらゆる変更を追跡します。

非推奨 options.attribution.trackPageViews

このオプションはもう存在しませんが、ページビューオプションを使用して同様にAmplitudeを設定できます。

amplitude.init(API_KEY, undefined, {
- attribution: {
-   trackPageViews: true,
- },
+ defaultTracking: {
+   pageViews: {
+     trackOn: 'attribution',
+   },
+ },
});

クッキーのオプション

Browser SDK 2.0以降、Amplitudeはクッキーの使用を管理するオプションを簡素化しました。デフォルトでは、AmplitudeはユーザーIDをブラウザのクッキーに保存します。

代替ストレージAPIを使用する

amplitude.init(API_KEY, undefined, {
  disableCookies: true,
  identityStorage: "localStorage",
});

ユーザー ID 永続性を無効にする

import { MemoryStorage } from "@amplitude/analytics-core";
amplitude.init(API_KEY, undefined, {
  cookieStorageProvider: new MemoryStorage(),
  identityStorage: "none",
});

クッキーオプションの設定

クッキーの使用を管理するオプションが、インターフェイスをより見つけやすくするためにoptions.cookieOptionsの下にネストされるようになりました。

amplitude.init(API_KEY, undefined, {
  cookieExpiration: 365,
  cookieSameSite: "Lax",
  cookieSecure: false,
  cookieUpgrade: true,
  domain: "",
  cookieOptions: {
    expiration: 365,
    sameSite: "Lax",
    secure: false,
    upgrade: true,
    domain: "",
  },
});

ユーザーエージェントのクライアント側解析を廃止

Browser SDK 2.0 以降、Amplitude はユーザーエージェントのプロパティ拡張をクライアント側からサーバー側に移行しました。 拡張されたユーザープロパティには、os_name、os_version、device_model、およびdevice_manufacturerが含まれます。新しい拡張戦略により、より正確な結果が得られますが、ブラウザー SDK 1.0 とはわずかに異なる結果が得られ、これらのプロパティを照会する既存のアナリティクスチャートに影響を与える可能性があります。ブラウザー SDK 1.0 の動作を維持するには、@amplitude/plugin-user-agent-enrichment-browser をインストールしてクライアント側でこれらのユーザープロパティを強化します。詳細については、NPM の plugin-user-agent-enrichment-browser パッケージを参照してください。

列挙型が不要に

Amplitude はもはや列挙型 TransportType、ServerZone、PluginType、を必要とせず、それらのリテラル値を受け入れます。

初期化時にトランスポート プロバイダーを設定します。

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init(API_KEY, USER_ID, {
  transport: amplitude.Types.TransportType.Fetch,
  transport: "fetch",
});

setTransport()を使用してトランスポートプロバイダーを設定します：

import * as amplitude from "@amplitude/analytics-browser";
amplitude.setTransport(amplitude.Types.TransportProvider.Fetch);
amplitude.setTransport("fetch");

初期化時にサーバゾーンを設定します。

import * as amplitude from "@amplitude/analytics-browser";
amplitude.init(API_KEY, USER_ID, {
  serverZone: amplitude.Types.ServerZone.US,
  serverZone: "US",
});

簡素化されたプラグインインターフェイス

Amplitudeを使用すると、独自のプラグインを作成することが容易になり、必要なプロパティが少なくなり、より高速なオーサリングが可能です。

plugin.name [オプション]

名前フィールドはオプションのプロパティで、削除のためにプラグインを参照できます。 名前を指定しない場合、Amplitudeはプラグインを追加するときにランダムな名前を割り当てます。 プラグインを削除する予定がない場合は、名前の割り当てをスキップできます。

plugin.type [オプション]

タイプフィールドは、作成するプラグインのタイプを定義するオプションのプロパティです。 この2つのタイプを区別するには、以下のexecute()関数を参照してください。 タイプを定義しない場合、プラグインはデフォルトで拡張タイプを使用します。

plugin.setup() [オプション]

setup関数はオプションのメソッドで、プラグインを追加したとき、または最初のinit時のいずれか後の方のタイミングでAmplitudeが呼び出します。この関数は2つのパラメータを受け取ります：

1. Amplitudeの設定。
2. Amplitudeインスタンス。

setup機能は、Amplitudeの設定またはインスタンスに依存するセットアップ操作やタスクに役立ちます。 例としては、変数へのベースライン値の割り当てやイベントリスナーの設定などがあります。

plugin.execute() [タイプ： エンリッチメントの場合はオプションです]

エンリッチメントプラグインの場合、execute 関数はオプションのメソッドで、Amplitude は各イベントに対して呼び出します。 この関数は新しいイベントを返さなければなりません。 そうでない場合、Amplitudeは渡されたイベントをキューから削除します。execute 関数は、イベントからプロパティを追加または削除したり、イベントをフィルタリングしたり、トラッキング対象の各イベントに対して何らかの操作を実行したりする必要がある場合に便利です。

送信先プラグインの場合、execute 関数はAmplitudeが各イベントに対して呼び出す必須メソッドです。この関数は、event（BaseEvent）、code（数値）、message（文字列）というキーを持つレスポンスオブジェクトを返さなければなりません。 execute 関数は、イベントをサードパーティ製エンドポイントに送信する場合に便利です。

plugin.teardown() [オプション]

ティアダウン関数は、Amplitudeが再初期化されたときにAmplitudeが呼び出すオプションのメソッドです。 teardown関数は、セットアップメソッドや実行メソッドによって作成された不要な永続状態をリセットするのに役立ちます。たとえば、イベントリスナーやミューテーションオブザーバーの削除などがあります。

ウェブアトリビューションv2とウェブアトリビューションv1の比較

ウェブアトリビューションバージョン2：

• デフォルトでは有効です。
• セッションのコンテキスト（新規または既存）に関係なく、新しいキャンペーンでinit上のアトリビューションを追跡します。 設定できません。
• すべての初期タッチアトリビューションプロパティのデフォルト値は"EMPTY"です。config.initialEmptyValueを使用して設定できます。
• 新しいキャンペーンで新しいセッションを開始することはありません。 config.resetSessionOnNewCampaign = trueを使用して設定できます。
• 広告クリックIDを追跡します。

ウェブアトリビューションバージョン1：

• デフォルトでは有効です。
• 新しいセッションでのinit時にアトリビューションを追跡します。設定できません。
• 新しいキャンペーンでは、initでのアトリビューションの追跡は行いません。 config.trackNewCampaignsを使用して設定できます。
• すべての初期タッチアトリビューションプロパティのデフォルト値は"EMPTY"です。config.initialEmptyValueを使用して設定できます。
• 新しいキャンペーンで新しいセッションを開始することはありません。 config.resetOnNewCampaignを使用して設定できます。
• 広告クリックIDを追跡します。