JRE Java SDK

이 문서는 Amplitude 애널리틱스 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가 https://api2.amplitude.com/batch의 배치 이벤트 업로드 API로 설정됩니다. 일반 모드와 배치 모드 모두 동일한 플러시 대기열 크기와 플러시 간격을 사용합니다.

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는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 실행할 수 있도록 지원합니다. 그룹 구성원 중 하나 이상이 특정 이벤트를 수행하는 경우 해당 그룹도 수행 회수가에 포함됩니다.

예를 들어 orgId를 사용하여 사용자가 속한 조직을 기준으로 사용자를 그룹화하려는 경우가 있습니다. Joe는 orgId 10에 속하고, Sue는 orgId 15에 속합니다. Sue와 Joe는 둘 다 특정 이벤트를 수행합니다. 이벤트 세분화 차트에서 해당 조직을 쿼리할 수 있습니다.

그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예시에서 orgId는 groupType이고 10와 15은 groupName의 값입니다. groupType의 또 다른 예로는 sport이 있으며, groupName 값은 tennis 및 baseball와 같이 구성됩니다.

그룹을 설정하면 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는 이벤트를 서버에 전송한 후 또는 재시도 후 이벤트가 실패한 후 이를 트리거합니다. 하나의 이벤트가 클라이언트 수준 콜백과 이벤트 수준 콜백을 모두 트리거할 수 있습니다.

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 이슈 페이지에서 이슈를 열어보십시오.