JRE Java SDK

これは、Amplitude Analytics Java SDKのドキュメントです。

SDKをインストールする

dependencies {
    implementation 'org.json:json:20201115'
    implementation 'com.amplitude:java-sdk:1.+'
}

SDKをインポートする

Amplitudeを使用する任意のファイルにインポートします。 AmplitudeはオープンソースのJSONObjectライブラリを使用して、JSONキー値オブジェクトを作成するため、手間がありません。

import com.amplitude.Amplitude;
import org.json.JSONObject;

SDKの初期化

イベントをインストルメントするには、まずSDKを初期化する必要があります。SDKにはAmplitudeプロジェクト用のAPIキーが必要です。

Amplitude client = Amplitude.getInstance();
client.init(AMPLITUDE_API_KEY);

Amplitude.getInstance(String name)では、設定を一意に保持する名前をオプションで指定できます。

Amplitude client = Amplitude.getInstance("YOUR_INSTANCE_NAME");
client.init(AMPLITUDE_API_KEY);

SDK を設定する

オプション

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

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 SDKは、logEventメソッドがメモリに記録するすべてのイベントをキューに入れ、その後、イベントをバックグラウンドでバッチ処理でフラッシュします。setEventUploadThresholdおよびsetEventUploadPeriodMillisを使用してバッチ動作をカスタマイズできます。 デフォルトでは、SDKはserverUrlがhttps://api2.amplitude.com/2/httpapiに設定されている通常モードで実行されます。一度に大量のデータを送信するには、useBatchModeをtrueに設定してバッチモードに切り替えます。これにより、setServerUrlがバッチイベントアップロードAPIhttps://api2.amplitude.com/batchに設定されます。通常モードとバッチモードの両方で、同じフラッシュキューサイズとフラッシュ間隔を使用します。

Amplitude client = Amplitude.getInstance();
// Events queued in memory will flush when number of events exceed upload threshold
// Default value is 10
client.setEventUploadThreshold(20);
// Events queue will flush every certain milliseconds based on setting
// Default value is 10,000 milliseconds
client.setEventUploadPeriodMillis(5000);
// Using batch mode with batch API endpoint, `https://api2.amplitude.com/batch`
client.useBatchMode(true);

また、イベントをオンデマンドでフラッシュすることもできます。

client.flushEvents();

Amplitudeは、連続的なリアルタイムストリームではなくスケジュールされたジョブなどを通じて一度に大量のデータを送信する顧客向けにバッチモードを提供します。

通常モードとバッチモードの両方で、同じイベント アップロードしきい値とフラッシュ タイム間隔を使用します。バッチモードでは、より大きなペイロードサイズ（20MB）を利用でき、スロットリングの上限も高くなります。

バッチモードではより高いデータレートが許可されるため、Amplitudeは負荷に基づいてバッチモードで送信されるデータを遅延させる可能性があります。 使用例については、GitHub 上のこのプロジェクトを参照してください。

// Enable batch mode
client.useBatchMode(true);
// Disable batch mode
client.useBatchMode(false);

カスタム HTTP プロキシを設定する

バージョン 1.9.0 で追加されました。 HTTPリクエスト用のカスタムプロキシを設定および設定解除します。

// Set proxy for http requests
client.setProxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.domain.com", port)));
// Unset proxy
client.setProxy(Proxy.NO_PROXY);

カスタムロガーを設定する

バージョン 1.10.0 で追加されました。 Amplitudeクライアント用にカスタマイズされたロガーを設定します。

// Set logger
client.setLogger(new AmplitudeLog() {
  @Override
  public void log(String tag, String message, LogMode messageMode) {
    if (messageMode.level >= logMode.level) {
      // implement using custom logging framework and format
    }
  }
});

minIdLength とヘッダーを設定する

Amplitude Java SDKは、1.7.0以降のバージョンで最小ID長とヘッダーのカスタマイズをサポートしています。

// Set logger
client.setOptions(new Options()
      .addHeader("Custom Header", "value")
      .setMinIdLength(5));

イベントフラッシュとスレッドタイムアウトの設定

バージョン 1.10.0 で追加されました。 イベントのスレッドフラッシュタイムアウトをミリ秒単位で設定します。正の長い整数に設定されている場合、イベントフラッシュタスクはタイムアウトになり、これらのイベントのコールバックがトリガーされます。

client.setFlushTimeout(2000L); // 2 seconds

クライアントをシャットダウンしてリソースをリリースする

バージョン 1.10.0 で追加されました。 Amplitudeクライアントが新しいイベントを受け入れるのを停止し、スレッドプールをシャットダウンします。 バッファ内のイベントはコールバックをトリガーします。 Amplitudeは、同じインスタンス名でAmplitude.getInstance(INSTANCE_NAME)呼び出すと新しいインスタンスを作成して返します。

client.shutdown();

イベントを送信

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。 たとえば、「ボタンのクリック」は、追跡したいアクションかもしれません。Javaでは、logEventはイベントオブジェクトのみを受け入れます。利用可能なイベントオブジェクトキーについては、HTTP V2 APIを参照してください。

Amplitude client = Amplitude.getInstance();
client.logEvent(new Event("Button Clicked", "test_user_id"));

プロパティを持つイベント

イベントには、イベントに関するコンテキストを提供するプロパティも含めることができます。 たとえば、"ホバー時間"は、"ボタンのクリック"に関連するイベントプロパティである可能性があります。

JSONObject eventProps = new JSONObject()
    .put("Hover Time", 10)
    .put("prop_2", "value_2");
