tencent cloud

Cloud Log Service

DocumentaçãoCloud Log ServiceOperation GuideCloud InsightNetwork Probe AnalysisInstructions for Using the Android Network Detection Plugin

Instructions for Using the Android Network Detection Plugin

Download
Modo Foco
Tamanho da Fonte
Última atualização: 2026-06-22 21:58:28

Introduction

Tencent Cloud CLS provides a network quality detection SDK plugin for Android. After integration, the plugin can actively initiate network diagnostic probes such as HTTP Ping, DNS, Ping, MTR, and TCP Ping. The probe data is automatically reported to CLS, helping you monitor end-user network quality in real time and quickly locate network issues.

Prerequisites

Create and obtain the TencentCloud API key information, SecretId and SecretKey. To obtain the key information, go to API Key Management.
You have obtained the mobile access Token in the CLS console. For details, see Obtain Keys.

Integration Steps

Step 1: Introducing the Dependency

In the build.gradle file, simultaneously import the core SDK and the network quality detection plugin:
implementation(group: 'com.tencentcloudapi.cls', name: 'tencentcloud-cls-sdk-android', version: '3.0.1')
implementation(group: 'com.tencentcloudapi.cls', name: 'cls-network-diagnosis-reporter-android', version: '3.0.1')
Dependency Package Description:
Dependency
Description
tencentcloud-cls-sdk-android
Core SDK responsible for reporting detection results to CLS.
cls-network-diagnosis-reporter-android
Network detection plugin that provides capabilities such as HTTP Ping, DNS, Ping, MTR, and TCP Ping.

Step 2: Configuring Permissions

Add the following to the AndroidManifest.xml file:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Step 3: Configuring Network Security (Android 9.0+)

Plain HTTP traffic is blocked by default on Android 9.0 (API 28) and later. You need to configure a network security policy.
1. Create the network_security_config.xml file in the res/xml/ directory.
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
<domain-config cleartextTrafficPermitted="true">
<!-- Replace with the actual CLS domain name as needed -->
<domain includeSubdomains="true">ap-guangzhou.cls.tencentcs.com</domain>
</domain-config>
</network-security-config>
2. Reference it within the <application> Tag in the AndroidManifest.xml file.
Complete AndroidManifest.xml Example:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.tencentcloudapi.cls">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:networkSecurityConfig="@xml/network_security_config">
<activity
android:name=".MainActivity"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>

Step 4: Initializing and Integrating the Plugin

Complete the initialization in Application.onCreate or Activity.onCreate.
private void initCls(Context context) {
// 1. Initialize the core SDK
ClsConfigOptions clsConfigOptions = new ClsConfigOptions(
"https://ap-guangzhou-open.cls.tencentcs.com",
"[log topic ID]",
new Credential("[secret_id]", "[secret_key]"));
clsConfigOptions.enableLog(true);
clsConfigOptions.addTag("cls_android", "3.0.1");
ClsDataAPI.startWithConfigOptions(context, clsConfigOptions);

// 2. Create and configure the network quality detection plugin
INetworkDiagnosisPlugin clsNetDiagnosisPlugin = new NetworkDiagnosisPlugin();
clsNetDiagnosisPlugin.addCustomField("env", "production"); // Optional: Add a custom field
clsNetDiagnosisPlugin.setAppCredentialToken("[mobile access Token]"); // Obtain it from the CLS console

// 3. Register and start the plugin
ClsDataAPI.sharedInstance(context)
.addPlugin(clsNetDiagnosisPlugin)
.startPlugin(context);
}
INetworkDiagnosisPlugin Interface Description:
Methodology
Description
addCustomField(String key, String value)
Adds custom fields and reports them along with the detection results.
setAppCredentialToken(String token)
Sets the mobile access Token.

Step 5: Configuring Obfuscation

If ProGuard or R8 obfuscation is enabled for the project, add the following to the proguard-rules.pro file.
-keep class net.jpountz.lz4.** { *; }

Network Detection API

All detection methods are invoked via CLSNetworkDiagnosis.getInstance(), and the detection results are automatically reported to CLS.

HTTP Ping

