Node SDK

Amplitude Node.js SDKは、Amplitude向けの初のバックエンドSDKであり、TypeScriptで記述されています。

クライアント側のSDKは、単一のユーザーまたはデバイスのセッションとアトリビューションの追跡向けに最適化されています。Node SDKは開発者の体験に重点を置いており、バックエンドサービスが多くのユーザーやソースからイベントを確実に正確に送信できるように支援しています。

Node SDKは以下を提供します。

• イベントのバッチ処理により、同じリクエストで複数のイベントを送信できます。
• ネットワークリクエストが失敗した場合や、Amplitudeがペイロードを制限または拒否した場合に対処する、リトライ処理メカニズム。
• インストルメンテーションに関する問題をデバッグするのに役立つユーティリティと型定義。

SDKの初期化

計装を行う前に、AmplitudeプロジェクトのAPIキーを使用してSDKを初期化してください。 初期化によってデフォルトのインスタンスが作成されます。 文字列名を指定してgetInstanceを使用することで、さらにインスタンスを作成できます。

// Option 1, initialize with API_KEY only
Amplitude.init(AMPLITUDE_API_KEY);
// Option 2, initialize including configuration
var options = {};
Amplitude.init(AMPLITUDE_API_KEY, options);

SDK を設定する

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

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 SDKは、logEventメソッドがメモリに記録するすべてのイベントをキューに入れ、その後、イベントをバックグラウンドでバッチ処理でフラッシュします。maxCachedEventsおよび uploadIntervalInSecを使用してバッチ動作をカスタマイズできます。 デフォルトでは、serverUrlはhttps://api2.amplitude.com/2/httpapiです。一度に大量のデータを送信するには、バッチモードを使用します。サーバーの URL をニーズに合ったバッチイベントアップロード API に設定します。

• 標準サーバーバッチAPI： https://api2.amplitude.com/batch。
• EU居住サーバーバッチAPI：https://api.eu.amplitude.com/batch。

通常モードとバッチモードの両方で、同じイベント アップロードしきい値とフラッシュ タイム間隔を使用します。

Amplitude.init(AMPLITUDE_API_KEY, {
  // Events queued in memory will flush when number of events exceed upload threshold
  // Default value is 16000
  maxCachedEvents: 20000,
  // Events queue will flush every certain milliseconds based on setting
  // Default value is 0 second.
  uploadIntervalInSec: 10,
});

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

AmplitudeのEUサーバーにデータを送信するには、初期化時にサーバーURLを設定してください。

client = Amplitude.init(AMPLITUDE_API_KEY, {
  serverUrl: "https://api.eu.amplitude.com/2/httpapi",
});

イベントを送信

計装に関する問題を防ぐために、デバイスIDとユーザーIDは、5文字以上の文字列である必要があります。 イベントに短すぎるデバイスIDまたはユーザーIDが含まれている場合、AmplitudeはそのイベントからID値を削除します。イベントにdevice_idまたはuser_idの値がない場合、Amplitudeはアップロードを400ステータスで拒否することがあります。 デフォルトの最小長である5文字を上書きするには、リクエストにmin_id_lengthオプションを渡します。

import * as Amplitude from "@amplitude/node";
const client = Amplitude.init(AMPLITUDE_API_KEY);
client.logEvent({
  event_type: "Node.js Event",
  user_id: "datamonster@gmail.com",
  location_lat: 37.77,
  location_lng: -122.39,
  ip: "127.0.0.1",
  event_properties: {
    keyString: "valueString",
    keyInt: 11,
    keyBool: true,
  },
});
// Send any events that are currently queued for sending.
// Will automatically happen on the next event loop.
client.flush();

ミドルウェア

ミドルウェアを使用すると、すべてのイベントで一連のカスタムコードを実行することでAmplitudeを拡張できます。このミドルウェアパターンは柔軟性があり、イベントの拡張、変換、フィルタリング、サードパーティの宛先へのルーティングなどをサポートしています。

各ミドルウェアは次のシグネチャを持つ関数です。

function (payload: MiddlewarePayload: next: MiddlewareNext): void;

payloadにはeventと、独自のミドルウェア実装にカスタムデータを渡すことができるオプションのextraフィールドが含まれています。

キュー内の次のミドルウェアを呼び出すには、next関数を使用します。ミドルウェア チェーンを継続するために next(payload) を呼び出してください。ミドルウェアが next を呼び出さなかった場合、現在のミドルウェアが完了した後にイベント処理が停止します。

client.addEventMiddleware()を使用してミドルウェアを Amplitude に追加します。 必要な数のミドルウェアを追加できます。 各ミドルウェアは、追加した順序で実行されます。

const loggingMiddleware: Middleware = (payload, next) => {
 console.log(`[amplitude] event=${payload.event} extra=${payload.extra}`);
 // continue to next middleware in chain
 next(payload);
}
const filteringMiddleware: Middleware = (payload, next) => {
 const {eventType} = payload.event;
 if (shouldSendEvent(eventType)) {
 next(payload)
 } else {
 // event will not continue to following middleware or be sent to Amplitude
 console.log(`Filtered event: ${eventType}`);
 }
}
client.addEventMiddleware(loggingMiddleware)
client.addEventMiddleware(filteringMiddleware)

例については、TypeScriptとJavaScriptを参照してください。