tencent cloud

Cloud Log Service

Using the Unity Network Probe Plugin

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-06-25 19:44:52

Overview

Tencent Cloud CLS provides a Unity network diagnostics SDK plugin, which supports multiple network probing operations within Unity projects, including ICMP Ping, TCP Ping, HTTP Ping, DNS resolution, and MTR route tracing. The probing results are automatically reported to the Tencent Cloud CLS platform, facilitating network quality analysis and troubleshooting.
Download: Click here to download the Unity network diagnostics SDK plugin.
Supported platforms:
Platform
Support Status
Windows (Standalone)
Supported
Android
Supported
iOS
Supported
Unity Editor
Supported (using Windows DLL)

Must-Knows

Initialization sequence: You must first call Unity_CLS.Initialize() to complete initialization before performing any probing operations.
Callback thread: Probing callbacks may execute on non-main threads. Pay attention to thread safety when manipulating Unity objects.
Memory management: The SDK automatically cleans up callback references after the callback execution, eliminating the need for manual management.
Network permissions: On the Android platform, ensure that the INTERNET and ACCESS_NETWORK_STATE permissions are declared.
iOS build: Ensure that all dependent frameworks are correctly linked in the Xcode project.
HTTP probing: The url parameter must include the complete protocol header (http:// or https://).
DNS probing: For the domain parameter, enter only the domain name and do not include the protocol header.
Credential security: In production environments, it is recommended to issue geoToken from the server side to avoid hardcoding SecretId/SecretKey in the client.

Integration Guide

Step 1: Importing the Plugin

Import method: In Unity, navigate to Assets > Import Package > Custom Package, select cls.unitypackage, and import it. The directory structure after import is as follows:
Assets/
└── Plugins/
└── Unity_CLS/
├── Unity_CLS.cs # C# unified interface layer
├── Android/
│ └── libs/
│ ├── all-dependencies-1.0.0-shaded.jar # java dependencies required for Android
│ ├── network-diagnosis-release.aar # network probing dependency
│ ├── producer-release.aar # log reporting dependency
│ └── unity-release.aar # unity interaction dependency
├── Windows/
│ └── cls_network_detect.dll # windows network probing + log reporting dynamic library
└── iOS/
├── UnityApi.h # bridging code for interacting with ios
├── UnityApi.m
├── TencentCloudLogProducer.framework # cls ios sdk package
├── FMDB.framework # dependency required by the cls ios sdk
├── Protobuf.framework
└── Reachability.framework

Step 2: Multi-Platform Integration

For Windows integration, no additional configuration is required. For other platforms, the following configurations are needed.
Android Configuration:
Ensure that the following permissions are added in Assets/Plugins/Android/AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
It is also recommended to add cleartext traffic support (for HTTP probing) within the <application> Tag:
<application android:usesCleartextTraffic="true">
iOS Configuration:
The iOS side depends on the following frameworks, which are already included in the plugin directory:
TencentCloudLogProducer.framework: the core CLS SDK.
FMDB.framework: local database support.
Protobuf.framework: data serialization.
Reachability.framework: network status detection.
Note:
After the iOS project is built, confirm in Xcode that the aforementioned frameworks are correctly linked under Embedded Binaries and Linked Frameworks and Libraries.

Step 3: Quick Start

After integration is complete, you can start using it. Below is a complete quick-start sample code. If you need the complete sample code, see Complete Usage Example.
using System.Collections.Generic;
using UnityEngine;
using TencentCloudCLS;

public class NetworkDiagnosisDemo : MonoBehaviour
{
void Start()
{
// 1. Initialize SDK.
Credential credential = new Credential();
credential.endpoint = "ap-guangzhou.cls.tencentcs.com";
credential.secretId = "Your SecretId";
credential.secretKey = "Your SecretKey";
credential.geoToken = "Your GeoToken";
Unity_CLS.Initialize(credential);
// 2. Set user-defined extended fields (optional)
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. Perform TCP Ping detection
TcpPingRequest tcpRequest = new TcpPingRequest();
tcpRequest.target = "www.baidu.com";
tcpRequest.port = 80;
tcpRequest.callback = (response) =>
{
Debug.Log("TCP Ping Result: " + response);
};
Unity_CLS.TcpPing(tcpRequest);
}
}

API Reference

Initializing

Initialize the SDK. This function must be called before any probing operations are performed.
Unity_CLS.Initialize(Credential credential)
Credential Parameter Description
Field
Type
Required
Description
endpoint
string
Yes
CLS service endpoint, such as "ap-guangzhou.cls.tencentcs.com"
secretId
string
Yes
TencentCloud API key SecretId. For how to obtain it, see TencentCloud API Key.
secretKey
string
Yes
TencentCloud API key SecretKey. For how to obtain it, see TencentCloud API Key.
topicId
string
No
CLS log topic ID (optional when geoToken is used)
geoToken
string
No
Network probe Token. For how to obtain it, see Obtain Key.
Example:
Credential credential = new Credential();
credential.endpoint = "ap-guangzhou.cls.tencentcs.com";
credential.secretId = "Your SecretId";
credential.secretKey = "Your SecretKey";
credential.geoToken = "Your GeoToken";

Unity_CLS.Initialize(credential);

Configuring User-Defined Extension Fields

Set global user-defined extended fields. After the fields are set, these fields will be carried by all subsequent probe reports.
Unity_CLS.SetUserCustom(Dictionary<string, string> userCustomField)
Example:
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 Detection

Probe the connectivity and latency of the target host via TCP connection.
Unity_CLS.TcpPing(TcpPingRequest request)
TcpPingRequest Parameter Description:
Field
Type
Default Value
Platform Support
Description
target
string
""
Entire platform
Target hostname or IP address
port
int
-1
Entire platform
Target port number
count
int
1
Entire platform
Number of probes
timeout
int
1000
Entire platform
Timeout (ms)
size
int
0
Windows/Android
Packet size to send (in bytes), where 0 means no data is sent
payload
string
null
Windows/Android
Test data content to be sent to the target port
interval
int
300
Windows
Probe interval (ms)
enableVerification
int
1
Windows
Whether to enable connection verification
1: Enabled
0: Disabled
prefer
int
0
Windows/iOS
IP version preference
0: IPv4 Preferred
1: IPv6 Preferred
2:IPv4 only
3:IPv6 only
netId
int
0
Windows
Network adapter ID
traceId
string
null
Entire platform
Trace ID (can be null, auto-generated)
src
string
null
Windows
Source identifier
multiplePortsDetect
bool
true
Android
Whether to perform multi-port detection
enableMultiplePortsDetect
bool
false
iOS
Whether to enable multi-port detection
detectCustomField
Dictionary
Empty dictionary
Entire platform
Extended field for detection
callback
callback_response
null
Entire platform
Result callback function
Example:
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 Result: " + response);
};

