SDK 配置參考 - Cloud Monitor

本文檔詳細介紹阿里雲 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	配置選項