Detect the HTTP connectivity, response time, certificate, and other information of the target URL.
public void clsHttpPing(Context context) throws NoSuchAlgorithmException {
INetworkDiagnosis.HttpRequest request = new INetworkDiagnosis.HttpRequest();
request.domain = "https://ap-guangzhou.cls.tencentcs.com"; // Required: Target URL
request.ip = "1.2.3.4"; // Optional: Specify the target IP (bypassing DNS)
request.headerOnly = true; // Optional: Retrieve only the response headers (default: false)
request.downloadBytesLimit = 1024; // Optional: Limit the download bytes (default: 64KB)
request.timeout = 30 * 1000; // Optional: Timeout duration in milliseconds (default: 30000ms)
request.maxTimes = 3; // Optional: Number of detection attempts (default: 10)
request.multiplePortsDetect = false; // Optional: Whether to perform multi-port detection (default: true)
// Optional: SSL certificate verification configuration
request.credential = new INetworkDiagnosis.HttpCredential(getSSLContext(context), null);
// Optional: Custom extension fields
request.extension = new HashMap<String, String>() {{
put("custom_field", "httpPing");
}};
// Without callback
CLSNetworkDiagnosis.getInstance().http(request);
// With callback
CLSNetworkDiagnosis.getInstance().http(request, new INetworkDiagnosis.Callback() {
@Override
public void onComplete(INetworkDiagnosis.Response response) {
CLSLog.i("HTTP", response.content);
}
});
}
HttpRequest Parameter Description:
HttpRequest inherits from PingRequest and contains all the following fields:
Field
Type
Default Value
Required
Description
domain
String
-
Required
Target URL, which must include the protocol header (http:// or https://).
ip
String
null
Optional
Specify the target IP address to skip DNS resolution and connect directly.
headerOnly
boolean
false
Optional
Whether to request only the response headers
downloadBytesLimit
int
65536(64KB)
Optional
Limits the number of bytes to download. A value of 0 indicates no limit.
credential
HttpCredential
null
Optional
SSL certificate verification configuration, which includes SSLContext and X509TrustManager.
timeout
int
30000 (30 seconds)
Optional
Request timeout interval, in milliseconds.
maxTimes
int
10
Optional
Number of probes
size
int(byte)
64
Optional
Probe packet size
multiplePortsDetect
boolean
true
Optional
Whether to enable multi-port detection
extension
Map<String, String>
null
Optional
Custom extension fields, which are reported along with the results.

DNS Resolution

Detect the DNS resolution time and result for the target domain.
public void clsDNSPing() {
INetworkDiagnosis.DnsRequest request = new INetworkDiagnosis.DnsRequest();
request.domain = "ap-guangzhou-open.cls.tencentcs.com"; // Required: Target domain
request.type = INetworkDiagnosis.DNS_TYPE_IPv4; // Optional: DNS type, "A" (IPv4) or "AAAA" (IPv6), default: "A"
request.nameServer = "8.8.8.8"; // Optional: Specify the DNS server address
request.timeout = 2000; // Optional: Timeout duration in milliseconds (default: 2000ms)
request.extension = new HashMap<String, String>() {{
put("custom_field", "dns");
}};
// Without callback
CLSNetworkDiagnosis.getInstance().dns(request);
// With callback
CLSNetworkDiagnosis.getInstance().dns(request, new INetworkDiagnosis.Callback() {
@Override
public void onComplete(INetworkDiagnosis.Response response) {
CLSLog.i("DNS", response.content);
}
});
}
DnsRequest Parameter Description:
DnsRequest inherits from PingRequest and contains all the following fields:
Field
Type
Default Value
Required
Description
domain
String
-
Required
Target domain name
type
String
"A"
Optional
DNS query type: "A" (IPv4) or "AAAA" (IPv6)
nameServer
String
null
Optional
Specify the DNS server address. If left empty, the system default DNS is used.
timeout
int
2000
Optional
Query timeout interval, in milliseconds.
size
int(byte)
64
Optional
Probe packet size
multiplePortsDetect
boolean
true
Optional
Whether to enable multi-port detection
extension
Map<String, String>
null
Optional
Custom extension fields

Ping(ICMP)

Detect the ICMP connectivity and latency for the target domain.
public void clsPing() {
INetworkDiagnosis.PingRequest request = new INetworkDiagnosis.PingRequest();
request.domain = "ap-guangzhou-open.cls.tencentcs.com"; // Required: Target domain
request.size = 64; // Optional: Probe packet size in bytes (default: 64)
request.maxTimes = -1; // Optional: Number of detection attempts (default: 10)
request.timeout = 2000; // Optional: Timeout duration in milliseconds (default: 2000ms)
request.multiplePortsDetect = true; // Optional: Whether to perform multi-port detection (default: true)
request.extension = new HashMap<String, String>() {{
put("custom_field", "ping");
}};
// Without callback
CLSNetworkDiagnosis.getInstance().ping(request);
// With callback
CLSNetworkDiagnosis.getInstance().ping(request, new INetworkDiagnosis.Callback() {
@Override
public void onComplete(INetworkDiagnosis.Response response) {
CLSLog.i("Ping", response.content);
}
});
}
PingRequest Parameter Description:
Field
Type
Default Value
Required
Description
domain
String
-
Required
Target domain name or IP
size
int(byte)
64
Optional
ICMP probe packet size
maxTimes
int
10
Optional
Number of probes
timeout
int
2000
Optional
Timeout interval for a single probe, in milliseconds.
multiplePortsDetect
boolean
true
Optional
Whether to enable multi-port detection
extension
Map<String, String>
null
Optional
Custom extension fields

MTR (Traceroute)

Trace the complete network path to the target domain, supporting both ICMP and UDP protocols.
public void clsMTR() {
INetworkDiagnosis.MtrRequest request = new INetworkDiagnosis.MtrRequest();
request.domain = "ap-guangzhou-open.cls.tencentcs.com"; // Required: Target domain
request.protocol = INetworkDiagnosis.MtrRequest.Protocol.ICMP; // Optional: Detection protocol (default: ALL)
request.maxTTL = 30; // Optional: Maximum hop count (default: 30)
request.maxPaths = 1; // Optional: Maximum number of paths (default: 1)
request.maxTimes = 10; // Optional: Number of detection attempts per hop (default: 10)
request.timeout = 2000; // Optional: Timeout duration in milliseconds (default: 2000ms)
request.multiplePortsDetect = true; // Optional: Whether to perform multi-port detection (default: true)
request.extension = new HashMap<String, String>() {{
put("custom_field", "mtr");
}};
// Without callback
CLSNetworkDiagnosis.getInstance().mtr(request);
// With callback
CLSNetworkDiagnosis.getInstance().mtr(request, new INetworkDiagnosis.Callback() {
@Override
public void onComplete(INetworkDiagnosis.Response response) {
CLSLog.i("MTR", response.content);
}
});
}
MtrRequest Parameter Description:
MtrRequest inherits from PingRequest and contains all the following fields:
Field
Type
Default Value
Required
Description
domain
String
-
Required
Target domain name or IP
protocol
Protocol
Protocol.ALL
Optional
Probing protocol: ALL (all), ICMP, UDP
maxTTL
int
30
Optional
Maximum number of router hops (TTL)
maxPaths
int
1
Optional
Maximum number of probe paths
maxTimes
int
10
Optional
Number of probes per hop
timeout
int
2000
Optional
Timeout interval for a single probe, in milliseconds.
size
int(byte)
64
Optional
Probe packet size
multiplePortsDetect
boolean
true
Optional
Whether to enable multi-port detection
extension
Map<String, String>
null
Optional
Custom extension fields

TCP Ping

Detect the TCP connectivity and latency for the specified port of the target domain.
public void clsTcpPing() {
INetworkDiagnosis.TcpPingRequest request = new INetworkDiagnosis.TcpPingRequest();
request.domain = "ap-guangzhou-open.cls.tencentcs.com"; // Required: Target domain
request.port = 80; // Required: Target port
request.payload = "hello"; // Optional: Probe data to send
request.maxTimes = -1; // Optional: Number of detection attempts (default: 10)
request.timeout = 2000; // Optional: Timeout duration in milliseconds (default: 2000ms)
request.size = 64; // Optional: Probe packet size in bytes (default: 64)
request.multiplePortsDetect = true; // Optional: Whether to perform multi-port detection (default: true)
request.extension = new HashMap<String, String>() {{
put("custom_field", "tcpPing");
}};
// Without callback
CLSNetworkDiagnosis.getInstance().tcpPing(request);
// With callback
CLSNetworkDiagnosis.getInstance().tcpPing(request, new INetworkDiagnosis.Callback() {
@Override
public void onComplete(INetworkDiagnosis.Response response) {
CLSLog.i("TcpPing", response.content);
}
});
}
TcpPingRequest Parameter Description:
TcpPingRequest inherits from PingRequest and contains all the following fields:
Field
Type
Default Value
Required
Description
domain
String
-
Required
Target domain name or IP address
port
int
-1
Required
Target port number
payload
String
null
Optional
Data content sent during probing
maxTimes
int
10
Optional
Number of probes
timeout
int
2000
Optional
Timeout interval for a single probe, in milliseconds.
size
int(byte)
64
Optional
Probe packet size
multiplePortsDetect
boolean
true
Optional
Whether to enable multi-port detection
extension
Map<String, String>
null
Optional
Custom extension fields


Ajuda e Suporte

Esta página foi útil?

comentários