日志服务 Unity 网络探测插件使用说明

一、概述

·下载地址：你可点击 此处 下载 Unity 网络诊断 SDK 插件。

·支持的平台：

二、注意事项

·初始化顺序：必须先调用 Unity_CLS.Initialize() 完成初始化，再执行任何探测操作。

·回调线程：探测回调可能在非主线程执行，操作 Unity 对象时需注意线程安全。

·内存管理：SDK 内部会在回调执行后自动清理回调引用，无需手动管理。

·网络权限：Android 平台需确保已声明 INTERNET 和 ACCESS_NETWORK_STATE 权限。

·iOS 构建：确保 Xcode 项目中正确链接了所有依赖的 Framework。

·HTTP 探测：url 参数需包含完整的协议头（http:// 或 https://）。

·DNS 探测：domain 参数只需填写域名，不要包含协议头。

·Credential 安全：生产环境中建议通过服务端下发 geoToken，避免在客户端硬编码 SecretId/SecretKey。

四、步骤1：导入插件

导入方式：Unity > Assets > Import Package > Custom Package，选择 cls.unitypackage，导入后目录结构如下：

Assets/└── Plugins/ └── Unity_CLS/ ├── Unity_CLS.cs # C# 统一接口层 ├── Android/ │ └── libs/ │ ├── all-dependencies-1.0.0-shaded.jar #安卓所需java依赖 │ ├── network-diagnosis-release.aar #网络探测依赖 │ ├── producer-release.aar #日志上报依赖 │ └── unity-release.aar #unity交互依赖 ├── Windows/ │ └── cls_network_detect.dll #windows网络探测+日志上报动态库 └── iOS/ ├── UnityApi.h #与ios交互的桥接代码 ├── UnityApi.m ├── TencentCloudLogProducer.framework #cls ios sdk包 ├── FMDB.framework #cls ios sdk所需的依赖 ├── Protobuf.framework └── Reachability.framework

五、步骤2：多平台集成

Windows 集成时，无需额外配置，其他平台还需进行如下配置。

·Android 配置：

在 Assets/Plugins/Android/AndroidManifest.xml 中确保添加以下权限：

<uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

同时建议在 <application> 标签中添加明文流量支持（用于 HTTP 探测）：

<application android:usesCleartextTraffic="true">

·iOS 配置：

iOS 端依赖以下 Framework，已包含在插件目录中：

·TencentCloudLogProducer.framework：CLS 核心 SDK。

·FMDB.framework：本地数据库支持。

·Protobuf.framework：数据序列化。

·Reachability.framework：网络状态检测。

注意：构建 iOS 项目后，在 Xcode 中确认以上 Framework 已正确链接到 Embedded Binaries 和 Linked Frameworks and Libraries 中。

六、步骤3：快速开始

集成完成后，即可开始使用，以下是一个完整的快速上手示例代码。如你需要完整的示例代码，请参见 完整使用示例。

