Erlang

本指南将会为您介绍如何使用 Erlang SDK 接入您的项目。

提示

在接入前, 请先阅读接入前准备。

最新版本为：1.3.0

更新时间为：2023-03-23

资源下载: 源代码 (opens new window)

一、集成SDK

v1.3.0 以及之后的版本，支持多实例

1.1: 需要您的项目已经引入 rebar3 环境。

1.2:修改您项目的配置文件，在您的配置文件中，添加对 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, ta_lager_rotator} %% 自定义日志轮转
            ]}]},
            {async_threshold, 500},
            {async_threshold_window, 50}
          ]
        }]
    }
  ]
  }
].

提示：在SDK目录中有示例文件 example_sys.config，可以参考示例配置。

LOG_DIRECTORY为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

1.3：修改您的 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, "v1.3.0"}}}
]}.

{shell, [ 
    %% 启用配置文件
    {config, "config/sys.config"},
    {apps, [app_name]}
]}.

执行命令：

rebar3 compile

1.4：在您的app项目配置文件中配置启动参数。在 xxxx.app.src 文件中添加数数SDK的启动项。

{application, your_name,
 [{description, "An OTP application"},
  {vsn, "0.1.0"},
  {registered, []},
  {mod, {your_name_app, []}},
  {applications,
   [kernel,
    stdlib,
    thinkingdata_analytics %% 这里添加数数SDK
   ]},
  {env,[]},
  {modules, []},

  {licenses, ["Apache-2.0"]},
  {links, []}
 ]}.

1.5: 单实例使用方式：

%% init consumer
%% A lager sink is provided by default: 'ta_logger'. You could add your own sink
Consumer = ta_consumer_log:init_with_logger(fun(E) -> ta_logger:info(E) end),
%% init SDK with consumer
TE_SDK = thinking_analytics_sdk:init_with_consumer(Consumer),

thinking_analytics_sdk:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct_1", #{"key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),

1.6: 多实例使用方式：

%% init consumer
%% A lager sink is provided by default: 'ta_logger'. You could add your own sink
Consumer = ta_consumer_log:init_with_logger(fun(E) -> ta_logger:info(E) end),
%% init SDK with consumer
TE_SDK = thinking_analytics_sdk:init_with_consumer(Consumer),

%% init consumer 1
%% You could add your own sink. e.g. 'ta_logger_1'. it is must define in lager config file
Consumer1 = ta_consumer_log:init_with_logger(fun(E) -> ta_logger:info(E) end),
%% init SDK with consumer
TE_SDK1 = thinking_analytics_sdk:init_with_consumer(Consumer1),

thinking_analytics_sdk:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct_1", #{"key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),
thinking_analytics_sdk:track_instance(TE_SDK1, "account_id_Erlang", "distinct_logbus", "ViewProduct_1", #{"key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),

v1.2.0 以及之后的新版本，采用 rebar3 引入。（不推荐使用）

1.1: 需要您的项目已经引入 rebar3 环境。

1.2：修改您项目的配置文件，在您的配置文件中，添加对 lager 库的配置，主要是增加一个数数SDK单独使用的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, ta_lager_rotator} %% 自定义日志轮转
            ]}]},
            {async_threshold, 500},
            {async_threshold_window, 50}
          ]
        }]
    }
  ]
  }
].

提示：在SDK目录中有示例文件 example_sys.config，可以参考示例配置。

LOG_DIRECTORY为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

1.3: 修改您的 rebar.config 文件，添加对 thinkingdata_analytics SDK 的引用。

{erl_opts, [debug_info, 
    %% 使用 lager 库所必须的参数
    {parse_transform, lager_transform},
    {lager_extra_sinks, [ta_logger]}
]}.

{deps, [ 
    %% 添加数数采集SDK 
    {thinkingdata_analytics, {git, "https://github.com/ThinkingDataAnalytics/erlang-sdk.git", {tag, "v1.3.0"}}}
]}.

{shell, [ 
    %% 启用配置文件
    {config, "config/sys.config"},
    {apps, [app_name]}
]}.

执行命令：

rebar3 compile

1.4：在您的app项目配置文件中配置启动参数。在 xxxx.app.src 文件中添加数数SDK的启动项。

{application, your_name,
 [{description, "An OTP application"},
  {vsn, "0.1.0"},
  {registered, []},
  {mod, {your_name_app, []}},
  {applications,
   [kernel,
    stdlib,
    thinkingdata_analytics %% 这里添加数数SDK
   ]},
  {env,[]},
  {modules, []},

  {licenses, ["Apache-2.0"]},
  {links, []}
 ]}.

v1.1.2 以及之前的版本 (不建议使用)。

我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南

二、初始化

以下是SDK初始化的示例代码:

%% init consumer
%% A lager sink is provided by default: 'ta_logger'. You could add your own sink
Consumer = ta_consumer_log:init_with_logger(fun(E) -> ta_logger:info(E) end),
%% init SDK with consumer
TE_SDK = thinking_analytics_sdk:init_with_consumer(Consumer),

三、常用功能

为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

3.1 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:

%% 注意account_id 和 distinct_id 必须至少设置其中一个
%% 设置用户的ip地址，TE系统会根据IP地址解析用户的地理位置信息，如果不设置的话，则默认不上报
%% 设置事件发生的时间，如果不设置的话，则默认使用为当前时间。注意：#time的类型必须是timestamp()类型

%% 上报事件
thinking_analytics_sdk:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct_1", #{"key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),

• 事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
• Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TE会统一转化为小写字母
• Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

用户属性的要求与事件属性保持一致

3.2 设置用户属性

对于一般的用户属性，您可以调用 user_set 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

thinking_analytics_sdk: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}),

四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

%% init consumer
%% A lager sink is provided by default: 'ta_logger'. You could add your own sink
Consumer = ta_consumer_log:init_with_logger(fun(E) -> ta_logger:info(E) end),
%% init SDK with consumer
TE_SDK = thinking_analytics_sdk:init_with_consumer(Consumer),

%% ordinary event
thinking_analytics_sdk:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct", #{"key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),
%% nested properties event
thinking_analytics_sdk:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct", #{"custom_property_1" => [#{"key_1" => "value_1"}, #{"key_2" => "value_2"}, #{"key_3_list" => ["a", "b", #{"unicode_key" => "🙂🆒😊"}]}]}),
%% ⚠️ if your properties include time, please use ta_utils:format_time().
%% include time
thinking_analytics_sdk:track_instance(TE_SDK, "account_id_Erlang", "distinct_id", "ViewProduct", #{"register_time" => ta_utils:format_time(os:timestamp())}),

thinking_analytics_sdk:close_instance(TE_SDK),