Javascript SDK から Browser SDK 1.0 への移行

Amplitude Browser SDK 1.0（@amplitude/analytics-browser）は、プラグインアーキテクチャ、組み込みの型定義、およびフロントエンドフレームワークに対するサポートの拡張が特徴です。Browser SDK 1.0はamplitude-jsと下位互換性がありません。

@amplitude/analytics-browserに移行するには、依存関係とインストルメンテーションを更新してください。

用語

• amplitude-js：Maintenance Browser SDK。
• @amplitude/analytics-browser：Browser SDK 1.0。

依存関係

スニペットをインストールするには、プロジェクトのスニペットローダーを更新してください。

Nodeプロジェクトの場合、package.json内の依存関係リストを更新してください。

{
  "dependencies": {
    "amplitude-js": "^8"
  }
}

インスツルメンテーション

ブラウザSDK 1.0はイベントを計測するためのAPIを提供します。Browser SDK 1.0に移行するには、いくつかの呼び出しを更新します。次のセクションでは、どのコールが変更されたかについて詳しく説明します。

初期化

他のすべての呼び出しと同様に、AmplitudeでもgetInstance()は削除されています。SDKを初期化するには、同じパラメータを使用してinit()を呼び出します。configパラメータの形状が異なります。 設定を参照してください。

import amplitude from "amplitude-js";
amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, config);

設定

イベントの追跡

メンテナンスBrowser SDKでは、イベントペイロード内の特定のプロパティをオーバーライドするための、logEventWithTimestampやlogEventWithGroupsなど、いくつかのlogEventAPIが提供されています。Amplitudeはこれらのバリエーションを単純化し、@amplitude/analytics-browser内で統一されたtrackAPIにしました。

logEvent()

logEvent()APIはtrack()にマップされます。

const eventType = "Button Clicked";
const eventProperties = {
  type: "primary",
};
amplitude.getInstance().logEvent(eventType, eventProperties);

logEventWithTimestamp()

logEventWithTimestamp()APIはtrack()にマップされます。

const eventType = "Button Clicked";
const eventProperties = {
  type: "primary",
};
const timestamp = Date.now();
amplitude
  .getInstance()
  .logEventWithTimestamp(eventType, eventProperties, timestamp);

logEventWithGroups()

logEventWithGroups()APIはtrack()にマップされます。

const eventType = "Button Clicked";
const eventProperties = {
  type: "primary",
};
const groups = {
  orgId: "12345",
};
amplitude.getInstance().logEventWithGroups(eventType, eventProperties, groups);

sendEvents()

sendEvents()APIはflush()にマップされます。

amplitude.getInstance().sendEvents();

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

ユーザープロパティを設定するためのAPIは同じですが、getInstance()存在しなくなりました。次のコードスニペットは、ユーザープロパティ API を移行する方法を示しています。

setUserId()

getInstance()を呼び出さずにamplitudeを呼び出す場合は、userIdを設定します。

const userId = "1";
amplitude.getInstance().setUserId(userId);

setDeviceId()

getInstance()を呼び出さずにamplitudeを呼び出す場合は、deviceIdを設定します。

const deviceId = "1";
amplitude.getInstance().setDeviceId(deviceId);

setSessionId()

getInstance()を呼び出さずにamplitudeを呼び出す場合は、sessionIdを設定します。

const sessionId = Date.now();
amplitude.getInstance().setSessionId(sessionId);

clearUserProperties()

AmplitudeはclearUserPropertiesAPIを削除しました。 ユーザープロパティを削除するには、統合されたidentifyAPIを使用してください。

amplitude.getInstance().clearUserProperties();

setUserProperties()

AmplitudeはsetUserPropertiesAPIを削除しました。 ユーザープロパティを追加するには、統合されたidentifyAPIを使用してください。

amplitude.getInstance().setUserProperties({
  membership, "paid",
  payment, "bank",
})

identify()

getInstance()を呼び出さずにamplitudeでidentifyを呼び出します。

