Unity 应用接入¶

通过收集 Unity 应用的指标数据，以可视化方式分析应用性能。

阅读路径¶

首次接入：先看快速开始
完整接入：继续阅读本文
参数详解：查看 SDK 初始化、RUM 配置、Log 配置、Trace 配置
自定义能力：查看自定义标签使用、数据采集自定义规则、数据采集脱敏
高级场景：查看原生与 Unity 混合开发
问题排查：查看故障排查

前置条件¶

注意

若已开通 RUM Headless 服务，前置条件已自动配置，可直接接入应用。

应用接入¶

进入 用户访问监测 > 新建应用 > Android/iOS
分别为 Unity Android 和 Unity iOS 创建两个应用，以便分别接收来自 Android 和 iOS 平台的 RUM 数据
为每个平台的应用输入对应的应用名称和应用 ID
选择应用接入方式：
- 公网 DataWay：直接接收 RUM 数据，无需安装 DataKit 采集器
- 本地环境部署：满足前置条件后接收 RUM 数据

安装¶

源码地址：https://github.com/GuanceCloud/datakit-unity

Demo 地址：https://github.com/GuanceCloud/datakit-unity/blob/dev/Assets/Scenes

下载最新 ft-sdk-unity.unitypackage
通过 Assets -> Import Package -> Custom Package... 导入 ft-sdk-unity.unitypackage
添加 json 解析第三方库 "com.unity.nuget.newtonsoft-json"，可以在 Package Manager -> Add Package by name ... 中完成
将 FTSDK.prefab 拖拽至第一个场景页面，并在 FTSDK.cs 中 _InitSDK 方法内初始化 SDK
将 FTViewObserver.prefab 拖拽至其他场景页面，用于监听页面 View 生命周期，以及应用休眠和唤醒
通过 Application.logMessageReceived 监听并转换 Unity 崩溃数据和普通日志数据，示例请参考快速开始与数据采集自定义规则

Assets/Plugins
├── Android
│   ├── FTUnityBridge.java                // Android bridge
│   ├── InnerClassProxy.java              // Android Inner Setting Proxy
│   ├── ft-sdk-release.aar                // Android SDK
│   ├── gson-2.8.5.jar                    // Android SDK 依赖第三方库
├── iOS
│   ├── FTMobileSDK.xcframework           // iOS SDK
│   ├── FTUnityBridge.mm                  // iOS bridge
├── FTSDK.cs                              // FTSDK.prefab 绑定脚本
├── FTSDK.prefab                          // SDK 初始化预制件
├── FTUnityBridge.cs                      // Unity bridge 桥接 iOS Android 等平台方法
├── FTViewObserver.cs                     // FTViewObserver.prefab 绑定脚本
├── FTViewObserver.prefab                 // View 页面监听预制件
├── UnityMainThreadDispatcher.cs          // UnityMainThreadDispatcher.prefab 绑定脚本
├── UnityMainThreadDispatcher.prefab      // 主线程消费队列预制件

如果原生 Android 和 iOS 工程已集成原生 SDK，需要注释 _InitSDK 方法，避免重复设置；具体场景请参考原生与 Unity 混合开发
iOS Plugin Inspector 设置：FTMobileSDK.xcframework 是动态库，需要勾选 Add to Embedded Binaries。选中此选项后，Unity 将设置 Xcode 项目选项，从而将插件文件复制到最终应用程序包。

如果已经集成原生 SDK，Android 的 gson-2.8.5.jar、ft-sdk-release.aar 以及 iOS 的 FTMobileSDK.framework 可以从 Unity 项目中移除。
Android 的 OkHttp 请求和启动耗时功能需要配合 ft-plugin 使用，详细配置请见 Android SDK。

初始化说明¶

最小初始化示例请阅读快速开始。

完整 SDKConfig 参数说明请阅读 SDK 初始化。

详细配置入口¶

数据采集自定义规则¶

Unity SDK 当前主要通过手动方法调用来实现自定义 RUM 数据采集。

Action¶

使用方法¶

/// <summary>
/// 添加 Action
/// </summary>
/// <param name="actionName">action 名称</param>
/// <param name="actionType">action 类型</param>
public static void StartAction(string actionName, string actionType)

/// <summary>
/// 添加 Action
/// </summary>
/// <param name="actionName">action 名称</param>
/// <param name="actionType">action 类型</param>
/// <param name="property">附加属性参数</param>
public static void StartAction(string actionName, string actionType, Dictionary<string, object> property)

/// <summary>
/// 添加 Action
/// </summary>
/// <param name="actionName">action 名称</param>
/// <param name="actionType">action 类型</param>
public static void AddAction(string actionName, string actionType)

/// <summary>
/// 添加 Action
/// </summary>
/// <param name="actionName">action 名称</param>
/// <param name="actionType">action 类型</param>
/// <param name="property">附加属性参数</param>
public static void AddAction(string actionName, string actionType, Dictionary<string, object> property)

代码示例¶

FTUnityBridge.StartAction("click", "test");

View¶

使用方法¶

/// <summary>
/// View 开始
/// </summary>
/// <param name="viewName">当前页面名称</param>
public static void StartView(string viewName)

