본문으로 건너뛰기

OpenHarmony

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

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

SDK에 필요한 최소 시스템 버전은 API 10입니다

SDK(har 형식)의 크기는 약 56 KB입니다

SDK 이름: ThinkingData SDK

개발자: 数数信息科技(上海)有限公司

버전 번호: 2.0.0

기능: SDK는 이벤트와 유저 속성 방식으로 클라이언트 로그를 수집하며, DAU, 사용 시간, 리텐션 등 행동 분석 통계 기능을 제공합니다.

개인정보 처리방침: ThinkingData SDK 개인정보 처리방침

규정 준수 가이드: ThinkingData SDK 규정 준수 가이드

최신 버전: 2.0.0

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

SDK 패키지 이름: @thinkingdata/analytics

MD5 값: 997d05310dbe82eb02b1536deeb4645f

업데이트 시간: 2026-08-19

1. SDK 통합​

  1. SDK 가져오기
  • 다음 명령을 실행합니다
ohpm i @thinkingdata/analytics
  • oh-package.json5의 dependencies 아래에 의존성을 수동으로 추가합니다. 그러면 IDE에 ohpm install 안내가 표시되며, 클릭하여 설치합니다
"dependencies": {
  "@thinkingdata/analytics": "2.0.0",
}

2. 초기화​

import { TDAnalytics, TDConfig, TDMode } from '@thinkingdata/analytics';

//방식 1
TDAnalytics.init(context, "appId", "serverUrl")

//방식 2
let config = new TDConfig()
config.appId = 'appId'
config.serverUrl = 'serverUrl'
config.mode = TDMode.NORMAL
config.enableAutoCalibrated = true
TDAnalytics.initWithConfig(context, config)

SDK는 초기화할 때 OS 버전, 디바이스 제조사, 운영 체제, 화면 해상도, 디바이스 모델, APP 버전, 네트워크 상태, 네트워크 통신사, 앱 설치 시간, 시스템 언어 등의 정보를 수집하며, 이는 통계 분석 기능에 사용됩니다.

파라미터 설명:

  • APPID: 프로젝트의 APPID로, AE 프로젝트 관리 페이지에서 확인할 수 있습니다

  • SERVER_URL: 데이터 전송 URL

    • 클라우드 서비스를 사용하는 경우 프로젝트 관리 -> 연동 설정에서 수집 주소를 확인하십시오.
    • 프라이빗 배포 버전을 사용하는 경우 데이터 수집 주소를 직접 지정할 수 있습니다.

  • mode: SDK 전송 모드이며, 기본값은 Normal 모드입니다.

  • enableAutoCalibrated : 시간 보정을 자동으로 활성화합니다.

3. 자주 사용하는 기능​

자주 사용하는 기능을 사용하기 전에 먼저 유저 식별 규칙을 이해하는 것을 권장합니다. SDK는 기본적으로 난수를 생성하여 게스트 ID로 사용하고, 게스트 ID를 로컬에 영구 저장합니다. 유저가 로그인하기 전에는 게스트 ID가 신원 식별 ID로 사용됩니다. 참고: 게스트 ID는 유저가 앱을 재설치하거나 디바이스를 변경하면 바뀝니다.

3.1 계정 ID 설정​

유저가 로그인할 때 login을 호출하여 유저의 계정 ID를 설정할 수 있습니다. AE 플랫폼은 계정 ID를 신원 식별 ID로 사용하며, 설정한 계정 ID는 logout을 호출하기 전까지 계속 유지됩니다. login을 여러 번 호출하면 이전 계정 ID를 덮어씁니다.

// 유저의 로그인 고유 식별자로, 전송 데이터의 #account_id에 해당합니다. 이때 #account_id의 값은 TA입니다
TDAnalytics.login("TA");

이 메서드는 로그인 이벤트를 전송하지 않습니다

3.2 공통 이벤트 속성 설정​

공통 이벤트 속성은 모든 이벤트에 포함되는 속성입니다. setSuperProperties를 호출하여 공통 이벤트 속성을 설정할 수 있으며, 이벤트를 보내기 전에 먼저 공통 이벤트 속성을 설정하는 것을 권장합니다. 유저의 회원 등급, 유입 채널 등 일부 중요한 속성은 모든 이벤트에 설정해야 하므로, 이러한 속성은 공통 이벤트 속성으로 설정할 수 있습니다.