const identify = new amplitude.Identify();
identify.set("membership", "paid");
amplitude.getInstance().identify(identify);

グループプロパティを設定する

groupIdentify()

getInstance()を呼び出さずにamplitudeでidentifyを呼び出します。

const identify = new amplitude.Identify();
identify.set("membership", "paid");
amplitude.getInstance().groupIdentify(identify);

収益の追跡

logRevenueV2()

getInstance()を呼び出さずに、amplitudeでrevenue()APIを使用して収益を追跡します。

const revenue = new amplitude.Revenue();
revenue.setProductId("productId").setPrice(10);
amplitude.getInstance().logRevenueV2(revenue);

パターン

プラグイン

設定config.language、config.library、config.platformおよびamplitude-jsは、これらの特定のフィールドのイベントペイロードを変更するためにで使用できました。@amplitude/analytics-browserはこれらの設定をサポートしていませんが、新しいブラウザSDKにプラグインを追加してイベントペイロードを強化できます。

import {
  BrowserConfig,
  EnrichmentPlugin,
  Event,
  PluginType,
} from "@amplitude/analytics-types";
export class LibraryModifierPlugin implements EnrichmentPlugin {
  name = "library-modifier";
  type = PluginType.ENRICHMENT as const;
  /**
   * setup() is called on plugin installation
   * example: client.add(new LibraryModifierPlugin());
   */
  setup(config: BrowserConfig): Promise<undefined> {
    this.config = config;
  }
  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  execute(event: Event): Promise<Event> {
    event.library = "my-library-name/1.0.0";
    return Promise.resolve(event);
  }
}

カスタムプラグインをインストールするには、カスタムプラグインをパラメータとしてadd()を使用します。

import { add } from "@amplitude/analytics-browser";
add(new LibraryModifierPlugin());

初期化を遅らせる

amplitude-jsで初期化を延期するには、config.deferInitializationをtrueに設定してinitを呼び出し、次にenableTracking()を呼び出して初期化を正式化し、キューに入れたすべてのイベントを送信します。

amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, {
  deferInitialization: true,
});
amplitude.getInstance().logEvent("Event 1");
amplitude.getInstance().logEvent("Event 2");
amplitude.getInstance().logEvent("Event 3");
amplitude.getInstance().enableTracking();

ウェブアトリビューション

amplitude-jsでは、次の設定を有効にすることでWebアトリビューションを有効にできます。

• config.includeGclid。
• config.includeFbclid。
• config.includeReferrer。
• config.includeUtm。

@amplitude/analytics-browserでは、ウェブアトリビューションを1つの設定で制御できます：config.attribution.disabled。デフォルト値は false で、これはすべてのキャンペーンのパラメータをキャプチャします。 この設定では、amplitude-js と同じキャンペーン パラメータが収集されます。

フラッシュまたは onExitPage

ユーザーがページから移動したときなど、一部のシナリオではイベントを即座に送信する必要があります。このケースは、イベントペイロードをバッチで送信しながら、ユーザーを別のページに誘導するボタンクリックをトラッキングする場合によく見られます。

amplitude-jsで、onExitPage()コールバックを使用します。

amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, {
  onExitPage: () => {
    amplitude.sendEvents();
  },
});

コールバック

amplitude-jsでは、初期化後に実行されるように 1 つのinitコールバック関数と、成功およびエラーのネットワーク要求に対して 2 つの別々のコールバック関数を渡します。 @amplitude/analytics-browserはPromise（およびasync/await）をサポートしているため、init()、track()、identify()、およびgroupIdentify()などの非同期メソッドは、カスタムPromiseインターフェイスを返します。

const initResult = await amplitude.init("YOUR_API_KEY").promise;
if (initResult.code === 200) {
  // success logic
} else {
  // error logic
}
const result = await amplitude.track("Button Clicked").promise;
if (result.code === 200) {
  // success logic
} else {
  // error logic
}