Unity_CLS.TcpPing(request);

ICMP Ping Detection

Probe the connectivity and latency of the target host via the ICMP protocol.
Unity_CLS.Ping(PingRequest request)
PingRequest Parameter Description:
Field
Type
Default Value
Platform Support
Description
target
string
""
Entire platform
Target hostname or IP address
count
int
1
Entire platform
Number of probes
timeout
int
1000
Entire platform
Timeout (ms)
packetSize
int
100
Windows/Android
Packet size (in bytes, excluding the ICMP header)
interval
int
300
Windows/iOS
Probe interval (ms)
ttl
int
64
Windows
TTL value
prefer
int
0
Windows/iOS
IP version preference
netId
int
0
Windows
Network adapter ID
traceId
string
null
Entire platform
Trace ID
src
string
null
Windows
Source identifier
multiplePortsDetect
bool
true
Android
Whether to perform multi-port detection
enableMultiplePortsDetect
bool
false
iOS
Whether to enable multi-port detection
detectCustomField
Dictionary
Empty dictionary
Entire platform
Extended field for detection
callback
callback_response
null
Entire platform
Result callback function
Example:
PingRequest request = new PingRequest();
request.target = "www.baidu.com";
request.count = 5;
request.timeout = 3000;
request.callback = (response) =>
{
Debug.Log("Ping Result: " + response);
};

Unity_CLS.Ping(request);

HTTP Detection