using System.Collections.Generic;using UnityEngine;using TencentCloudCLS;public class NetworkDiagnosisDemo : MonoBehaviour{ void Start() { // 1. 初始化 SDK Credential credential = new Credential(); credential.endpoint = "ap-guangzhou.cls.tencentcs.com"; credential.secretId = "你的 SecretId"; credential.secretKey = "你的 SecretKey"; credential.geoToken = "你的 GeoToken"; Unity_CLS.Initialize(credential); // 2. 设置用户自定义扩展字段（可选） Dictionary<string, string> userCustomField = new Dictionary<string, string>(); userCustomField.Add("app_version", "1.0.0"); userCustomField.Add("user_id", "12345"); Unity_CLS.SetUserCustom(userCustomField); // 3. 执行 TCP Ping 探测 TcpPingRequest tcpRequest = new TcpPingRequest(); tcpRequest.target = "www.baidu.com"; tcpRequest.port = 80; tcpRequest.callback = (response) => { Debug.Log("TCP Ping 结果: " + response); }; Unity_CLS.TcpPing(tcpRequest); }}

八、初始化

初始化 SDK，必须在执行任何探测操作之前调用。

Unity_CLS.Initialize(Credential credential)

Credential 参数说明

示例如下：

Credential credential = new Credential();credential.endpoint = "ap-guangzhou.cls.tencentcs.com";credential.secretId = "你的 SecretId";credential.secretKey = "你的 SecretKey";credential.geoToken = "你的 GeoToken";Unity_CLS.Initialize(credential);

九、设置用户自定义扩展字段

设置全局用户自定义扩展字段，设置后所有后续探测上报都会携带这些字段。

Unity_CLS.SetUserCustom(Dictionary<string, string> userCustomField)

示例如下：

Dictionary<string, string> userCustomField = new Dictionary<string, string>();userCustomField.Add("app_version", "1.0.0");userCustomField.Add("user_id", "12345");userCustomField.Add("channel", "official");Unity_CLS.SetUserCustom(userCustomField);

十、TCP Ping 探测

通过 TCP 连接探测目标主机的连通性和延迟。

Unity_CLS.TcpPing(TcpPingRequest request)

TcpPingRequest 参数说明：

示例如下：

TcpPingRequest request = new TcpPingRequest();request.target = "www.baidu.com";request.port = 80;request.count = 3;request.timeout = 2000;request.detectCustomField = new Dictionary<string, string>(){ { "scene", "login_page" }};request.callback = (response) =>{ Debug.Log("TCP Ping 结果: " + response);};Unity_CLS.TcpPing(request);

十一、ICMP Ping 探测

通过 ICMP 协议探测目标主机的连通性和延迟。

Unity_CLS.Ping(PingRequest request)

PingRequest 参数说明：

示例如下：

PingRequest request = new PingRequest();request.target = "www.baidu.com";request.count = 5;request.timeout = 3000;request.callback = (response) =>{ Debug.Log("Ping 结果: " + response);};Unity_CLS.Ping(request);

十二、HTTP 探测

通过 HTTP/HTTPS 请求探测目标 URL 的连通性和响应时间。

Unity_CLS.Http(HttpRequest request)

HttpRequest 参数说明：

示例如下：

HttpRequest request = new HttpRequest();request.url = "https://www.baidu.com";request.timeout = 5000;request.callback = (response) =>{ Debug.Log("HTTP 探测结果: " + response);};Unity_CLS.Http(request);

十三、DNS 解析探测

探测 DNS 解析的结果和耗时。

Unity_CLS.Dns(DnsRequest request)

DnsRequest 参数说明：

示例如下：

DnsRequest request = new DnsRequest();request.domain = "www.baidu.com";request.servers = "8.8.8.8";request.callback = (response) =>{ Debug.Log("DNS 解析结果: " + response);};Unity_CLS.Dns(request);

十四、MTR 路由追踪

执行 MTR（My Traceroute）路由追踪，获取到目标主机的完整路由路径及每跳延迟。

Unity_CLS.Mtr(MtrRequest request)

MtrRequest 参数说明：

示例如下：

MtrRequest request = new MtrRequest();request.target = "www.baidu.com";request.maxTtl = 30;request.times = 5;request.protocol = "icmp";request.callback = (response) =>{ Debug.Log("MTR 结果: " + response);};Unity_CLS.Mtr(request);

十五、完整使用示例

以下是一个包含所有探测类型的完整示例脚本，可挂载到 Unity 场景中的 GameObject 上。

using System;using System.Collections.Generic;using UnityEngine;using UnityEngine.UI;using TencentCloudCLS;public class NetworkDiagnosisManager : MonoBehaviour{ void Start() { Debug.Log("[NetworkDiagnosis] 开始初始化…"); } /// <summary> /// 初始化 SDK（需在所有探测操作前调用） /// </summary> public void Init() { Credential credential = new Credential(); credential.endpoint = "ap-guangzhou.cls.tencentcs.com"; credential.secretId = "你的 SecretId"; credential.secretKey = "你的 SecretKey"; credential.geoToken = "你的 GeoToken"; Unity_CLS.Initialize(credential); // 设置用户自定义扩展字段 Dictionary<string, string> userCustomField = new Dictionary<string, string>(); userCustomField.Add("app_version", "1.0.0"); userCustomField.Add("scene", "main_menu"); Unity_CLS.SetUserCustom(userCustomField); Debug.Log("[NetworkDiagnosis] 初始化完成"); } /// <summary> /// 执行 TCP Ping 探测 /// </summary> public void DoTcpPing() { TcpPingRequest request = new TcpPingRequest(); request.target = "www.baidu.com"; request.port = 80; request.count = 3; request.detectCustomField = new Dictionary<string, string>() { { "test_type", "tcp_ping" } }; request.callback = (response) => { Debug.Log("[TCP Ping] 结果: " + response); }; Unity_CLS.TcpPing(request); } /// <summary> /// 执行 ICMP Ping 探测 /// </summary> public void DoPing() { PingRequest request = new PingRequest(); request.target = "www.baidu.com"; request.count = 5; request.detectCustomField = new Dictionary<string, string>() { { "test_type", "icmp_ping" } }; request.callback = (response) => { Debug.Log("[Ping] 结果: " + response); }; Unity_CLS.Ping(request); } /// <summary> /// 执行 HTTP 探测 /// </summary> public void DoHttp() { HttpRequest request = new HttpRequest(); request.url = "http://www.baidu.com"; request.timeout = 5000; request.detectCustomField = new Dictionary<string, string>() { { "test_type", "http" } }; request.callback = (response) => { Debug.Log("[HTTP] 结果: " + response); }; Unity_CLS.Http(request); } /// <summary> /// 执行 DNS 解析探测 /// </summary> public void DoDns() { DnsRequest request = new DnsRequest(); request.domain = "www.baidu.com"; request.detectCustomField = new Dictionary<string, string>() { { "test_type", "dns" } }; request.callback = (response) => { Debug.Log("[DNS] 结果: " + response); }; Unity_CLS.Dns(request); } /// <summary> /// 执行 MTR 路由追踪 /// </summary> public void DoMtr() { MtrRequest request = new MtrRequest(); request.target = "www.baidu.com"; request.maxTtl = 30; request.times = 3; request.detectCustomField = new Dictionary<string, string>() { { "test_type", "mtr" } }; request.callback = (response) => { Debug.Log("[MTR] 结果: " + response); }; Unity_CLS.Mtr(request); }}

十六、回调说明

所有探测方法均通过 callback 回调返回结果，回调签名为：

public delegate void callback_response(string response);

回调参数 response 为 JSON 格式的字符串，包含探测结果数据。其中包含 traceId 字段，用于追踪标识。

注意：回调可能在非主线程中执行，如需在回调中操作 Unity UI，请使用主线程调度机制。

每次探测都会生成一个唯一的 traceId 用于追踪，traceId 说明如下：

·如果未设置 request.traceId，SDK 会自动生成一个 UUID 作为 traceId。

·如果手动设置了 request.traceId，SDK 会在其前面拼接一个短 UUID 前缀（格式：{自动 UUID}-{用户 traceId}），以防止重复。

回调返回的 JSON 中包含 traceId 字段，可用于在 CLS 控制台中检索对应的探测记录。

十七、扩展字段说明

SDK 支持如下两种扩展字段。

十八、用户扩展字段（userCustomField）

通过 Unity_CLS.SetUserCustom() 设置，全局生效，所有后续探测上报都会携带。适用于标识用户身份、应用版本等全局信息。

Dictionary<string, string> userCustomField = new Dictionary<string, string>();userCustomField.Add("user_id", "12345");userCustomField.Add("app_version", "2.0.0");Unity_CLS.SetUserCustom(userCustomField);

十九、检测扩展字段（detectCustomField）

通过每个 Request 对象的 detectCustomField 属性设置，仅对当次探测生效。适用于标识探测场景、业务标签等。

request.detectCustomField = new Dictionary<string, string>(){ { "scene", "game_loading" }, { "server_region", "ap-shanghai" }};

21、参数平台差异总结

22、多端口探测

·Android：通过 multiplePortsDetect 字段控制，默认为 true。

·iOS：通过 enableMultiplePortsDetect 字段控制，默认为 false。

·Windows：不支持多端口探测。

23、底层实现差异