Node.js SDK 移行ガイド

Amplitudeの最新Node.js SDK（@amplitude/analytics-node）は、プラグインアーキテクチャと組み込み型定義を備えています。最新の Node.js SDK は、メンテナンス Node.js SDK @amplitude/nodeと下位互換性がありません。

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

用語

@amplitude/node：メンテナンスNode.js SDK
@amplitude/analytics-node:最新のNode.js SDK

依存関係

package.json を更新してメンテナンス Node.js SDK をアンインストールし、最新の Node.js SDK をインストールします。

json

{
  "dependencies": {
    "@amplitude/node": "*",
    "@amplitude/analytics-node": "^1"
  }
}

npm install @amplitude/analytics-nodeを使用して@amplitude/analytics-nodeをインストールします。

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

最新のNode.js SDKでは、インストルメンテーションイベントを行うための新しいAPIが提供されています。移行するには、いくつかのコールを更新します。次のセクションでは、どの呼び出しが変更されたかについて詳しく説明します。

初期化

メンテナンス Node.js SDK は名前空間のインポートのみをサポートしています。最新のNode.js SDKは、名前空間インポート（import * as amplitude from '@amplitude/analytics-node'）と名前付きインポート（import { init } from '@amplitude/analytics-node'）の両方をサポートしています。このドキュメントの例では、名前付きインポートを使用しています。

SDKを初期化するには、有効なAmplitude APIキーと設定パラメータを使用してinit()を呼び出します。

import * as Amplitude from "@amplitude/node";
import { init } from "@amplitude/analytics-node";
var options = {};
const client = Amplitude.init(AMPLITUDE_API_KEY, options);
init(API_KEY, options);

設定

最新のNode.js SDKでは異なる設定形式が採用されています。最新のNode.js SDKは、一部の設定オプションをサポートしなくなりました。

@amplitude/node	@amplitude/analytics-node
`debug`	`logLevel`を警告レベルに設定
`logLevel`	`logLevel`
`maxCachedEvents`	`flushQueueSize`
`retryTimeouts`	`flushMaxRetries`は`retryTimeouts`のような数値の配列ではなく、数値にのみ設定可能
`optOut`	`optOut`
`retryClass`	サポートされていません。最新のNode.js SDKは内部で再試行ロジックを処理
`transportClass`	`transportProvider`
`serverUrl`	`serverUrl`
`uploadIntervalInSec`	`flushIntervalMillis`はミリ秒単位、`uploadIntervalInSec`は秒単位
`minIdLength`	`minIdLength`
`requestTimeoutMillis`	非対応
`onRetry`	サポートされていません。最新のNode.js SDKは内部で再試行ロジックを処理

イベントの記録

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

import { track } from '@amplitude/analytics-node';
const eventProperties = {
    buttonColor: 'primary',
};
client.logEvent({
track({
  event_type: 'Button Clicked',
  user_id: 'user@amplitude.com',
  event_properties: eventProperties
});

フラッシュ

flush()APIは依然として同じです。

import { flush } from "@amplitude/analytics-node";
client.flush();
flush();

Identify

identify()APIでは異なるシグネチャを使用します。メンテナンスNode.js SDKのシグネチャは(userId: string | null, deviceId: string | null, identify: Identify)です。最新のNode.js SDKのシグネチャは(identify: Identify, eventOptions?: EventOptions)です。EventOptionsに関する詳細については、EventOptionsリファレンスを参照してください。

import { identify, Identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.set("location", "LAX");
client.identify("user@amplitude.com", null, identifyObj);
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

ミドルウェア

ミドルウェアは、最新Node.js SDKのプラグインにマップされます。最新のNode.js SDKは、エンリッチメントプラグインと送信先プラグインという2つのプラグインタイプをサポートしています。次の例では、イベント情報を記録しています。

+ import { add } from '@amplitude/analytics-node';
+ import { NodeConfig, EnrichmentPlugin, Event, PluginType } from '@amplitude/analytics-types';
- const loggingMiddleware: Middleware = (payload, next) => {
- console.log(`[amplitude] event=${payload.event} extra=${payload.extra}`);
- next(payload);
}
+ export class AddLogEventPlugin implements EnrichmentPlugin {
+ name = 'log-event';
+ type = PluginType.ENRICHMENT as const;
+ config?: NodeConfig;
+ async setup(config: NodeConfig): Promise<undefined> {
+ this.config = config;
+ return;
+ }
+ async execute(event: Event): Promise<Event> {
+ console.log(`[amplitude] event=${event}`);
+ return event;
+ }
+ }

addEventMiddleware()APIはadd()にマップされます。

+ import { add } from '@amplitude/analytics-node';
- client.addEventMiddleware(new Middleware())
+ add(new Plugin());

Was this helpful?