본문으로 건너뛰기

Java

최근 업데이트 2026. 10. 03.
팁

연동하기 전에 먼저 연동 전 준비를 읽어 주십시오.

Java SDK는 최소 JDK 8 버전과 호환됩니다

최신 버전: v3.0.4-beta.1

업데이트 시간: 2026-01-07

리소스 다운로드: 소스 코드

주의

이 문서는 v3.0.0 이상 버전에 적용됩니다. 과거 버전은 Java SDK 연동 가이드(V2)를 참고하십시오

SDK의 API는 스레드 안전하며 기본적으로 동기 호출입니다. 전송하는 데이터 양이 많으면 비즈니스 스레드에 영향을 주지 않도록 하위 스레드에서 API를 호출할 수 있습니다.

1. SDK 통합​

1. Maven으로 SDK를 통합하려면 pom.xml 파일에 다음 의존성 정보를 추가하십시오:

<dependencies>
    // others...
    <dependency>
        <groupId>cn.thinkingdata</groupId>
        <artifactId>thinkingdatasdk</artifactId>
        <version>3.0.2</version>
    </dependency>
</dependencies>

2. Logbus 설치

SDK+LogBus 방식으로 서버 측 데이터 수집 및 전송을 완료하는 것을 권장합니다. 다음 문서를 참고하여 Logbus를 설치할 수 있습니다: LogBus 사용 가이드

2. 초기화​

방법 1​

TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"), false);

LOG_DIRECTORY는 데이터를 기록할 폴더 경로입니다.

방법 2​

SDK는 설정을 전달하여 초기화하는 방식을 지원하며, 설정으로 SDK 기능을 세밀하게 제어할 수 있습니다. 예를 들어 로그 파일에 접두사를 추가할 수 있습니다.

TDLoggerConsumer.Config config = new TDLoggerConsumer.Config("LOG_DIRECTORY");
config.setFilenamePrefix("unique_name");
TDAnalytics te = new TDAnalytics(new TDLoggerConsumer(config), false);

3. 자주 사용하는 기능​

게스트 ID와 계정 ID가 정상적으로 바인딩되도록, 게임에서 게스트 ID와 계정 ID를 모두 사용하는 경우 두 ID를 함께 전송할 것을 강력히 권장합니다. 그렇지 않으면 계정을 매칭할 수 없어 유저가 중복 집계될 수 있습니다. 구체적인 ID 바인딩 규칙은 유저 식별 규칙 장을 참고하십시오.

3.1 이벤트 전송​

track을 호출하여 이벤트를 업로드할 수 있습니다. 앞서 정리한 문서에 따라 이벤트 속성과 정보 전송 조건을 설정하는 것을 권장합니다. 다음은 이벤트 전송 예시 코드입니다:

//이벤트 속성 설정
HashMap<String,Object> properties = new HashMap<>();
// 유저의 ip 주소 설정, AE 시스템은 IP 주소를 기반으로 유저의 지리적 위치 정보를 해석함
properties.put("#ip", "192.168.1.1");//문자열
properties.put("channel","te");//문자열
properties.put("age",1);//숫자
properties.put("isSuccess",true);//불리언
properties.put("birthday",new Date());//시간

HashMap<String,Object>  object = new HashMap<>();
object.put("key", "value");
properties.put("object",object);//객체

HashMap<String,Object> object1 = new HashMap<>();
object1.put("key", "value");

ArrayList<Object> arr = new ArrayList<>();
arr.add(object1);
properties.put("object_arr",arr);//객체 그룹

ArrayList<String> arr1 = new ArrayList<>();
arr1.add("value");
properties.put("arr",arr1);//배열

