阿里云 RUM Unity SDK 用于 Unity 游戏的实时用户监控，当前支持 Android、iOS、WebGL、Windows Standalone 平台。
功能概览
阿里云 RUM Unity SDK 是一款面向 Unity 游戏的实时用户监控（Real User Monitoring）SDK，集成后可实现以下能力：
异常监控：自动捕获 Unity 异常和崩溃。
结构化日志采集：按 LogType 粒度控制日志采集。
网络请求监控：对 UnityWebRequest 和 HttpClient 进行自动埋点。
分布式链路追踪：支持 W3C 与 SkyWalking 协议。
自定义事件上报：上报业务自定义事件。
IL2CPP 符号表支持：提升崩溃符号化质量。
环境要求
维度 | 要求 |
Unity 版本 | ≥ 2021.3 |
Android 最低版本 | API Level 21+ |
iOS 最低版本 | iOS 12.0 |
Windows Standalone | Windows 7+（x86 / x86_64） |
Android 构建方式 | Gradle |
iOS 依赖管理 | CocoaPods |
Windows 原生依赖 | 内置 alibabacloud_rum.dll（x86 / x86_64） |
≥ 0.1.8 |
安装 SDK
通过 .unitypackage 安装
下载 SDK 包
导入 Unity 项目
打开 Unity 项目。
在菜单栏选择 Assets > Import Package > Custom Package...。
选择下载的
.unitypackage文件。在弹出的导入对话框中，单击 Import。
确认导入结果
导入成功后，项目目录中出现以下结构：
Assets/ ├── Runtime/ # SDK 运行时核心代码 │ ├── Android/ # Android 平台适配 │ ├── iOS/ # iOS 平台适配 │ ├── Windows/ # Windows Standalone 平台适配 │ ├── Plugins/ │ │ ├── x86/ # Windows x86 原生 DLL │ │ └── x86_64/ # Windows x86_64 原生 DLL │ ├── Rum/ # RUM 核心实现 │ ├── Worker/ # 后台工作线程 │ └── ... └── Editor/ # SDK Editor 配置工具 └── Windows/ # Windows 构建后处理器
配置 SDK
1. 打开配置窗口
在 Unity 菜单栏选择 Tools > Alibabacloud，打开 SDK 配置窗口。
2. 核心配置（Core Tab）
Core 页签根据当前 Build Target 自动渲染对应字段。
Android / iOS / WebGL
配置项 | 说明 | 必填 |
Endpoint | RUM 上报服务的 URL，可在云监控 2.0 控制台获取 | 是 |
SERVICE ID | 服务 ID，用于标识应用 | 是 |
WORKSPACE | 工作空间 ID | 否 |
Enable Native SDK Debuggable | 是否开启原生 SDK 调试日志 | 否 |
Windows Standalone
配置项 | 说明 | 必填 |
Endpoint | RUM 上报服务的基础 URL。保存时自动追加 /rum/web/v2 后缀（与原生 alibabacloud_rum_options_set_config_address 对齐），重新打开时自动剥离，保持编辑幂等。 | 是 |
APP ID | 云监控 2.0 控制台 RUM 注册的应用标识，对应原生 alibabacloud_rum_options_set_app_id。 | 是 |
Enable Native SDK Debuggable | 是否开启原生 SDK 调试日志 | 否 |
Windows Standalone 不需要 WORKSPACE 字段，UI 会自动隐藏。Endpoint 输入框下方实时预览最终拼接的完整 config address。
自动场景追踪
配置项 | 说明 |
Automatic Scene Tracking | 开启后，场景切换会自动作为 RUM View 上报 |
调试配置
配置项 | 说明 |
Enable Debug Output | 是否输出 SDK 诊断日志 |
Verbosity Level | 日志级别（Debug/Info/Warning/Error） |
3. 日志配置（Logging Tab）
配置项 | 说明 | 默认值 |
Enable Structured Logging | 是否开启结构化日志采集 | false |
Structured Log On DebugLog | 是否采集 Debug.Log | false |
Structured Log On DebugLogWarning | 是否采集 Debug.LogWarning | true |
Structured Log On DebugLogAssertion | 是否采集 Debug.LogAssertion | true |
Structured Log On DebugLogError | 是否采集 Debug.LogError | true |
Structured Log On DebugLogException | 是否采集 Debug.LogException | true |
4. 网络配置（Network Tab）
配置项 | 说明 | 默认值 |
Enable Network Tracking | 是否开启网络请求追踪 | true |
Network Sample Rate | 采样率（0.0~1.0） | 1.0 |
Network Url Allowlist | URL 白名单，为空则允许所有 | 空 |
Network Url Blocklist | URL 黑名单 | 空 |
Capture Request Body Size | 是否采集请求体大小 | true |
Capture Response Body Size | 是否采集响应体大小 | true |
Capture Request Headers | 是否采集请求头 | false |
Capture Response Headers | 是否采集响应头 | false |
配置分布式链路追踪
SDK 支持在 HTTP 请求中注入追踪上下文头，实现分布式链路追踪。
追踪协议
协议 | 说明 |
W3C | W3C Trace Context 标准，使用 |
SkyWalking | Apache SkyWalking 标准，使用 |
TraceContextConfig 配置类
通过 TraceContextConfig 类配置 URL 模式与追踪协议的映射关系，定义于 Runtime/Network/TraceContextStandard.cs：
[Serializable]
public class TraceContextConfig
{
public string UrlPattern { get; set; } // URL 匹配模式
public TraceContextStandard Standard { get; set; } // 追踪标准
}在 Unity Editor 中配置
在 Network Tab 中完成以下配置：
勾选 Enable Trace Context。
在 Trace Context Configs 中添加条目。
设置 Url Pattern（如
api.example.com）。选择 Standard（W3C 或 SkyWalking）。
配置项 | 说明 |
Enable Trace Context | 是否开启分布式链路追踪。 |
Trace Context Configs | 按 URL 模式配置追踪标准（W3C / SkyWalking）。 |
HTTP 方法过滤
可按 HTTP 方法独立配置追踪范围，支持的方法包括：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS。
配置平台依赖
Android 平台
1. 安装 EDM4U
SDK 通过 External Dependency Manager for Unity（EDM4U）管理原生依赖。如果尚未安装，请从 EDM4U 发布页面下载并导入。
2. 解析依赖
导入 SDK 后，EDM4U 会自动解析 Editor/AlibabacloudDependencies.xml 中定义的原生依赖：
<androidPackage spec="com.aliyun.rum:alibabacloud-android-rum-sdk:*.*.*">
<repositories>
<repository>https://repo1.maven.org/maven2</repository>
</repositories>
</androidPackage>如果自动解析未触发，在菜单栏选择 Assets > External Dependency Manager > Android Resolver > Resolve。
3. ProGuard 配置
SDK 已包含 ProGuard 规则，无需额外配置。如需手动添加，规则文件位于 Runtime/Android/proguard-unity.txt。
iOS 平台
1. 安装 CocoaPods
确保系统已安装 CocoaPods：
sudo gem install cocoapods2. 解析依赖
EDM4U 会自动生成 Podfile 并添加以下依赖：
pod 'AlibabaCloudRUM', '*.*.*'在菜单栏选择 Assets > External Dependency Manager > iOS Resolver > Settings，确认 Cocoapods Integration 已启用。
3. 构建后操作
构建 iOS 项目后，必须使用 .xcworkspace 文件打开 Xcode 工程，而非 .xcodeproj：
cd Your-Builds/iOS-Paths
pod install
open Your-Unity-App.xcworkspace4. Xcode 配置
确保 AlibabaCloudRUMSDK.xcframework 已正确链接到 UnityFramework，并设置为 Embed & Sign。
WebGL 平台
WebGL 平台无需额外原生依赖，SDK 通过 .jslib 插件与浏览器环境交互。
1. 引入浏览器 SDK
在 WebGL 构建的 HTML 文件中，添加阿里云浏览器 RUM SDK：
<script src="https://sdk.rum.aliyuncs.com/v2/browser-sdk.js"></script>2. 注意事项
WebGL 平台使用 PassthroughWorker，所有操作在主线程同步执行。
Windows Standalone 平台
Windows Standalone 平台（v3.0.0 起支持）通过 P/Invoke 调用原生 C SDK（alibabacloud_rum.dll），开箱即用，无需额外依赖管理工具。
1. 原生 DLL 位置
导入 SDK 后，原生 DLL 自动放置到以下目录：
Runtime/Plugins/x86/alibabacloud_rum.dll # 32-bit
Runtime/Plugins/x86_64/alibabacloud_rum.dll # 64-bitDLL 的 .meta 文件已启用 Editor（CPU： x86_64， OS： Windows）和 Standalone Windows64 平台，无需手动配置。
2. 构建后处理
SDK 内置 WindowsBuildPostProcessor.cs，构建时自动将原生 DLL 拷贝到：
<YourGame>_Data/Plugins/x86_64/alibabacloud_rum.dll后处理器支持 Asset 和 UPM（Packages/）两种安装布局，使用 PackageInfo.FindForAssembly 自动解析包路径。
3. 运行时 DLL 加载
首次调用 SDK 时，WindowsDllLoader 执行以下操作：
调用 SetDllDirectory 将插件目录注册到 DLL 搜索路径。
单实例守护，防止根目录与 Plugins/x86_64 双重加载导致崩溃。
加载失败时按错误码（如 Error 126 表示依赖缺失）输出诊断信息。
4. 调用约定与崩溃保护
所有 P/Invoke 函数声明为 CallingConvention.Cdecl，与原生 ABI 保持一致。初始化路径通过 [HandleProcessCorruptedStateExceptions] 捕获结构化异常，所有公开 API 入口包含 !IsNativeReady 短路保护——原生 DLL 不可用时自动降级为空操作（No-Op），不影响业务运行。
5. 注意事项
Windows 平台 auto_crash_tracking 默认禁用，防止原生 SDK 的 SetUnhandledExceptionFilter 抢占 Unity 崩溃处理器。Unity 异常仍正常写入 Player.log 并上报至 RUM。
Windows 平台 auto_curl_tracking 默认禁用，网络埋点统一通过 UnityWebRequest / HttpClient 拦截。
应用退出时 SDK 自动刷新原生事件队列，确保缓冲数据上报至服务端。
配置文件说明
SDK 配置保存在 ScriptableObject 中，路径为：
Assets/Resources/Alibabacloud/AlibabacloudOptions.asset配置文件在运行时通过 Resources.Load<AlibabacloudOptions>() 自动加载。
接入验证
运行应用后，控制台出现以下日志即表示 SDK 初始化成功：
Android
[AlibabaCloudRum] rum init successiOS
[AlibabaCloudRUM] [INFO ] [RUM] <start> AlibabaCloud RUM init successWebGL
[ALIBABACLOUD] RUM SDK initialized successfullyWindows Standalone
[AlibabaCloud-RUM] [INFO ] [Init] alibabacloud rum init success.如果控制台未出现上述成功日志，请按以下步骤排查：
检查 Endpoint 配置是否正确，确认 URL 与云监控 2.0 控制台中显示的上报地址一致。
检查 SERVICE ID 是否与云监控 2.0 控制台中创建的应用 ID 匹配。
在 Core Tab 中开启 Enable Debug Output，查看 SDK 输出的详细诊断日志定位问题原因。
常见问题
Android 构建失败，提示找不到 RUM SDK 类
确保 EDM4U 已正确解析依赖。检查 Assets/Plugins/Android 目录下是否生成了相关 Gradle 配置文件。
iOS 构建后崩溃
确保使用 .xcworkspace 打开 Xcode 工程，并检查 AlibabaCloudRUMSDK.xcframework 是否已正确链接到 UnityFramework。
WebGL 构建后无数据上报
确保在 WebGL 构建产出的 HTML 文件中引入了浏览器 RUM SDK。详细操作请参见接入 Web/H5 应用。
SDK 初始化失败，控制台无成功日志
现象：运行应用后，控制台未出现 SDK 初始化成功的日志。
可能原因：
Endpoint 配置错误或为空。
SERVICE ID 与云监控 2.0 控制台中的应用 ID 不匹配。
排查步骤：
登录云监控 2.0 控制台，确认 Endpoint 和 SERVICE ID 的值，并与 SDK 配置窗口中的值逐字对比。
在 SDK 配置窗口的 Core Tab 中，开启 Enable Debug Output 并将 Verbosity Level 设置为 Debug，重新运行应用查看详细诊断日志。
Windows 构建后启动即闪退，Player.log 无任何崩溃信息
此问题已在 v3.0.0 修复。请确认以下事项：
使用 v3.0.0 或更高版本 SDK。
P/Invoke 调用约定为 Cdecl（v3.0.0 默认）。
未强制启用 auto_crash_tracking（会抢占 Unity 崩溃处理器）。
Windows 启动报 Native DLL not found 或 Error 126
排查步骤：
确认
<YourGame>_Data/Plugins/x86_64/alibabacloud_rum.dll存在（构建后处理器会自动拷贝）。在 Editor 中确认
Runtime/Plugins/x86_64/alibabacloud_rum.dll.meta已勾选 Editor 和 Standalone Windows64 平台。Error 126 表示 DLL 依赖缺失，请安装 Visual C++ Redistributable for Visual Studio。
检查 Player.log 中
[ALIBABACLOUD Windows]前缀的诊断日志，查看实际加载路径。
Windows Endpoint 字段提示 "Final config address： ..." 是什么意思
这是配置预览功能（v3.0.0 新增）。Windows 原生 SDK 要求完整的 config address（含 /rum/web/v2 后缀），UI 自动在基础 URL 后追加该后缀。HelpBox 展示的即为最终传递给原生 SDK 的完整地址。