SDK 配置参考-云监控(CMS)-阿里云帮助中心

本文档详细介绍阿里云 RUM Unity SDK 的 API 接口及使用方法。SDK 提供了统一的 IAlibabacloudRum 接口，支持异常上报、自定义事件、日志采集、网络请求监控和视图追踪等功能。

核心 API

IAlibabacloudRum 接口

IAlibabacloudRum 是 SDK 的核心接口，定义于 Runtime/Rum/AlibabacloudRum.cs。通过 AlibabacloudSdk.Instance.Rum 获取实例。

using Alibabacloud.Rum.Unity;
using Alibabacloud.Rum.Unity.Rum;

// 获取 RUM 实例
IAlibabacloudRum rum = AlibabacloudSdk.Instance.Rum;

自定义异常上报

ReportException

上报异常信息到 RUM 平台。

方法签名

void ReportException(Exception ex);

参数说明

参数	类型	必填	说明
ex	Exception	是	要上报的异常对象

使用示例

using Alibabacloud.Rum.Unity;

try
{
    // 业务代码
    int result = 10 / int.Parse("0");
}
catch (Exception ex)
{
    // 手动上报异常
    AlibabacloudSdk.Instance.Rum.ReportException(ex);
    throw;
}

自动捕获

SDK 默认会自动捕获 Unity 异常，无需手动调用。自动捕获通过 AlibabacloudUnityLogHandler 实现，在 SDK 初始化时自动挂载到 Debug.unityLogger。

自定义事件上报

ReportEvent

上报自定义业务事件，用于追踪关键业务指标。

方法签名

void ReportEvent(string eventName, string group, double value, Dictionary<string, object> info);

参数说明

参数	类型	必填	说明
eventName	string	是	事件名称，如 "item_purchased"
group	string	否	事件分组，如 "economy"、"gameplay"
value	double	否	事件数值，如购买金额、分数等
info	Dictionary<string, object>	否	附加属性，键值对形式

使用示例

using Alibabacloud.Rum.Unity;
using System.Collections.Generic;

// 上报购买事件
AlibabacloudSdk.Instance.Rum.ReportEvent(
    eventName: "item_purchased",
    group: "economy",
    value: 99.9,
    info: new Dictionary<string, object>
    {
        { "item_id", "sword_001" },
        { "item_name", "Excalibur" },
        { "currency", "USD" },
        { "player_level", 25 }
    }
);

// 上报关卡完成事件
AlibabacloudSdk.Instance.Rum.ReportEvent(
    eventName: "level_completed",
    group: "gameplay",
    value: 150.5,  // 完成时间（秒）
    info: new Dictionary<string, object>
    {
        { "level_id", "world_1_level_5" },
        { "stars_earned", 3 },
        { "attempts", 2 }
    }
);

// 上报简单事件（无附加属性）
AlibabacloudSdk.Instance.Rum.ReportEvent(
    eventName: "tutorial_skipped",
    group: "onboarding",
    value: 0,
    info: null
);

自定义日志上报

ReportLog

上报结构化日志到 RUM 平台。

方法签名

void ReportLog(string logContent, string logName, string logLevel, string stackTrace, Dictionary<string, object> extraInfo);

参数说明

参数	类型	必填	说明
logContent	string	是	日志内容
logName	string	否	日志名称/来源，如 "Unity.Log"
logLevel	string	否	日志级别：Info、Warning、Error
stackTrace	string	否	堆栈信息
extraInfo	Dictionary<string, object>	否	附加属性

使用示例

using Alibabacloud.Rum.Unity;
using System.Collections.Generic;

// 上报信息日志
AlibabacloudSdk.Instance.Rum.ReportLog(
    logContent: "Player reached level 10",
    logName: "game_progress",
    logLevel: "Info",
    stackTrace: "",
    extraInfo: new Dictionary<string, object>
    {
        { "player_id", "12345" },
        { "level", 10 },
        { "score", 50000 }
    }
);

// 上报警告日志
AlibabacloudSdk.Instance.Rum.ReportLog(
    logContent: "Low memory warning detected",
    logName: "system",
    logLevel: "Warning",
    stackTrace: UnityEngine.StackTraceUtility.ExtractStackTrace(),
    extraInfo: new Dictionary<string, object>
    {
        { "available_memory", "512MB" },
        { "scene", "main_game" }
    }
);

