跳到主要内容

Unreal

最近更新 2026/10/03
提示

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

TDAnalytics 实现了虚幻引擎内置的 Analytics 服务，同时也支持直接通过 C++ 代码调用接口上报数据。目前支持 Android、iOS、 Windows 和 macOS 平台。支持虚幻引擎4.26+和5.+版本。

最新版本: v3.0.3

更新时间: 2025-10-11

资源下载: 源码、SDK下载

注意

当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 Unreal 接入指南（V1），SDK下载（v1.6.0）

一、集成SDK​

1.1 集成 TDAnalytics 插件​

下载 Unreal SDK，解压后将 TDAnalytics 放入您项目的 Plugins 目录； 如果 Plugins 目录不存在，首先在项目根目录下创建 Plugins 目录，然后将 TDAnalytics 目录放入其中。

1.2 激活 TDAnalytics 插件​

为了启用 TDAnalytics 插件，你需要执行以下步骤：

  • 重启 Unreal Editor

  • 打开 编辑 > 插件，在项目 Analytics 类别下，启用 TDAnalytics

  • 如果您使用 Blueprint，请启用内置 Analytics 类别下的 Analytics Blueprint Library

  • 再次重启 Unreal Editor

  • 打开 编辑>项目设置，在插件类别下，设置 TDAnalytics 参数：

    • Server Url: 必填。接收端地址，需使用 https 类型的地址
    • App ID: 必填。您项目的 APP ID，在 AE 后台项目管理页可以查看
    • TimeZone: 可选，如果需要对齐时区，请填写规范的 TimeZone ID，例如"UTC01:00". 不需要对齐时区的情况下，不需要填写
    • Enable Encrypt: 是否开启数据加密 默认false，开启后数据会加密后上传到 AE
    • EncryptPublicKey: 可选，不填则使用默认配置，加密公钥
    • EncryptVersion: 可选，不填则使用默认配置，密钥版本
    • SymmetricEncryption: 可选，不填则使用默认配置，对称密钥
    • AsymmetricEncryption: 可选，不填则使用默认配置，非对称密钥

注意：Windows/MacOS 暂不支持对齐时区。

  • 在 Config 目录下的 DefaultEngine.ini 文件中添加以下内容:
[Analytics]
ProviderModuleName=TDAnalytics
  • 如果您希望直接在 C++ 代码中使用 TDAnalytics 接口，需要在您项目的 *.Build.cs 文件中添加以下内容：
PrivateDependencyModuleNames.AddRange(new string[] { "TDAnalytics" });
PrivateIncludePathModuleNames.AddRange(new string[] { "TDAnalytics" });

并且，在您希望使用 SDK 的文件中引用 TDAnalytics.h 头文件:

#include "TDAnalytics.h"

二、初始化​

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

// 初始化 SDK
UTDAnalytics::Initialize();

初始化完成之后，就可以使用 SDK 上报事件了。

三、常用功能​

在使用常用功能之前，建议你先了解用户识别规则；SDK默认会生成随机数作为访客ID，并持久化存储访客ID在本地；用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在用户重新安装 App 以及更换设备时将会变更。

3.1 设置账号ID​

在用户进行登录时，可调用 Login 来设置用户的账号 ID， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 Logout 之前一直保留。多次调用 Login 将覆盖先前的账号 ID 。

// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
UTDAnalytics::Login("TA");

Login 可以多次调用，每次调用会判断传入的账号 ID 与先前保存的 ID 是否一致，一致则忽略调用，不一致则会覆盖先前的 ID。

该方法不会上传登录事件

3.2 设置公共事件属性​