let superProperties = {};
superProperties["channel"] = "ta";//문자열
superProperties["age"] = 1;//숫자
superProperties["isSuccess"] = true;//불리언
superProperties["birthday"] = new Date();//시간
superProperties["object"] = {key:"value"};//객체
superProperties["object_arr"] = [{key:"value"}];//객체 그룹
superProperties["arr"] = ["value"];//배열
TDAnalytics.setSuperProperties(superProperties)

공통 이벤트 속성은 캐시에 저장되므로 앱을 시작할 때마다 호출할 필요가 없습니다. setSuperProperties를 호출하여 이전에 이미 설정한 공통 이벤트 속성을 전송하면 이전 속성을 덮어씁니다.

3.3 자동 수집 활성화​

enableAutoTrack은 onWindowStageCreate 이후에 활성화하는 것을 권장합니다. 다음 코드 예시는 모든 자동 수집 이벤트를 활성화합니다:

//APP 설치 이벤트 TDAutoTrackEventType.APP_INSTALL
//APP 시작 이벤트 TDAutoTrackEventType.APP_START
//APP 종료 이벤트 TDAutoTrackEventType.APP_END
//APP 페이지 조회 이벤트 TDAutoTrackEventType.APP_VIEW_SCREEN
//APP 컨트롤 클릭 이벤트 TDAutoTrackEventType.APP_CLICK
//APP 크래시 이벤트 TDAutoTrackEventType.APP_CRASH
TDAnalytics.enableAutoTrack(context,TDAutoTrackEventType.APP_START | TDAutoTrackEventType.APP_INSTALL | TDAutoTrackEventType.APP_END | TDAutoTrackEventType.APP_VIEW_SCREEN | TDAutoTrackEventType.APP_CLICK | TDAutoTrackEventType.APP_CRASH)

3.4 이벤트 전송​

track을 호출하여 이벤트를 전송할 수 있습니다. 앞서 정리한 트래킹 문서에 따라 이벤트 속성을 설정하는 것을 권장합니다. 여기서는 유저가 어떤 상품을 구매하는 경우를 예로 듭니다.

TDAnalytics.track({
  eventName: 'product_buy',
  properties: {
      product_name:"상품명"
  }
})

이벤트 이름은 문자열 타입이며, 영문자로만 시작할 수 있고 숫자, 영문자, 밑줄 "_"을 포함할 수 있습니다.

3.5 유저 속성 설정​

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

// username은 TA
TDAnalytics.userSet({
  properties: {
    username: "TA"
  }
})
//username은 AE
TDAnalytics.userSet({
  properties: {
    username: "AE"
  }
})

4. 모범 사례​

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

import { TDAnalytics, TDConfig, TDMode, TDAutoTrackEventType } from '@thinkingdata/analytics';
let config = new TDConfig()
config.appId = 'appId'
config.serverUrl = 'serverUrl'
config.enableAutoCalibrated = true
config.mode = TDMode.NORMAL
// 초기화
TDAnalytics.initWithConfig(context, config)
//자동 수집 활성화
TDAnalytics.enableAutoTrack(context,TDAutoTrackEventType.APP_START | TDAutoTrackEventType.APP_INSTALL | TDAutoTrackEventType.APP_END | TDAutoTrackEventType.APP_VIEW_SCREEN | TDAutoTrackEventType.APP_CLICK | TDAutoTrackEventType.APP_CRASH)
// 유저의 로그인 고유 식별자로, 전송 데이터의 #account_id에 해당합니다. 이때 #account_id의 값은 TA입니다
TDAnalytics.login("TA");
//공통 이벤트 속성 설정
let superProperties = {
    channel : "ta", //문자열
    age : 1,//숫자
    isSuccess : true,//불리언
    birthday :  new Date(),//시간
    object : { key : "value" },//객체
    object_arr : [ { key : "value" } ],//객체 그룹
    arr : [ "value" ]//배열
};
TDAnalytics.setSuperProperties(superProperties);
//이벤트 전송
TDAnalytics.track({
    eventName: "product_buy", // 이벤트 이름
    properties: {
        product_name: "상품명"
    } //이벤트 속성
});
//유저 속성 설정
TDAnalytics.userSet({
    properties: { 
        username: "AE" 
    }
});
이 문서가 도움이 되었나요?
이 페이지의 내용