Probe the connectivity and response time of the target URL via HTTP/HTTPS requests.
Unity_CLS.Http(HttpRequest request)
HttpRequest Parameter Description:
Field
Type
Default Value
Platform Support
Description
url
string
""
Entire platform
Target URL (must include the protocol header, such as http:// or https://).
count
int
1
Android/iOS
Number of probes
timeout
int
1000
Entire platform
Timeout (ms)
interval
int
300
Windows
Probe interval (ms)
ip
string
null
Android
Specified IP address (uses DNS resolution when null).
downloadBytesLimit
int
0
Windows
Download byte limit, where 0 means unlimited.
downloadHeaderOnly
int
0
Windows
Whether to download headers only
1: Headers Only
0: Full Content
verifySslCert
int
0
Windows/iOS
Whether to verify SSL Certificates
1: Verify
0: Do Not Verify
size
int
0
Android
Packet size to send
prefer
int
0
Windows/iOS
IP version preference
netId
int
0
Windows
Network adapter ID
traceId
string
null
Entire platform
Trace ID
src
string
null
Windows
Source identifier
multiplePortsDetect
bool
true
Android
Whether to perform multi-port detection
enableMultiplePortsDetect
bool
false
iOS
Whether to enable multi-port detection
detectCustomField
Dictionary
Empty dictionary
Entire platform
Extended field for detection
callback
callback_response
null
Entire platform
Result callback function
Example:
HttpRequest request = new HttpRequest();
request.url = "https://www.baidu.com";
request.timeout = 5000;
request.callback = (response) =>
{
Debug.Log("HTTP Probe Result: " + response);
};

Unity_CLS.Http(request);

DNS Resolution Detection

Probe the result and latency of DNS resolution.
Unity_CLS.Dns(DnsRequest request)
DnsRequest Parameter Description:
Field
Type
Default Value
Platform Support
Description
domain
string
""
Entire platform
Target domain name.
type
string
null
Windows/Android
DNS query type (such as "A" and "AAAA", defaults to A when null)
servers
string
null
Entire platform
DNS server list (comma-separated, such as "8.8.8.8,8.8.4.4", uses system default when null)
count
int
1
Android
Number of probes
timeout
int
1000
Entire platform
Timeout (ms)
size
int
0
Android
Packet size to send
prefer
int
0
Windows/iOS
IP version preference
traceId
string
null
Entire platform
Trace ID
src
string
null
Windows
Source identifier
multiplePortsDetect
bool
true
Android
Whether to perform multi-port detection
enableMultiplePortsDetect
bool
false
iOS
Whether to enable multi-port detection
detectCustomField
Dictionary
Empty dictionary
Entire platform
Extended field for detection
callback
callback_response
null
Entire platform
Result callback function
Example:
DnsRequest request = new DnsRequest();
request.domain = "www.baidu.com";
request.servers = "8.8.8.8";
request.callback = (response) =>
{
Debug.Log("DNS Resolution Result: " + response);
};

Unity_CLS.Dns(request);

MTR Route Tracing

Execute an MTR (My Traceroute) route trace to obtain the complete route path and per-hop latency to the target host.
Unity_CLS.Mtr(MtrRequest request)
MtrRequest Parameter Description:
Field
Type
Default Value
Platform Support
Description
target
string
""
Entire platform
Target hostname or IP address
maxTtl
int
30
Entire platform
Maximum TTL value (maximum number of hops, 1 - 255)
times
int
10
Entire platform
Number of probes per hop
timeout
int
1000
Entire platform
Timeout (ms)
interval
int
300
Windows
Detection interval (ms)
protocol
string
"icmp"
Windows/Android
Protocol type ("icmp", "tcp", "udp")
destPort
int
0
Windows
Target port (used for TCP/UDP protocols)
maxPaths
int
1
Windows/Android
Maximum number of paths (1 - 10)
size
int
0
Android
Packet size to send
prefer
int
0
Windows/iOS
IP version preference
netId
int
0
Windows
Network adapter ID
traceId
string
null
Entire platform
Trace ID
src
string
null
Windows
Source identifier
multiplePortsDetect
bool
true
Android
Whether to perform multi-port detection
enableMultiplePortsDetect
bool
false
iOS
Whether to enable multi-port detection
detectCustomField
Dictionary
Empty dictionary
Entire platform
Extended field for detection
callback
callback_response
null
Entire platform
Result callback function
Example:
MtrRequest request = new MtrRequest();
request.target = "www.baidu.com";
request.maxTtl = 30;
request.times = 5;
request.protocol = "icmp";
request.callback = (response) =>
{
Debug.Log("MTR Result: " + response);
};

Unity_CLS.Mtr(request);

Complete Usage Example

The following is a complete sample script that includes all probe types and can be attached to a GameObject in a Unity scene.
using System;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;
using TencentCloudCLS;

public class NetworkDiagnosisManager : MonoBehaviour
{
void Start()
{
Debug.Log("[NetworkDiagnosis] Starting initialization...");
}

/// <summary>
/// Initialize the SDK (must be called before any probing operations)
/// </summary>
public void Init()
{
Credential credential = new Credential();
credential.endpoint = "ap-guangzhou.cls.tencentcs.com";
credential.secretId = "Your SecretId";
credential.secretKey = "Your SecretKey";
credential.geoToken = "Your GeoToken";

Unity_CLS.Initialize(credential);

// Set user-defined extended fields
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] Initialization completed.");
}

/// <summary>
/// Perform TCP Ping detection
/// </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] Result: " + response);
};
Unity_CLS.TcpPing(request);
}

