# Erlang
本指南将会为您介绍如何使用 Erlang SDK 接入您的项目。
提示
在接入前, 请先阅读接入前准备。
最新版本为:v2.0.0
更新时间为:2023-10-08
资源下载: 源代码 (opens new window)
注意
当前文档适用于 v2.0.0 及以后的版本,历史版本请参考 Erlang SDK 接入指南(V1) (opens new window)
# 一、集成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, [
%% 添加数数采集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 库的配置,主要是增加数数SDK单独使用的sink:
ta_logger_lager_event
。如果您需要使用多实例写入到不同的日志文件,那么需要添加其它的sink。
[
%% lager日志库配置
{lager, [
{colored, true},
{log_root, "./log"}, %% 系统运行中产生的日志的存放路径
%% 这里增加一个数数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),
WARNING
Windows 平台注意事项:需要使用管理员权限打开命令行终端并运行项目,否则会出现数据写入错误。
我们推荐使用SDK+LogBus的形式,完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南
# 二、初始化
以下是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),
# 三、常用功能
为了保证访客 ID 与账号 ID 能够顺利进行绑定,如果您的游戏中会用到访客 ID 与账号 ID,我们极力建议您同时上传这两个 ID,否则将会出现账号无法匹配的情况,导致用户重复计算,具体的 ID 绑定规则可参考用户识别规则一章。
# 3.1 发送事件
您可以调用track
来上传事件,建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件,以下是发送事件的示例代码:
%% 注意account_id 和 distinct_id 必须至少设置其中一个
%% 设置用户的ip地址,TE系统会根据IP地址解析用户的地理位置信息,如果不设置的话,则默认不上报
%% 设置事件发生的时间,如果不设置的话,则默认使用为当前时间。注意:#time的类型必须是timestamp()类型
%% 上报事件
td_analytics:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct", #{"key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),
- 事件的名称是字符串类型,只能以字母开头,可包含数字,字母和下划线 "_",长度最大为 50 个字符。
- Key 为该属性的名称,为字符串类型,规定只能以字母开头,包含数字,字母和下划线 "_",长度最大为 50 个字符,对字母大小写不敏感,TE会统一转化为小写字母
- 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}),
# 四、最佳实践
以下示例代码包含以上所有操作,我们推荐按照如下步骤使用:
%% 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),