/// <summary>
/// View 开始
/// </summary>
/// <param name="viewName">当前页面名称</param>
/// <param name="property">附加属性参数</param>
public static void StartView(string viewName, Dictionary<string, object> property)

/// <summary>
/// View 结束
/// </summary>
public static void StopView()

/// <summary>
/// View 结束
/// </summary>
/// <param name="property">附加属性参数</param>
public static void StopView(Dictionary<string, object> property)

代码示例¶

FTUnityBridge.StartView("TEST_VIEW_ONE");

FTUnityBridge.StopView();

Resource¶

使用方法¶

/// <summary>
/// resource 开始
/// </summary>
/// <param name="resourceId">资源 Id</param>
public static async Task StartResource(string resourceId)

/// <summary>
/// resource 开始
/// </summary>
/// <param name="resourceId">资源 Id</param>
/// <param name="property">附加属性参数</param>
public static async Task StartResource(string resourceId, Dictionary<string, object> property)

/// <summary>
/// resource 结束
/// </summary>
/// <param name="resourceId">资源 Id</param>
public static async Task StopResource(string resourceId)

/// <summary>
/// resource 结束
/// </summary>
/// <param name="resourceId">资源 Id</param>
/// <param name="property">附加属性参数</param>
public static async Task StopResource(string resourceId, Dictionary<string, object> property)

/// <summary>
/// 添加网络传输内容和指标
/// </summary>
/// <param name="resourceId">资源 Id</param>
/// <param name="resourceParams">数据传输内容</param>
public static async Task AddResource(string resourceId, ResourceParams resourceParams)

ResourceParams¶

方法名	类型	必须	说明
url	string	是	url 地址
requestHeader	string	否	请求头参数，没有格式限制
responseHeader	string	否	响应头参数，没有格式限制
responseConnection	string	否	响应 `connection`
responseContentType	string	否	响应 `ContentType`
responseContentEncoding	string	否	响应 `ContentEncoding`
resourceMethod	string	否	请求方法 GET、POST 等
responseBody	string	否	返回 body 内容

代码示例¶

FTUnityBridge.StartResource(resourceId);

FTUnityBridge.StopResource(resourceId);

ResourceParams resourceParams = new ResourceParams();
resourceParams.url = url;
resourceParams.requestHeader = client.DefaultRequestHeaders.ToDictionary(header => header.Key, header => string.Join(",", header.Value));
resourceParams.responseHeader = response.Headers.ToDictionary(header => header.Key, header => string.Join(",", header.Value));
resourceParams.resourceStatus = (int)response.StatusCode;
resourceParams.responseBody = responseData;
resourceParams.resourceMethod = "GET";

FTUnityBridge.AddResource(resourceId, resourceParams);

Error¶

使用方法¶

/// <summary>
/// 添加错误信息
/// </summary>
/// <param name="log">日志</param>
/// <param name="message">消息</param>
public static async Task AddError(string log, string message)

/// <summary>
/// 添加错误信息
/// </summary>
/// <param name="log">日志</param>
/// <param name="message">消息</param>
/// <param name="property">附加属性参数</param>
public static async Task AddError(string log, string message, Dictionary<string, object> property)

代码示例¶

void OnEnable()
{
    Application.logMessageReceived += LogCallBack;
}

void OnDisable()
{
    Application.logMessageReceived -= LogCallBack;
}

void LogCallBack(string condition, string stackTrace, LogType type)
{
    if (type == LogType.Exception)
    {
        FTUnityBridge.AddError(stackTrace, condition);
    }
}

LongTask¶

使用方法¶

/// <summary>
/// 添加长耗时任务
/// </summary>
/// <param name="log">日志内容</param>
/// <param name="duration">持续时间，纳秒</param>
public static async Task AddLongTask(string log, long duration)

/// <summary>
/// 添加长耗时任务
/// </summary>
/// <param name="log">日志内容</param>
/// <param name="duration">持续时间，纳秒</param>
/// <param name="property">附加属性参数</param>
public static async Task AddLongTask(string log, long duration, Dictionary<string, object> property)

代码示例¶

FTUnityBridge.AddLongTask("long task test", 100002);

高级场景¶

常见问题¶

添加局变量避免冲突字段¶

为了避免自定义字段与 SDK 数据冲突，建议标签命名添加 项目缩写 的前缀，例如 df_tag_name。项目中使用 key 值可查询源码。SDK 全局变量中出现与 RUM、Log 相同变量时，RUM、Log 会覆盖 SDK 中的全局变量。

Unity 应用接入¶

阅读路径¶

前置条件¶

应用接入¶

安装¶

初始化说明¶

详细配置入口¶

数据采集自定义规则¶

Action¶

使用方法¶

代码示例¶

View¶

使用方法¶

代码示例¶

Resource¶

使用方法¶

ResourceParams¶

代码示例¶

Error¶

使用方法¶

代码示例¶

LongTask¶

使用方法¶

代码示例¶

高级场景¶

常见问题¶

添加局变量避免冲突字段¶

其他¶

文档内容是否对您有帮助？ ×