// 上报错误日志
AlibabacloudSdk.Instance.Rum.ReportLog(
    logContent: "Failed to load asset bundle",
    logName: "asset_loader",
    logLevel: "Error",
    stackTrace: UnityEngine.StackTraceUtility.ExtractStackTrace(),
    extraInfo: new Dictionary<string, object>
    {
        { "bundle_path", "assets/bundles/characters" },
        { "error_code", 404 }
    }
);

自动捕获

SDK 默认根据用户配置，自动捕获日志，无需手动调用。

自定义视图追踪

StartView

开始追踪一个视图（页面/场景）。

方法签名

void StartView(string key, string name, Dictionary<string, object> attributes);

参数说明

参数	类型	必填	说明
key	string	是	视图唯一标识，如场景路径
name	string	否	视图名称，如场景名称
attributes	Dictionary<string, object>	否	附加属性，`视图加载时间(_alibabacloud.load_time)`，单位ms

使用示例

using Alibabacloud.Rum.Unity;
using System.Collections.Generic;

// 开始追踪主菜单视图
AlibabacloudSdk.Instance.Rum.StartView(
    key: "main_menu",
    name: "Main Menu",
    attributes: new Dictionary<string, object>
    {
        { "_alibabacloud.load_time", 3 }
    }
);

// 开始追踪游戏场景
AlibabacloudSdk.Instance.Rum.StartView(
    key: "Scenes/Game/Level1",
    name: "Level 1",
    attributes: new Dictionary<string, object>
    {
        { "_alibabacloud.load_time", 4 }
    }
);

StopView

结束视图追踪。

方法签名

void StopView(string key, Dictionary<string, object> attributes);

参数说明

参数	类型	必填	说明
key	string	是	视图唯一标识，需与 StartView 的 key 一致
attributes	Dictionary<string, object>	否	附加属性，会剔除掉以`_alibabacloud.`开头的属性

使用示例

using Alibabacloud.Rum.Unity;
using System.Collections.Generic;

// 结束主菜单视图追踪
AlibabacloudSdk.Instance.Rum.StopView(
    key: "main_menu",
    attributes: new Dictionary<string, object>
    {
        { "exit_reason", "play_button_clicked" }
    }
);

自动场景追踪

当 AlibabacloudOptions.AutomaticSceneTracking 开启时（默认开启），SDK 会自动追踪场景切换：

SceneManager.activeSceneChanged 事件触发时记录场景加载开始时间
SceneManager.sceneLoaded 事件触发时调用 StartView，并附带加载耗时

网络请求监控

使用 InstrumentedWebRequest

SDK 提供了 InstrumentedWebRequest 类，用于自动埋点 UnityWebRequest。

方法签名

// 创建埋点的 UnityWebRequest
static UnityWebRequest CreateInstrumentedRequest(string url, string method);

// 发送请求并自动埋点
static UnityWebRequestAsyncOperation SendWebRequest(UnityWebRequest request);

使用示例

using Alibabacloud.Rum.Unity.Network;
using UnityEngine.Networking;
using System.Collections;

public class ApiClient : MonoBehaviour
{
    public IEnumerator GetData(string url)
    {
        // 创建埋点的请求
        var request = InstrumentedWebRequest.CreateInstrumentedRequest(url, "GET");
        
        // 发送请求（自动埋点）
        yield return InstrumentedWebRequest.SendWebRequest(request);
        
        // 处理响应
        if (request.result == UnityWebRequest.Result.Success)
        {
            Debug.Log(request.downloadHandler.text);
        }
    }
    
    public IEnumerator PostData(string url, string jsonData)
    {
        var request = InstrumentedWebRequest.CreateInstrumentedRequest(url, "POST");
        request.uploadHandler = new UploadHandlerRaw(System.Text.Encoding.UTF8.GetBytes(jsonData));
        request.downloadHandler = new DownloadHandlerBuffer();
        request.SetRequestHeader("Content-Type", "application/json");
        
        yield return InstrumentedWebRequest.SendWebRequest(request);
        
        if (request.result == UnityWebRequest.Result.Success)
        {
            Debug.Log("Post success: " + request.downloadHandler.text);
        }
    }
}

SDK 实例管理

AlibabacloudSdk 类

SDK 核心入口，定义于 Runtime/AlibabacloudSdk.cs。

属性

属性	类型	说明
Instance	AlibabacloudSdk	单例实例
Rum	IAlibabacloudRum	RUM 接口实例
Options	AlibabacloudOptions	配置选项