Android 端网络探测工具使用说明

lvhongzhen · 2023 年7 月 13 日 11:49

网络探测工具是融云提供的一款 SDK 插件，可有效探测当前客户端连接融云服务的质量，返回详细数据报告。

客户将其集成在自己的测试应用或正式应用中，选择合适的时机进行探测，可帮助融云实现质量数据的上报，快速定位、解决问题。

网络探测流程

sequenceDiagram
    App->>NetworkTester: 初始化插件
    NetworkTester-->>App: 成功或失败
    App->>NetworkTester: 注册回调监听
    App->>NetworkTester: 开始探测
    NetworkTester->>Server: 探测中
    NetworkTester-->>App: 回调返回探测中的信息
    App->>NetworkTester: （可选）主动探测探测
    NetworkTester-->>App: 回调返回最终探测结果
    NetworkTester->>Server: 上报探测结果

前提条件

获取 App Key，以及确定 App Key 所属的数据中心
获取 Token，例如当前客户端用户的 Token

集成网络探测插件

网络探测插件支持以 maven 方式集成。

打开根目录下的 build.gradle（Project 视图下），声明[融云的 Maven 代码库]。

allprojects {
    repositories {
        ...
        //融云 maven 仓库地址
        maven {url "https://maven.rongcloud.cn/repository/maven-releases/"}
    }
}

在项目的 build.gradle 文件中添加以下依赖：

dependencies {
    ...
    /// 网络探测工具
    implementation 'cn.rongcloud.sdk:network_detector:1.0.0'
}

探测网络质量

初始化网络探测插件。

RCNetworkDetector.getInstance().init(mContext, appKey, token, category);

category 参数中传入以下数据中心枚举值：

public enum RCEnvironmentCategory {
    BEIJING(1, "BJ"),//北京
    SINGAPORE(2, "singapore"),//新加坡
    NORTH_AMERICA(3, "north america");//北美
}

初始化成功后，注册网络探测结果监听器。探测过程中会通过 onReportNaviResult 逐条上报 Navi 服务地址，通过 onReportCmpResult 逐条上报 CMP 服务地址。一般来说，App 仅需关注 onFinished 返回的最终探测结果。

 RCNetworkDetector.getInstance().addDetectorListener()

public interface RCNetworkDetectorListener {
/**
 * 网络探测开始
 *
 * @param sessionId 会话 ID
 */
void onStartWith(@NonNull String sessionId);

/**
 * 上报 Navi 探测结果
 *
 * @param result Navi 探测结果
 * @param index Navi 索引
 * @param count Navi 总数
 * @param error 错误信息
 */
void onReportNaviResult(
        @NonNull RCNaviConnectResult result, int index, int count, @Nullable RCError error);

/**
 * 上报 CMP 探测结果
 *
 * @param result CMP 探测结果
 * @param index CMP 索引
 * @param count CMP 总数
 * @param error 错误信息
 */
void onReportCmpResult(
        @NonNull RCCMPConnectResult result, int index, int count, @Nullable RCError error);

/**
 * 探测结束
 *
 * @param result 探测结果
 * @param error 错误信息
 */
void onFinished(@RCConstant.DetectorResult int result, @Nullable RCError error);
}

开始探测。
```
RCNetworkDetector.getInstance().start(mWebView);
```
探测过程中会执行上一步中 RCNetworkDetectorListener 监听器的方法, 反馈探测结果。
探测完成后自动结束。

在探测过程进行中，您可以主动停止探测。停止后，插件也会通过 onFinished 返回探测结果。

    RCNetworkDetector.getInstance().stop();

查询网络探测数据

网络探测插件还提供以下查询方法：

      //获取设备信息
      RCNetworkDetector.getInstance().getDeviceInfo();
      //获取会话 ID
      RCNetworkDetector.getInstance().getSessionId();
      //获取导航探测结果
      RCNetworkDetector.getInstance().getNaviResults();
      //获取 CMP 探测结果
      RCNetworkDetector.getInstance().getCMPResult();

参考资源

RCNaviConnectResult

导航探测结果。

//导航探测结果
public class RCNaviConnectResult {
    // navi 地址
    @SerializedName("address")
    private String address;
    // 请求状态
    @SerializedName("status")
    private int status;
    // 总耗时
    @SerializedName("cost")
    private long cost;
    // tcp 耗时
    @SerializedName("connect")
    private long connect;
    // dns 耗时
    @SerializedName("dns")
    private long dns;
    // 系统错误码
    @SerializedName("code")
    private int code;
    // navi 版本
    @RCConstant.NaviVersion
    @SerializedName("version")
    private int version;
    // 远端IP
    @SerializedName("remote")
    private String remote;
    // http 状态码
    @SerializedName("http_code")
    private int httpCode;
    // 系统错误描述
    @SerializedName("message")
    private String message;
}

RCCMPConnectResult

CMP 探测结果。

//CMP探测结果
public class RCCMPConnectResult {
    // 探测地址
    @SerializedName("address")
    private String address;
    //// 探测类型: HttpTLS, HttpNoneTLS, WebSocketTLS, WebSocketNoneTLS
    @RCConstant.CMPType
    @SerializedName("type")
    private String type;
    // 探测状态: 成功,失败, 超时
    @SerializedName("status")
    private int status;
    // 探测耗时
    @SerializedName("cost")
    private long cost;
    //dns耗时
    @SerializedName("dns")
    private long dns;
    //tcp耗时
    @SerializedName("connect")
    private long connect;
    //业务链接耗时
    @SerializedName("bs")
    private long bs;
    //TCP 错误码
    @SerializedName("connect_code")
    private int connectCode;
    // rmtp 错误码
    @SerializedName("rmtp_code")
    private int rmtpCode;
    // 业务链接结果
    @SerializedName("rmtp_status")
    private int rmtpStatus;
}

RCDeviceInfo

设备信息。

//设备信息
public class RCDeviceInfo {
    //系统
    @SerializedName("os")
    private String OS;
    //系统名称
    @SerializedName("os_name")
    private String OSName;
    // 系统版本
    @SerializedName("os_version")
    private String OSVersion;
    //品牌
    @SerializedName("os_brand")
    private String OSBrand;
    // 设备类型
    @SerializedName("device_model")
    private String DeviceModel;
    // 网络类型
    @SerializedName("network_type")
    private String networkType;
    // gateway
    @SerializedName("gateway")
    private String gateway;
    // dns
    @SerializedName("dns")
    private String DNS;
    // 运营商
    @SerializedName("carrier")
    private String carrier;
    // 代理
    @SerializedName("proxy")
    private String proxy;
    // 信号强度
    @SerializedName("signal_strength")
    private String signalStrength;
}

状态码

RCError 中定义了网络探测过程中可能出现的错误码。

状态码	原因
RC_DETECTOR_RESULT_STOPPED_BY_USER	主动调用探测结束接口，提前终止探测
RC_DETECTOR_RESULT_FINISHED	探测成功（正常探测结束）
RC_DETECTOR_RESULT_NETWORK_EXCEPTION	探测失败（网络异常）
RC_DETECTOR_RESULT_OTHER	其他异常