try {
    te.track("account_id","distinct_id","payment",properties);
} catch (Exception e) {
    System.out.println("except:"+e);
}
  • 이벤트 이름은 문자열 타입이며, 영문자로 시작해야 하고 숫자, 영문자, 밑줄 "_"을 포함할 수 있으며, 최대 길이는 50자입니다.
  • Key는 해당 속성의 이름으로 문자열 타입입니다. 영문자로 시작해야 하며 숫자, 영문자, 밑줄 "_"을 포함할 수 있고, 최대 길이는 50자입니다. 대소문자를 구분하지 않으며 AE에서 모두 소문자로 변환합니다
  • Value는 해당 속성의 값으로 문자열, 숫자, 불리언, 시간, 객체, 객체 그룹, 배열을 지원합니다

유저 속성의 요구 사항은 이벤트 속성과 같습니다

3.2 유저 속성 설정​

일반적인 유저 속성은 userSet을 호출하여 설정할 수 있습니다. 이 인터페이스로 전송한 속성은 원래 속성 값을 덮어쓰며, 이전에 해당 유저 속성이 없었다면 새로 생성하고 타입은 전달된 속성의 타입과 같습니다. 여기서는 사용자 이름 설정을 예로 듭니다:

//이때 user_name은 TA
Map<String,Object> userProperties = new HashMap<String,Object>();
userProperties.put("user_name", "TA");
try {
   te.userSet("account_id","distinct_id",userProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}
 
//이때 user_name은 AE
Map<String,Object> newUserProperties = new HashMap<String,Object>();
newUserProperties.put("user_name", "AE");
try {
   te.userSet("account_id","distinct_id",newUserProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}

3.3 데이터 전송​

TDLogConsumer를 사용하면 수집한 이벤트는 먼저 json 문자열로 인코딩된 후 캐시에 추가됩니다. 캐시에 있는 문자열 길이가 설정한 길이를 초과해야 데이터가 디스크에 기록됩니다. 기본 최대 길이는 8192 byte입니다.

일부 비즈니스 시나리오에서 데이터를 AE 서버로 즉시 전송하려면 flush() 인터페이스를 호출하면 됩니다. flush()를 자주 호출하면 서비스 성능이 저하되므로 주의하십시오.

te.flush();

3.4 SDK 종료​

try{
   te.close();
} catch (Exception e) {
    System.out.println("except:"+e);
}

SDK를 종료하고 빠져나옵니다. 캐시 안의 데이터가 유실되지 않도록 서버를 종료하기 전에 이 인터페이스를 호출하십시오

4. 모범 사례​

다음 예시 코드에는 위의 모든 작업이 포함되어 있으며, 다음 단계에 따라 사용하는 것을 권장합니다.

//SDK 초기화, LOG_DIRECTORY는 로컬에 기록할 폴더 주소
TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"), false);

//이벤트 속성 설정
HashMap<String,Object> properties = new HashMap<>();
// 유저의 ip 주소 설정, AE 시스템은 IP 주소를 기반으로 유저의 지리적 위치 정보를 해석함
properties.put("#ip", "192.168.1.1");//문자열
properties.put("channel","te");//문자열
properties.put("age",1);//숫자
properties.put("isSuccess",true);//불리언
properties.put("birthday",new Date());//시간

HashMap<String,Object>  object = new HashMap<>();
object.put("key", "value");
properties.put("object",object);//객체

HashMap<String,Object> object1 = new HashMap<>();
object1.put("key", "value");

ArrayList<Object> arr = new ArrayList<>();
arr.add(object1);
properties.put("object_arr",arr);//객체 그룹

ArrayList<String> arr1 = new ArrayList<>();
arr1.add("value");
properties.put("arr",arr1);//배열

try {
    te.track("account_id","distinct_id","payment",properties);
} catch (Exception e) {
    System.out.println("except:"+e);
}

//유저 속성 설정
Map<String,Object> userProperties = new HashMap<String,Object>();
userProperties.put("user_name", "TE");
try {
   te.userSet("account_id","distinct_id",userProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}
이 문서가 도움이 되었나요?
이 페이지의 내용