/// <summary>
/// Perform ICMP Ping detection
/// </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] Result: " + response);
};
Unity_CLS.Ping(request);
}

/// <summary>
/// Perform HTTP detection
/// </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] Result: " + response);
};
Unity_CLS.Http(request);
}

/// <summary>
/// Perform DNS resolution detection
/// </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] Result: " + response);
};
Unity_CLS.Dns(request);
}

/// <summary>
/// Perform MTR route tracing
/// </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] Result: " + response);
};
Unity_CLS.Mtr(request);
}
}

Callback Description

All detection methods return results via callback, and the callback signature is:
public delegate void callback_response(string response);
The callback parameter `response` is a JSON-formatted string containing detection result data. It includes a `traceId` field for tracking identification.
Note:
Callbacks may be executed on non-main threads. If you need to manipulate Unity UI within a callback, use the main thread dispatch mechanism.
Each detection generates a unique traceId for tracking. The traceId is described as follows:
If request.traceId is not set, the SDK automatically generates a UUID as the traceId.
If request.traceId is manually set, the SDK prepends a short UUID prefix (format: {auto-generated UUID}-{user traceId}) to it to prevent duplication.
The JSON returned by the callback contains a traceId field, which can be used to search for the corresponding detection records in the CLS console.

Extension Field Description

The SDK supports the following two types of extended fields.

User Extension Fields (userCustomField)

Set via Unity_CLS.SetUserCustom(). This setting takes effect globally and is carried by all subsequent probe reports. It is suitable for identifying global information such as user identity and application version.
Dictionary<string, string> userCustomField = new Dictionary<string, string>();
userCustomField.Add("user_id", "12345");
userCustomField.Add("app_version", "2.0.0");
Unity_CLS.SetUserCustom(userCustomField);

Detection Extension Fields (detectCustomField)

Set via the detectCustomField property of each Request object. This setting takes effect only for the current detection and is suitable for identifying the detection scenario, business Tags, and other information.
request.detectCustomField = new Dictionary<string, string>()
{
{ "scene", "game_loading" },
{ "server_region", "ap-shanghai" }
};

Platform Differences

Summary of Parameter Platform Differences

Parameter
Windows
Android
iOS
interval (probe interval)
Partially supported
prefer (IP version preference)
netId (network adapter ID)
src (source identifier)
multiplePortsDetect
enableMultiplePortsDetect
enableVerification(TCP)
payload(TCP)
protocol(MTR)

Multi-Port Detection

Android: Controlled via the multiplePortsDetect field, which defaults to true.
iOS: Controlled via the enableMultiplePortsDetect field, which defaults to false.
Windows: Multi-port detection is not supported.

Underlying Implementation Differences

Platform
Implementation Method
Windows / Editor
Call the C native library via DLL (cls_network_detect.dll) P/Invoke.
Android
Call the Java-layer SDK (AAR package) via AndroidJavaClass.
iOS
Call the Objective-C bridging layer (UnityApi.m → TencentCloudLogProducer.framework) via DllImport __Internal.







Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan