본문으로 건너뛰기

Python

최근 업데이트 2026. 08. 27.

이 가이드에서는 Python SDK로 프로젝트를 연동하는 방법을 소개합니다.

최신 버전: v3.0.0

업데이트 시간: 2023-10-07

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

주의

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

1. SDK 통합​

  1. pip로 Python SDK 가져오기
pip install ThinkingDataSdk

업그레이드 명령:

pip install --upgrade ThinkingDataSdk
  1. Logbus 설치

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

2. 초기화​

다음은 SDK 초기화 예시 코드입니다.

from tgasdk.sdk import *

consumer = TDLogConsumer("LOG_DIRECTORY", rotate_mode=TD_ROTATE_MODE.HOURLY, file_prefix="LOG_FILE_PREFIX")
te = TDAnalytics(consumer)

LOG_DIRECTORY는 로컬에 기록할 폴더 경로입니다. LogBus의 모니터링 폴더 경로를 이 경로로 설정하기만 하면 LogBus로 데이터를 모니터링하고 업로드할 수 있습니다.

LOG_FILE_PREFIX는 로그 파일 이름의 접두사입니다.

3. 자주 사용하는 기능​

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

3.1 이벤트 전송​

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

distinct_id = "ABCDEF123456"
account_id = "TE10001"
properties = {
    "#time": datetime.datetime.now(),
    # 이 event가 발생한 시간을 설정합니다. 설정하지 않으면 기본값은 현재 시간입니다
    "#ip": "192.168.1.1",
    # 유저의 IP를 설정합니다. tda가 이 IP를 기반으로 성/주, 도시를 자동으로 파싱합니다
    # "#uuid":uuid.uuid1(),#선택 입력. 위의 enable_uuid 스위치가 켜져 있으면 입력할 필요가 없습니다
    "Product_Name": "상품명",
    "Price": 30,
    "OrderId": "주문번호abc_123"
}
# 이벤트 업로드, 계정 ID와 게스트 ID 포함
try:
    te.track(distinct_id, account_id, "Payment", properties)
    # 게스트 ID만 업로드할 수도 있습니다
    # te.track(distinct_id = distinct_id, event_name = "Payment", properties = properties)
    # 또는 계정 ID만 업로드합니다
    # te.track(account_id = account_id, event_name = "Payment", properties = properties)
except Exception as e:
    # 예외 처리
    print(e)
  • 이벤트 이름은 문자열 타입이며, 영문자로 시작해야 하고 숫자, 영문자, 밑줄 "_"을 포함할 수 있으며, 최대 길이는 50자입니다.
  • Key는 해당 속성의 이름으로 문자열 타입입니다. 영문자로 시작해야 하며 숫자, 영문자, 밑줄 "_"을 포함할 수 있고, 최대 길이는 50자입니다. 대소문자를 구분하지 않으며 AE에서 모두 소문자로 변환합니다
  • Value는 해당 속성의 값으로 문자열, 숫자, 불리언, 시간, 객체, 객체 그룹, 배열을 지원합니다

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

3.2 유저 속성 설정​

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

properties = {"user_name": "ABC"}
# 유저 속성 업로드, "user_name"의 값은 "ABC"
try:
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
except Exception as e:
    # 예외 처리
    print(e)

3.3 데이터 전송​

TDLogConsumer를 사용하면 수집된 이벤트는 먼저 json 문자열로 변환된 후 캐시 배열에 추가됩니다. 배열 요소 수가 설정한 용량을 초과해야 데이터가 디스크에 기록됩니다. 기본 용량 제한은 데이터 5건이며, TDLogConsumer의 생성자에서 buffer_size의 크기를 설정할 수 있습니다.

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

te.flush();

3.4 SDK 종료​

te.close()

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

4. 모범 사례​

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

from tgasdk.sdk import *

# SDK 초기화
te = TDAnalytics(TDLogConsumer("LOG_DIRECTORY"))

# 이벤트 업로드, 계정 ID와 게스트 ID가 모두 비어 있으면 안 됨
properties = {
    "#time": datetime.datetime.now(),  # 이 event가 발생한 시간을 설정합니다. 설정하지 않으면 기본값은 현재 시간입니다
    "#ip": "192.168.1.1",  # 유저의 IP를 설정합니다. tda가 이 IP를 기반으로 성/주, 도시를 자동으로 파싱합니다
    "Product_Name": "상품명"
}
try:
    te.track("distinct_id", "account_id", "Payment", properties)
except Exception as e:
    # 예외 처리
    print(e)

# 유저 속성 업로드, "user_name"의 값은 "ABC"
user_properties = {"user_name": "ABC"}
try:
    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=user_properties)
except Exception as e:
    # 예외 처리
    print(e)

# flush 인터페이스를 호출하면 데이터가 즉시 파일에 기록됩니다. 운영 환경에서는 flush를 자주 호출하여 IO나 네트워크 오버헤드 문제가 발생하지 않도록 주의하십시오
te.flush()
이 문서가 도움이 되었나요?
이 페이지의 내용