Erlang

Last updated 10/05/2026

This guide shows you how to integrate the Erlang SDK into your project.

tip

Before you integrate the SDK, read Pre-integration preparation.

Latest version: v2.0.0

Update time: 2023-10-08

Downloads: Source code

Note

This document applies to v2.0.0 and later. For earlier versions, see Erlang SDK Integration Guide (V1)

1. Integrate the SDK

1. Your project must already have the rebar3 environment set up.
2. Modify your rebar.config file to add a reference to the thinkingdata_analytics SDK.

{erl_opts, [debug_info, 
    %% Required parameter for using the lager library
    {parse_transform, lager_transform},
    %% Declare the extra sinks here. For multiple sinks, write: [ta_logger, ta_logger_xxxx]
    {lager_extra_sinks, [ta_logger]}
]}.

{deps, [ 
    %% Add the ThinkingData SDK 
    {thinkingdata_analytics, {git, "https://github.com/ThinkingDataAnalytics/erlang-sdk.git", {tag, "v2.0.0"}}}
]}.

{shell, [ 
    %% Enable the configuration file
    {config, "config/example_sys.config"},
    {apps, [app_name]}
]}.

Tip: The SDK directory contains a sample file, example_sys.config, which you can use as a reference for configuration.

1. Run the command:

rebar3 compile

1. Modify your project's configuration file (for example, example_sys.config). In your configuration file, add the configuration for the lager library, mainly a sink used only by the ThinkingData SDK: ta_logger_lager_event. If you need multiple instances to write to different log files, add more sinks.

[
  %% lager logging library configuration
  {lager, [
    {colored, true},
    {log_root, "./log"}, %% Path where logs generated while the system runs are stored
    %% Add a sink used only by the ThinkingData SDK here. Its name is fixed as ta_logger_lager_event
    {extra_sinks,
      [
        {ta_logger_lager_event,
          [{handlers, [
            {lager_file_backend, [
              {file, "LOG_DIRECTORY"}, %% Configure the path and name of the file that stores collected data
              {level, info},
              {formatter, lager_default_formatter},
              {formatter_config, [message, "\n"]},
              {size, 10485760}, %% Rotation size of a single file: 10Mb
              {rotator, td_lager_rotator} %% Custom log rotation
            ]}]},
            {async_threshold, 500},
            {async_threshold_window, 50}
          ]
        }]
    }
  ]
  }
].

LOG_DIRECTORY is the path of the local folder that data is written to. Set the folder that LogBus monitors to this path, and LogBus monitors and uploads the data.

1. Configure the startup parameters in your app's project configuration file. Add the required startup items to the xxxx.app.src file.

{application, app_name,
 [{description, "An OTP application"},
  {vsn, "0.1.0"},
  {registered, []},
  {mod, {app_name_app, []}},
  {applications,
   [kernel,
    stdlib,
    jsone, %% Add the startup item here
    lager %% Add the startup item here
   ]},
  {env,[]},
  {modules, []},

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

1. Use the 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),

tip

Note for the Windows platform: Open the command-line terminal and run the project with administrator privileges. Otherwise, data write errors occur.

We recommend using SDK + LogBus to collect and report server-side data. To install Logbus, see the following document: LogBus user guide

2. Initialization

The following sample code initializes the 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. Common features

To make sure that the distinct ID and account ID can be bound correctly, if your game uses both the distinct ID and the account ID, we strongly recommend that you upload both IDs. Otherwise, accounts may fail to match and users may be counted more than once. For details on ID binding rules, see User identification rules.

3.1 Send events

You can call track to upload events. We recommend setting event properties and the conditions for sending events based on the document you prepared earlier. The following sample code sends an event:

%% Note: at least one of account_id and distinct_id must be set
%% Set the user's IP address. The AE system parses the user's geographic location from the IP address. If it isn't set, it isn't reported by default
%% Set the time when the event occurred. If it isn't set, the current time is used by default. Note: #time must be of the timestamp() type

%% Report an event
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" => ["🚌", "🏍", "😚😊"]}),

• The event name is of the string type. It must start with a letter, can contain digits, letters, and underscores "_", and can be up to 50 characters long.
• Key is the name of the property and is of string type. It must start with a letter, can contain digits, letters, and underscores "_", can be up to 50 characters long, and is case-insensitive. AE converts it to lowercase
• Value is the value of the property. Supported types are string, number, Boolean, time, object, object group, and array

User properties have the same requirements as event properties

3.2 Set user properties

For general user properties, you can call user_set_instance to set them. Properties uploaded through this API overwrite the original property values. If the user property doesn't exist yet, a new user property is created with the same type as the value passed in. The following example sets the username:

%% 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 Send data

When you use td_analytics:consumer_type_log(), the SDK writes collected data to disk in real time, so you don't need to call the flush() method.

3.4 Shut down the SDK

%% Call this when you shut down the SDK
td_analytics:close_instance(TE_SDK),

Shuts down and exits the SDK. Call this API before you shut down the server to avoid losing data in the cache

4. Best practices

The following sample code includes all of the operations above. We recommend using them in the following order:

%% 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),