Event event = new Event("Button Clicked", userId);
event.eventProperties = eventProps;
client.logEvent(event);

グループによるイベント

Amplitudeでは、ユーザーをグループに割り当てたり、それらのグループに対して「ユニーク数による集計」などのクエリを実行したりすることができます。 グループの少なくとも1人のメンバーが特定のイベントを実行した場合、そのグループはカウントに含まれます。

たとえば、orgId を使用して、ユーザーが所属する組織に基づいてユーザーをグループ化したい場合などです。 ジョーはorgIdが10のグループに所属し、スーはorgIdが15のグループに所属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。

グループを設定する際には、groupTypeとgroupNameを定義してください。前の例では、orgId は groupTypeであり、10 と 15はgroupName の値です。groupTypeのもう1つの例としては、tennis および baseballのようなsport値を持つgroupName があります。

グループを設定すると、groupType:groupNameもユーザープロパティとして設定され、そのユーザーのgroupTypeに設定されている既存のgroupNameの値と対応するユーザープロパティ値が上書きされます。groupTypeは文字列であり、groupNameはユーザーが複数のグループに属していることを示す文字列または文字列の配列のいずれかを指定できます。

JSONObject groups = new JSONObject();
groups.put("orgId", 10);
Event setGroupEvent = new Event("$identify", userId);
setGroupEvent.groups = groups;
setGroupEvent.userProperties = groups;
client.logEvent(setGroupEvent);

JSONObject groups = new JSONObject();
groups.put("sport", new String[] {"tennis", "soccer"});
Event setGroupsEvent = new Event("$identify", userId);
setGroupsEvent.groups = groupProps;
setGroupsEvent.userProperties = groups;
client.logEvent(setGroupsEvent);

また、logEvent を使用してイベントレベルのグループを設定することもできます。 イベントレベルのグループの場合、グループの指定はログに記録する特定のイベントにのみ適用され、ユーザーに永続しません。

JSONObject groups = new JSONObject();
groups.put("orgId", 10);
Event event = new Event('event type', userId);
event.groups = groups;
client.logEvent(event);

グループを設定したあと、特定のグループのプロパティを設定または更新できます。これらの更新プログラムは今後のイベントにのみ影響します。

JSONObject groups = new JSONObject()
    .put("org", "engineering")
    .put("department", "sdk");
JSONObject groupProps = new JSONObject()
    .put("technology", "java")
    .put("location", "sf");
Event event = new Event("$groupidentify", userId);
event.groups = groups;
event.groupProperties = groupProps;
client.logEvent(event);

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

複数のユーザープロパティを一度に設定する場合の省略形としてevent.userPropertiesを使用します。

Event event = new Event("Button Clicked", "test_user_id");
JSONObject userProps = new JSONObject();
double[] arr = {1,2,4,8};
try {
  userProps.put("team", "red").put("running_times", arr);
} catch (JSONException e) {
  e.printStackTrace();
  System.err.println("Invalid JSON");
}
event.userProperties = userProps;
client.logEvent(event);

デバイス情報を設定する

Android SDKやiOS SDKとは異なり、Java SDKはデバイス情報を収集しません。デバイスID、デバイスブランド、デバイスメーカー、デバイスモデルなどのデバイス情報を、各イベントのプロパティとして設定します。

Event event = new Event("Button Clicked", "test_user_id");
event.deviceId = "device_id";
event.deviceBrand = "device_brand";
event.deviceManufacturer = "device_manufacturer";
event.deviceModel = "device_model";
client.logEvent(event);

セッション情報を設定する

イベント内でsessionIdを設定できます。このパターンは、cityやpriceなどの他のプロパティにも適用されます。イベント・プロパティの完全なリストは、Event.java で確認できます。

Event event = new Event("Button Clicked", "test_user_id");
event.sessionId = 1;
client.logEvent(event);

Amplitudeコールバック

AmplitudeCallBacksのサポートはバージョン1.4.0から開始されています。SDKがサーバーにイベントを送信した後、または再試行後にイベントが失敗した後にコールバックをトリガーできます。

Amplitude client = Amplitude.getInstance();
AmplitudeCallbacks callbacks =
  new AmplitudeCallbacks() {
  @Override
    public void onLogEventServerResponse(Event event, int status, String message) {
    // Event: Event processed.
    // status: response code, like 200, 400, and so on.
    // message: success or error message.
  }
};
client.setCallbacks(callbacks);

バージョン1.5.0以降では、イベントレベルでコールバックを追加できるようになりました。SDKは、イベントをサーバーに送信した後、または再試行後にイベントが失敗した後にこれらのコールバックをトリガーします。1 つのイベントでクライアントレベルのコールバックとイベントレベルのコールバックの両方をトリガーできます。

Amplitude client = Amplitude.getInstance();
AmplitudeCallbacks eventCallbacks =
  new AmplitudeCallbacks() {
  @Override
    public void onLogEventServerResponse(Event event, int status, String message) {
    // Event: Event processed.
    // status: response code, like 200, 400, and so on.
    // message: success or error message.
  }
};
client.logEvent(event, eventCallbacks)

ミドルウェア

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

各ミドルウェアは、runメソッドを持つインターフェイスです：

void run(MiddlewarePayload payload, MiddlewareNext next);

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

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

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

Java と Kotlin の例を参照してください。

トラブルシューティング

デバッグ時はログを確認してください。 SDKはエラーメッセージを出力します。

問題が発生した場合は、GitHubのissuesページで課題を開いてください。