Node.js SDK

Node.js SDK を使用すると、Amplitude にイベントを送信できます。

SDKをインストールする

依存関係を npm または yarn でインストールしてください。

npm install @amplitude/analytics-node

SDKの初期化

計測を行う前に、SDK を初期化する必要があります。 初期化には、Amplitude プロジェクト用の API キーが必要です。SDK を初期化すると、アプリケーション内のどこでも使用できます。

import { init } from "@amplitude/analytics-node";
// Option 1, initialize with API_KEY only
init(API_KEY);
// Option 2, initialize including configuration
init(API_KEY, {
  flushIntervalMillis: 30 * 1000, // Sets request interval to 30s
});

SDK を設定する

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

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

import * as amplitude from "@amplitude/analytics-node";
amplitude.init(API_KEY, {
  // 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,
});

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

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

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

デバッグ

開発者コンソールに出力されるログのレベルを制御します。

• None: すべてのログメッセージを抑制します。
• Error：エラーメッセージのみを表示します。
• Warn：エラーメッセージと警告を表示します。logLevelを明示的に指定しない場合、これがデフォルト値になります。
• Verbose: 有益なメッセージを表示します。
• Debug：デバッグに役立つ可能性のあるエラーメッセージ、警告、および情報メッセージを表示します。これには、すべてのSDKパブリックメソッド呼び出しの関数コンテキスト情報が含まれます。このログモードは開発フェーズでのみ使用してください。

必要なレベルを設定することで、ログ レベルを設定しますlogLevel。

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

デフォルトのロガーは、ログを開発者コンソールに出力します。 カスタマイズの目的に応じて、Loggerインターフェイスに基づいた独自のロガー実装を提供できます。 たとえば、実稼働環境のSDKからエラーメッセージを収集します。

独自の実装で loggerProvider を構成して、ロガーを設定してください。

amplitude.init(AMPLITUDE_API_KEY, {
  loggerProvider: new MyLogger(),
});

デバッグモード

logLevel を "Debug" に設定してデバッグモードを有効にします。たとえば次のようになります。

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

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

• type：このコンテキストのカテゴリ（例：invoke public method）。
• name: 呼び出された関数の名前 (例: setUserId)。
• args：呼び出された関数の引数です。
• stacktrace：呼び出された関数のスタックトレースです。
• time：関数呼び出しの開始と終了のタイムスタンプです。
• states：関数呼び出し前後の有用な内部状態のスナップショットです。

イベントを追跡する

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

import { track } from "@amplitude/analytics-node";
// Track a basic event
track("Button Clicked", undefined, {
  user_id: "user@amplitude.com",
});
// Track events with optional properties
const eventProperties = {
  buttonColor: "primary",
};
track("Button Clicked", eventProperties, {
  user_id: "user@amplitude.com",
});

複数のプロジェクトへのイベントの追跡

複数のAmplitudeプロジェクトにイベントをログ記録するには、Amplitudeプロジェクトごとに個別のインスタンスを作成してください。 次に、Amplitudeを呼び出したい場所にインスタンス変数を渡します。 各インスタンスは、独立したapiKeys、userIds、deviceIds、および設定を使用できます。

import * as amplitude from "@amplitude/analytics-node";
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などの操作をサポートしています。 提供された Identify インターフェイスを使用して操作を宣言します。 複数の操作を単一の Identify オブジェクトにまとめます。 次に、IdentifyオブジェクトをAmplitudeクライアントに渡し、サーバーに送信します。

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

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

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

Identify.set

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

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

Identify.setOnce

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.setOnce("initial-location", "SFO");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.add

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.add("travel-count", 1);
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

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

配列をユーザープロパティとして使用できます。配列を直接設定するか、prepend、append、preInsert、および postInsert を使用して配列を生成します。

Identify.prepend

このメソッドは、ユーザープロパティ配列の前に値を付加します。 ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を先頭に追加する前にそのプロパティを空のリストに初期化します。

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.prepend("visited-locations", "LAX");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.append

このメソッドは、ユーザープロパティ配列に値を付加します。 ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を追加する前にそのプロパティを空のリストに初期化します。

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.append("visited-locations", "SFO");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.preInsert

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.preInsert("unique-locations", "LAX");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.postInsert

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.postInsert("unique-locations", "SFO");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.remove

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.remove("unique-locations", "JFK");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

ユーザーグループ

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 は、ユーザーが複数のグループに属していることを示すために、文字列または文字列の配列のいずれかを指定できます。

import { setGroup } from "@amplitude/analytics-node";
// set group with a single group name
setGroup("orgId", "15", {
  user_id: "user@amplitude.com",
});

import { setGroup } from "@amplitude/analytics-node";
// set group with multiple group names
setGroup("sport", ["soccer", "tennis"], {
  user_id: "user@amplitude.com",
});

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