公共事件属性指的就是每个事件都会带有的属性，您可以调用 SetSuperProperties 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。

    TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
    Properties->SetStringField("channel", "ta");//字符串
    Properties->SetNumberField("age", 1);//数字
    Properties->SetBoolField("isSuccess", true);//布尔
    FDateTime DateTime = FDateTime::Now();
    Properties->SetStringField("birthday", FDateTime::FromUnixTimestamp(DateTime.ToUnixTimestamp()).ToString(TEXT("%Y-%m-%d %H:%M:%S.")) += *FString::Printf(TEXT("%03d"), DateTime.GetMillisecond()));//时间

    TSharedPtr<FJsonObject> ItemProperties = MakeShareable(new FJsonObject);
    ItemProperties->SetStringField("itemChannel", "item");
    Properties->SetObjectField("object", ItemProperties);//对象

    TArray< TSharedPtr<FJsonValue> > DataObjectArray;
    TSharedPtr<FJsonObject> ArrayItemProperties = MakeShareable(new FJsonObject);
    ArrayItemProperties->SetStringField("arrayItemChannel", "array_item");
    TSharedPtr<FJsonValueObject> DataObjectValue = MakeShareable(new FJsonValueObject(ArrayItemProperties));
    DataObjectArray.Add(DataObjectValue);
    Properties->SetArrayField("object_arr", DataObjectArray);//对象组

    TArray< TSharedPtr<FJsonValue> > DataArray;
    TSharedPtr<FJsonValueString> DataValue = MakeShareable(new FJsonValueString("data_value"));
    DataArray.Add(DataValue);
    Properties->SetArrayField("arr", DataArray);//数组

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

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

3.3 开启自动采集​

以下代码示例开启安装、启动、关闭事件（PC端不支持自动采集），如果您想详细了解SDK的自动采集能力，可以查看自动采集功能详细介绍

// 开启自动采集
UTDAnalytics::EnableAutoTrack();

3.4 发送事件​

您可以调用 Track 来上传事件，建议您根据先前梳理的埋点文档来设置事件的属性以及发送信息的条件，此处以用户购买某商品作为范例：

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("product_name", "商品名");//字符串
// 上报一个带属性的事件
UTDAnalytics::Track("product_buy", Properties);

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。

3.5 设置用户属性​

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

 //此时"username"为"TA"
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("username", "TA");//字符串
UTDAnalytics::UserSet(Properties);
//此时"username"为"AE"
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetStringField("username", "AE");//字符串
UTDAnalytics::UserSet(NewProperties);

四、最佳实践​

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

#include "TDAnalytics.h"
if (isPrivacyPolicyAccepted) { // 用户已同意《隐私政策》
   //初始化 SDK
   UTDAnalytics::Initialize();
   // 开启自动采集事件
   UTDAnalytics::EnableAutoTrack();
   //如果用户已登录，可以设置用户的账号ID作为身份唯一标识
   UTDAnalytics::Login("TA");
   //设置公共事件属性
   TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
   Properties->SetStringField("channel", "ta");//字符串
   Properties->SetNumberField("age", 1);//数字
   Properties->SetBoolField("isSuccess", true);//布尔
   FDateTime DateTime = FDateTime::Now();
   Properties->SetStringField("birthday", FDateTime::FromUnixTimestamp(DateTime.ToUnixTimestamp()).ToString(TEXT("%Y-%m-%d %H:%M:%S.")) += *FString::Printf(TEXT("%03d"), DateTime.GetMillisecond()));//时间

   TSharedPtr<FJsonObject> ItemProperties = MakeShareable(new FJsonObject);
   ItemProperties->SetStringField("itemChannel", "item");
   Properties->SetObjectField("object", ItemProperties);//对象

   TArray< TSharedPtr<FJsonValue> > DataObjectArray;
   TSharedPtr<FJsonObject> ArrayItemProperties = MakeShareable(new FJsonObject);
   ArrayItemProperties->SetStringField("arrayItemChannel", "array_item");
   TSharedPtr<FJsonValueObject> DataObjectValue = MakeShareable(new FJsonValueObject(ArrayItemProperties));
   DataObjectArray.Add(DataObjectValue);
   Properties->SetArrayField("object_arr", DataObjectArray);//对象组

   TArray< TSharedPtr<FJsonValue> > DataArray;
   TSharedPtr<FJsonValueString> DataValue = MakeShareable(new FJsonValueString("data_value"));
   DataArray.Add(DataValue);
   Properties->SetArrayField("arr", DataArray);//数组
   UTDAnalytics::SetSuperProperties(Properties, AppID);
   //发送事件
   TSharedPtr<FJsonObject> EventProperties = MakeShareable(new FJsonObject);
   EventProperties->SetStringField("product_name", "商品名");//字符串
   UTDAnalytics::Track("product_buy", EventProperties);
   //设置用户属性
   TSharedPtr<FJsonObject> UserProperties = MakeShareable(new FJsonObject);
   UserProperties->SetStringField("username", "TA");//字符串
   UTDAnalytics::UserSet(UserProperties);
}
这篇文档对你有帮助吗？
本页内容