Erlang
이 가이드에서는 Erlang SDK를 사용하여 프로젝트에 연동하는 방법을 소개합니다.
연동하기 전에 먼저 연동 전 준비를 읽어 주십시오.
최신 버전: v2.0.0
업데이트 시간: 2023-10-08
리소스 다운로드: 소스 코드
이 문서는 v2.0.0 이상 버전에 적용됩니다. 과거 버전은 Erlang SDK 연동 가이드(V1)를 참고하십시오
1. SDK 통합
- 프로젝트에 rebar3 환경이 이미 도입되어 있어야 합니다.
rebar.config파일을 수정하여 thinkingdata_analytics SDK에 대한 참조를 추가합니다.
{erl_opts, [debug_info,
%% lager 라이브러리 사용에 필요한 파라미터
{parse_transform, lager_transform},
%% 여기서 확장 sink를 선언해야 함. sink가 여러 개라면 다음과 같이 작성: [ta_logger, ta_logger_xxxx]
{lager_extra_sinks, [ta_logger]}
]}.
{deps, [
%% ThinkingData 수집 SDK 추가
{thinkingdata_analytics, {git, "https://github.com/ThinkingDataAnalytics/erlang-sdk.git", {tag, "v2.0.0"}}}
]}.
{shell, [
%% 설정 파일 활성화
{config, "config/example_sys.config"},
{apps, [app_name]}
]}.
참고: SDK 디렉터리에 예시 파일
example_sys.config가 있으므로 예시 설정을 참고할 수 있습니다.
- 다음 명령을 실행합니다:
rebar3 compile
- 프로젝트의 설정 파일(예: example_sys.config)을 수정합니다. 설정 파일에 lager 라이브러리 설정을 추가하며, 주로 ThinkingData SDK 전용 sink인
ta_logger_lager_event를 추가합니다. 여러 인스턴스를 사용하여 서로 다른 로그 파일에 기록해야 한다면 다른 sink도 추가해야 합니다.
[
%% lager 로그 라이브러리 설정
{lager, [
{colored, true},
{log_root, "./log"}, %% 시스템 실행 중 생성되는 로그의 저장 경로
%% 여기에 ThinkingData SDK 전용 sink를 추가함. 이름은 ta_logger_lager_event로 고정
{extra_sinks,
[
{ta_logger_lager_event,
[{handlers, [
{lager_file_backend, [
{file, "LOG_DIRECTORY"}, %% 수집 데이터를 저장할 파일 경로와 이름 설정
{level, info},
{formatter, lager_default_formatter},
{formatter_config, [message, "\n"]},
{size, 10485760}, %% 단일 파일의 분할 크기 10Mb
{rotator, td_lager_rotator} %% 커스텀 로그 로테이션
]}]},
{async_threshold, 500},
{async_threshold_window, 50}
]
}]
}
]
}
].
LOG_DIRECTORY는 로컬에 기록할 폴더 경로입니다. LogBus의 모니터링 폴더 경로를 이 경로로 설정하기만 하면 LogBus로 데이터를 모니터링하고 업로드할 수 있습니다.
- app 프로젝트 설정 파일에서 시작 파라미터를 설정합니다.
xxxx.app.src파일에 필요한 시작 항목을 추가합니다.
{application, app_name,
[{description, "An OTP application"},
{vsn, "0.1.0"},
{registered, []},
{mod, {app_name_app, []}},
{applications,
[kernel,
stdlib,
jsone, %% 여기에 시작 항목 추가
lager %% 여기에 시작 항목 추가
]},
{env,[]},
{modules, []},
{licenses, ["Apache-2.0"]},
{links, []}
]}.
- SDK를 사용합니다:
%% A lager sink is provided by default: 'ta_logger'. You could add your own sink
Consumer = td_log_consumer:init_with_logger(fun(E) -> ta_logger:info(E) end),
%% init SDK with consumer
TE_SDK = td_analytics:init_with_consumer(Consumer),
Windows 플랫폼 주의 사항: 관리자 권한으로 명령줄 터미널을 열고 프로젝트를 실행해야 합니다. 그렇지 않으면 데이터 기록 오류가 발생합니다.
SDK+LogBus 방식으로 서버 측 데이터 수집 및 전송을 완료하는 것을 권장합니다. 다음 문서를 참고하여 Logbus를 설치할 수 있습니다: LogBus 사용 가이드
2. 초기화
다음은 SDK 초기화 예시 코드입니다.
%% A lager sink is provided by default: 'ta_logger'. You could add your own sink
Consumer = td_log_consumer:init_with_logger(fun(E) -> ta_logger:info(E) end),
%% init SDK with consumer
TE_SDK = td_analytics:init_with_consumer(Consumer),
3. 자주 사용하는 기능
게스트 ID와 계정 ID가 정상적으로 바인딩되도록, 게임에서 게스트 ID와 계정 ID를 모두 사용하는 경우 두 ID를 함께 전송할 것을 강력히 권장합니다. 그렇지 않으면 계정을 매칭할 수 없어 유저가 중복 집계될 수 있습니다. 구체적인 ID 바인딩 규칙은 유저 식별 규칙 장을 참고하십시오.
3.1 이벤트 전송
track을 호출하여 이벤트를 업로드할 수 있습니다. 앞서 정리한 문서에 따라 이벤트 속성과 정보 전송 조건을 설정하는 것을 권장합니다. 다음은 이벤트 전송 예시 코드입니다:
%% 주의: account_id와 distinct_id 중 하나 이상을 반드시 설정해야 함
%% 유저의 ip 주소 설정. AE 시스템은 IP 주소를 해석하여 유저의 지리적 위치 정보를 얻으며, 설정하지 않으면 기본적으로 전송하지 않음
%% 이벤트 발생 시간 설정. 설정하지 않으면 기본적으로 현재 시간을 사용함. 주의: #time의 타입은 반드시 timestamp() 타입이어야 함
%% 이벤트 전송
td_analytics:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct", #{"#ip" => "192.168.1.1", "#time" => os:timestamp(), "key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),
- 이벤트 이름은 문자열 타입이며, 영문자로 시작해야 하고 숫자, 영문자, 밑줄 "_"을 포함할 수 있으며, 최대 길이는 50자입니다.
- Key는 해당 속성의 이름으로 문자열 타입입니다. 영문자로 시작해야 하며 숫자, 영문자, 밑줄 "_"을 포함할 수 있고, 최대 길이는 50자입니다. 대소문자를 구분하지 않으며 AE에서 모두 소문자로 변환합니다
- Value는 해당 속성의 값으로 문자열, 숫자, 불리언, 시간, 객체, 객체 그룹, 배열을 지원합니다
유저 속성의 요구 사항은 이벤트 속성과 같습니다
3.2 유저 속성 설정
일반적인 유저 속성은 user_set_instance를 호출하여 설정할 수 있습니다. 이 인터페이스로 업로드한 속성은 원래 속성 값을 덮어쓰며, 이전에 해당 유저 속성이 없었다면 새로 생성하고 타입은 전달된 속성의 타입과 같습니다. 여기서는 사용자 이름 설정을 예로 듭니다.
%% user properties
td_analytics:user_set_instance(TE_SDK, "account_id_Erlang", "distinct_id", #{"id" => 12, "key_1" => [1,1,1,1], "key_2" => ["a", "b"], "key_3" => ["中", "文"], "key_4" => ["中文", "list"], "key_5" => "中文字符串", "amount" => 7.123}),
3.3 데이터 전송
td_analytics:consumer_type_log()를 사용하면 SDK는 수집한 데이터를 실시간으로 디스크에 기록하므로 flush() 메서드를 호출할 필요가 없습니다.
3.4 SDK 종료
%% SDK를 종료할 때 호출해야 함
td_analytics:close_instance(TE_SDK),
SDK를 종료하고 빠져나옵니다. 캐시 안의 데이터가 유실되지 않도록 서버를 종료하기 전에 이 인터페이스를 호출하십시오
4. 모범 사례
다음 예시 코드에는 위의 모든 작업이 포함되어 있으며, 다음 단계에 따라 사용하는 것을 권장합니다.
%% A lager sink is provided by default: 'ta_logger'. You could add your own sink
Consumer = td_log_consumer:init_with_logger(fun(E) -> ta_logger:info(E) end),
%% init SDK with consumer
TE_SDK = td_analytics:init_with_consumer(Consumer),
%% ordinary event
td_analytics:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct", #{"key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),
td_analytics:close_instance(TE_SDK),