import { track } from "@amplitude/analytics-node";
track(
  {
    event_type: "event type",
    event_properties: { eventPropertyKey: "event property value" },
    groups: { orgId: "15" },
  },
  undefined,
  {
    user_id: "user@amplitude.com",
  },
);

グループプロパティ

Group Identify API を使用して、特定のグループのプロパティを設定または更新します。これらの更新プログラムは今後のイベントにのみ影響します。

groupIdentify()メソッドは、グループタイプとグループ名の文字列パラメータ、およびグループに適用されるIdentifyオブジェクトを受け入れます。

import { Identify, groupIdentify } from "@amplitude/analytics-node";
const groupType = "plan";
const groupName = "enterprise";
const event = new Identify();
event.set("key1", "value1");
groupIdentify(groupType, groupName, identify, {
  user_id: "user@amplitude.com",
});

収益追跡

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

ユーザーからの収益を追跡するには、ユーザーが収益を生成するたびに、収益を呼び出します。 たとえば、あるカスタマーがプロダクトを1点につき3.99ドルで3台購入したとします。

import { Revenue, revenue } from "@amplitude/analytics-node";
const event = new Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3);
revenue(event, {
  user_id: "user@amplitude.com",
});

収益インターフェイス

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

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

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

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

await init(AMPLITUDE_API_KEY).promise;
track("Button Clicked", undefined, {
  user_id: "user@amplitude.com",
});
await flush().promise;

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

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

import { setOptOut } from "@amplitude/analytics-node";
setOptOut(true);

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

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

import { setOptOut } from "@amplitude/analytics-node";
setOptOut(false);

コールバック

すべての非同期APIはオプションでPromiseインターフェイスを介して待機できます。Promise インターフェイスはコールバックインターフェイスとしても機能します。

import { track } from "@amplitude/analytics-node";
// Using async/await
const results = await track("Button Clicked", undefined, {
  user_id: "user@amplitude.com",
}).promise;
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)
// Using promises
track("Button Clicked", undefined, {
  user_id: "user@amplitude.com",
}).promise.then((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メソッドは、Amplitudeクライアントインスタンスにプラグインを追加します。プラグインはイベントの処理と送信を支援できます。

import { add } from "@amplitude/analytics-node";
add(new Plugin());

削除する

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

import { remove } from "@amplitude/analytics-node";
remove(plugin.name);

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

• plugin.setup()
  • 説明: オプションです。 setup 関数はオプションのメソッドで、プラグインを追加したとき、または最初の初期化時の、いずれか遅い方のタイミングで呼び出されます。この関数は、2つのパラメータを受け取ります：1）Amplitudeの設定、および 2）Amplitudeのインスタンスです。Amplitudeの設定またはインスタンスに依存するセットアップ操作やタスクに使用してください。その例としては、変数へのベースライン値の割り当て、イベントリスナーの設定などがあります。
• plugin.execute()
  • 説明：
    • type:enrichmentの場合はオプションです。 エンリッチメントプラグインの場合、execute 関数は各イベントで呼び出されるオプションのメソッドです。 この関数は新しいイベントを返す必要があります。そうしないと、SDKは渡されたイベントをキューから削除します。 イベントへのプロパティの追加や削除、イベントのフィルタリング、または追跡される各イベントに対する操作の実行が必要な場合に、これを使用します。
    • 送信先プラグインの場合、execute 関数は各イベントで呼び出される必須メソッドです。この関数は、event（BaseEvent）、code（数値）、message（文字列）というキーを持つレスポンスオブジェクトを返さなければなりません。 それを使用して、イベントをサードパーティのエンドポイントに送信します。

プラグインの例

import { init, add } from '@amplitude/analytics-node';
import { NodeConfig, EnrichmentPlugin, Event, PluginType } from '@amplitude/analytics-types';
export class AddEventIdPlugin implements EnrichmentPlugin {
  name = 'add-event-id';
  type = PluginType.ENRICHMENT as const;
  currentId = 100;
  config?: NodeConfig;
  /**
   * setup() is called on plugin installation
   * example: client.add(new AddEventIdPlugin());
   */
  async setup(config: NodeConfig): Promise<undefined> {
     this.config = config;
     return;
  }
  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  async execute(event: Event): Promise<Event> {
    event.event_id = this.currentId++;
    return event;
  }
}
init('API_KEY');
add(new AddEventIdPlugin());

カスタムHTTPクライアント

カスタマイズ目的でTransportインターフェイスの実装を構成オプションに提供できます。たとえば、カスタマイズされたHTTP要求ヘッダーを使用してtransportProviderプロキシサーバに要求を送信する場合などです。

import { Transport } from '@amplitude/analytics-types';
class MyTransport implements Transport {
 async send(serverUrl: string, payload: Payload): Promise<Response | null> {
 // check example: https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/analytics-client-common/src/transports/fetch.ts
 }
}
amplitude.init(API_KEY, {
 transportProvider: new MyTransport(),
});