Lua
이 가이드에서는 Lua SDK를 사용하여 프로젝트에 연동하는 방법을 소개합니다.
최신 버전: v2.0.1
업데이트 시간: 2026-01-08
리소스 다운로드: 소스 코드
이 문서는 v2.0.0 이상 버전에 적용됩니다. 과거 버전은 Lua SDK 연동 가이드(V1)를 참고하십시오
1. SDK 통합
- 소스 코드를 다운로드하고, 다운로드한 ThinkingDataSdk.lua 파일을 프로젝트 디렉터리에 넣습니다
- luarocks 관리 도구로 서드파티 라이브러리를 설치합니다:
luarocks install uuid 0.3-1
# luasec 라이브러리를 설치하려면 OPENSSL_DIR 경로를 지정해야 합니다
luarocks install luasec OPENSSL_DIR=[PATH]
luarocks install lua-cjson
- Logbus 설치
SDK+LogBus 방식으로 서버 측 데이터 수집 및 전송을 완료하는 것을 권장합니다. 다음 문서를 참고하여 Logbus를 설치할 수 있습니다: LogBus 사용 가이드
2. 초기화
다음은 SDK 초기화 예시 코드입니다.
local tdAnalytics = require "ThinkingDataSdk"
local consumer = tdAnalytics.TDLogConsumer("LOG_DIRECTORY", tdAnalytics.LOG_RULE.HOUR, 200, 500)
local sdk = tdAnalytics(consumer)
LOG_DIRECTORY는 로컬에 기록할 폴더 경로입니다. LogBus의 모니터링 폴더 경로를 이 경로로 설정하기만 하면 LogBus로 데이터를 모니터링하고 업로드할 수 있습니다.
3. 자주 사용하는 기능
게스트 ID와 계정 ID가 정상적으로 바인딩되도록, 게임에서 게스트 ID와 계정 ID를 모두 사용하는 경우 두 ID를 함께 전송할 것을 강력히 권장합니다. 그렇지 않으면 계정을 매칭할 수 없어 유저가 중복 집계될 수 있습니다. 구체적인 ID 바인딩 규칙은 유저 식별 규칙 장을 참고하십시오.
3.1 이벤트 전송
track을 호출하여 이벤트를 업로드할 수 있습니다. 앞서 정리한 문서에 따라 이벤트 속성과 정보 전송 조건을 설정하는 것을 권장합니다. 다음은 이벤트 전송 예시 코드입니다:
--게스트 ID 설정 "ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--계정 ID 설정 "AE_10001"
local accountId = "AE_10001"
--이벤트 속성 설정
local properties = {}
--이벤트 발생 시간을 설정합니다. 설정하지 않으면 기본적으로 현재 시간을 사용합니다
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--유저의 IP 주소를 설정합니다. AE 시스템은 IP 주소를 기반으로 유저의 지리적 위치 정보를 분석하며, 설정하지 않으면 기본적으로 전송하지 않습니다
properties["#ip"] = "192.168.1.1"
properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--이벤트를 업로드합니다. 유저의 게스트 ID와 계정 ID를 포함하며, 계정 ID와 게스트 ID의 순서에 주의하십시오
sdk:track(accountId, distinctId, "payment", properties)
- 이벤트 이름은 문자열 타입이며, 영문자로 시작해야 하고 숫자, 영문자, 밑줄 "_"을 포함할 수 있으며, 최대 길이는 50자입니다.
- Key는 해당 속성의 이름으로 문자열 타입입니다. 영문자로 시작해야 하며 숫자, 영문자, 밑줄 "_"을 포함할 수 있고, 최대 길이는 50자입니다. 대소문자를 구분하지 않으며 AE에서 모두 소문자로 변환합니다
- Value는 해당 속성의 값으로 문자열, 숫자, 불리언, 시간, 객체, 객체 그룹, 배열을 지원합니다
유저 속성의 요구 사항은 이벤트 속성과 같습니다
3.2 유저 속성 설정
일반적인 유저 속성은 userSet을 호출하여 설정할 수 있습니다. 이 인터페이스로 업로드한 속성은 기존 속성 값을 덮어쓰며, 이전에 해당 유저 속성이 없었다면 새로 생성하고 타입은 전달된 속성의 타입과 같습니다. 여기서는 사용자 이름 설정을 예로 듭니다:
--게스트 ID 설정 "ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--계정 ID 설정 "AE_10001"
local accountId = "AE_10001"
local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
--유저 속성 업로드
sdk:userSet(accountId, distinctId, userSetProperties)
userSetProperties = {}
userSetProperties["user_name"] = "abc"
--유저 속성을 다시 업로드합니다. 이때 "user_name"의 값은 "abc"로 덮어씁니다
sdk:userSet(accountId, distinctId, userSetProperties)
3.3 데이터 전송
TDLogConsumer를 사용하면 수집한 이벤트가 캐시 배열에 추가됩니다. 배열 요소 수가 설정한 용량을 초과할 때만 데이터를 디스크에 기록합니다. TDLogConsumer를 초기화할 때 batchNum 값을 명시적으로 전달해야 합니다.
일부 비즈니스 시나리오에서 데이터를 AE 서버로 즉시 전송하려면 flush() 인터페이스를 호출하면 됩니다. flush()를 자주 호출하면 서비스 성능이 저하되므로 주의하십시오.
sdk:flush()
3.4 SDK 종료
sdk:close()
SDK를 종료하고 빠져나옵니다. 캐시 안의 데이터가 유실되지 않도록 서버를 종료하기 전에 이 인터페이스를 호출하십시오
4. 모범 사례
다음 예시 코드에는 위의 모든 작업이 포함되어 있으며, 다음 단계에 따라 사용하는 것을 권장합니다.
local tdAnalytics = require "ThinkingDataSdk"
local consumer = tdAnalytics.TDLogConsumer("LOG_DIRECTORY", tdAnalytics.LOG_RULE.HOUR, 200, 500)
local sdk = tdAnalytics(consumer)
--게스트 ID 설정 "ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--계정 ID 설정 "AE_10001"
local accountId = "AE_10001"
--이벤트 속성 설정
local properties = {}
--이벤트 발생 시간을 설정합니다. 설정하지 않으면 기본적으로 현재 시간을 사용합니다
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--유저의 IP 주소를 설정합니다. AE 시스템은 IP 주소를 기반으로 유저의 지리적 위치 정보를 분석하며, 설정하지 않으면 기본적으로 전송하지 않습니다
properties["#ip"] = "192.168.1.1"
properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--이벤트를 업로드합니다. 유저의 게스트 ID와 계정 ID를 포함하며, 계정 ID와 게스트 ID의 순서에 주의하십시오
sdk:track(accountId, distinctId, "payment", properties)
local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
--유저 속성 업로드
sdk:userSet(accountId, distinctId, userSetProperties)
userSetProperties = {}
userSetProperties["user_name"] = "abc"
--유저 속성을 다시 업로드합니다. 이때 "user_name"의 값은 "abc"로 덮어씁니다
sdk:userSet(accountId, distinctId, userSetProperties)