Android SDK 1.1.0

更新时间:2023-09-18 15:37:24

一、SDK兼容说明

兼容项 兼容内容
系统版本 Android 5.0+
Java版本 1.8+
适用架构 armeabi-v7a, arm64-v8a

二、集成SDK

1.导入securelink-sdk-android.aar 和 mars-xlog-1.2.6.aar

  1. 把securelink-sdk-android.aar 和 mars-xlog-1.2.6.aar 复制到工程libs目录下。如果您的APP也使用了mars-xlog,这里就不需要添加,但建议使用相同的版本号,目前最新版本是1.2.6。

  2. 在项目的build.gradle中添加依赖

    方式一(推荐方式):

    dependencies {
      ...
        
      // 添加AAR包
      implementation files('libs/securelink-sdk-android.aar')
      implementation files('libs/mars-xlog-1.2.6.aar')
    }
    

    旧版本AGP的可能不支持,如果报错,请使用方式二。

    方式二:

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
    
    dependencies {
      ...
        
      // 添加AAR包
      implementation(name: 'securelink-sdk-android', ext: 'aar')
      implementation(name: 'mars-xlog-1.2.6', ext: 'aar')
    }
    

2. 配置ABI

目前我们提供armeabi-v7a, arm64-v8a 两种类型的ABI,您可以根据项目中使用到的ABI进行配置:

defaultConfig {
  ...
    
	ndk{
		// 设置您需要的ABI
		abiFilters "armeabi-v7a", "arm64-v8a"
	}
}

三、调用SDK

如果应用是多进程架构,SecureLink SDK 只能在应用的主进程中调用。

1. 初始化SDK

调用如下代码初始化SDK,一次启动只调用一次:

WSLink.getInstance().init(this.getApplicationContext());

初始化函数定义如下:

/***
 * 初始化SDK
 * @param context Application Context
 */
public void init(Context context);

2. 登录

调用登录接口,需要在子线程中执行。

2.1 账号密码登录

调用如下代码进行登录:

int errorCode = WSLink.getInstance().loginWithAccount(sdkToken, username, password);

if (errorCode != 0) {
  Log.e(TAG, "Login with account failed, errorCode=" + errorCode);
} else {
  Log.i(TAG, "Login with account succeed");
}

函数定义:

/***
 * 账号密码登录
 * @param sdkToken SDKToken
 * @param username 用户名
 * @param password 密码
 * @return errorCode 错误码:0表示成功,非0表示失败,详见《错误码说明》
*/
public synchronized int loginWithAccount(String sdkToken, String username, String password);

2.2 OAuth2.0 认证登录

调用如下代码进行登录:

int errorCode = WSLink.getInstance().loginWithOAuth(sdkToken, oauthName, code);

if (errorCode != 0) {
  Log.e(TAG, "Login with oauth2 failed, errorCode=" + errorCode);
} else {
  Log.i(TAG, "Login with oauth2 succeed");
}

函数定义:

/***
 * OAuth2.0登录
 * @param sdkToken SDKToken
 * @param oauthName 身份源名称,由网宿提供
 * @param code 会话Token 
 * @return 返回值 错误码:0表示成功,非0表示失败,详见《错误码说明》
*/
public synchronized int loginWithOAuth(String sdkToken, String oauthName, String code);

3. 启动VPN

调用如下代码启动VPN,由于启动会比较耗时,需要在子线程中执行。


WSSdpListener sdpListener = new WSSdpListener() {
  
  @Override
  public void onError(int code, String msg){
      // VPN启动失败,code详见《错误码说明》
      Log.e(TAG,"onError: code="+code+", msg="+msg);
      ...
  }

  @Override
  public void onConnected(){
      // VPN已连接成功,可以开始请求权限内资源
      Log.i(TAG,"onConnected");
      ...
  }

  @Override
  public void onDisconnected(DisconnectReason disconnectReason){
      // VPN连接已断开,断开原因详见DisconnectReason
      Log.i(TAG,"onDisconnected, reason="+disconnectReason);
      ...
  }
  
  @Override
  void onReconnecting() {
    // VPN重连中
  }
  
}

WSLink.getInstance().startSdp(sdpListener);

VPN断开原因

断开原因 描述 最佳实践
UNKNOWN_ERROR 未知错误 请联系网宿技术支持
NETWORK_ERROR 网络错误 请检查网络再尝试调用start接口
AUTH_FAIL 鉴权失败,可能是:账号被禁用 或 账号过期 或 被踢下线 请重新调用start接口获取原因
VPN_CONFIG_ERROR 配置错误 请联系联系网宿技术支持
VPN_CONFIG_VERIFY_ERROR 配置校验失败 请联系联系网宿技术支持
CONNECTION_TIMEOUT 连接超时 请检查网络再尝试调用start接口
TUN_SETUP_FAILED TUN网卡设置失败 请联系联系网宿技术支持
CLOSE_VPN_BY_USER 用户调用stop接口
CLOSE_VPN_BY_SYSTEM 用户在设置界面关闭VPN 或 用户开启另一个VPN应用 进入应用重新启动SDK
REFRESH_TOKEN_EXPIRED 超过刷新TOKEN的有效时间,需要从头开始登录,重新获取sdkToken 重新获取sdkToken,初始化SDK,然后启动VPN
VPN_SERVICE_DISCONNECTED VPN服务异常断开,可能是VPN进程挂掉 尝试重新调用start

4. 关闭VPN

当您暂时不需要访问权限内资源时,可以调用如下代码关闭VPN:

WSLink.getInstance().stopSdp();

5. 退出登录

当用户退出登录时,请调用如下代码,否则无法重新登录。

WSLink.getInstance().logout();

6. 应用退到后台

由于VPN比较耗电,如果没有特殊需求,建议退到后台一段时间后,关闭VPN,回到前台需要访问权限内资源时,重新开启VPN。

四、用户权限说明

  • 由于SecureLink SDK需要使用VPN,因此当开启VPN时,SDK会主动申请VPN使用权限,如果用户拒绝,则会启动失败。

  • AndroidManifest.xml中定义的用户权限:

    <!-- 网络访问权限 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- VPN服务需要监听网络切换 -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- VPN服务申请为前台服务,避免被系统杀死 -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    

    如上权限已通过aar添加到应用,不需要您手动添加。

五、嵌入成功验证

Logcat过滤tag:WSLink,出现如下日志表示嵌入成功:

I/WSLink: SDK version: 1.1.0
...
I/WSLink: Initialize succeed

注:如果出现错误日志,请联系网宿技术支持。

错误码说明

错误码 错误描述 最佳实践
1000 包名指纹校验不通过 打包应用时,请使用在控制台创建的APP的包名或指纹,否则鉴权将无法通过
1002 SDK 版本校验不通过 获取SDK配置时发生内部错误,请联系网宿技术支持
2001 企业标识不存在 请联系企业管理员或网宿技术支持确认企业标识是否变更或服务是否存在
2005 用户名或者密码错误,请重新输入 提示用户确认用户名或密码
2006 登录设备已达上限 若您购买了客户端同时在线的增值服务,SecureLink会限制可登录设备的数量上限。请提示用户可退出其它设备再登录
2007 账号已禁用, 请联系企业管理员 提示用户账号已被禁用
2022 账号到期,请联系企业管理员 提示用户账号过期
2028 登录过期,请重新登录 提示用户登录过期,重新登录
2032 错误次数超限,账号已锁定 提示用户输入错误次数超限,账号已被锁定
2041 密码已到期,请重置后登录 提示用户密码已到期
2031 账号已在其它设备登录 SecureLink的默认设备规则为后手踢前手,即新设备可以抢占旧设备。建议提示用户: 账号已在其他设备登录,如非本人操作,请立即修改密码
2048 LDAP认证失败,请稍后重试 稍后重新调用WSLink init 接口, 若仍旧失败,请联系企业管理员或网宿技术支持确认LDAP服务是否有异常
2063 非法 SDK TOKEN 请检查 SDK 鉴权逻辑,并重新进行SDK鉴权
2065 用户无权限,请联系管理员 请联系企业管理员
2066 获取用户信息失败 如果是OAuth登录,请检查code是否正确;
2072 管理员非开启OAuth登录权限 请联系网络技术支持,开启OAuth登录权限
6000 内部未知错误 请联系网宿技术支持,详细信息请看logcat
6001 网络不可用 提示用户检查网络是否已连接
6002 网络请求超时 提示用户检查网络或重试
6003 未知网络错误 提示用户检查网络或重试,如果还是错误,请联系网宿技术支持,详细信息请看logcat
6101~6114 配置错误 请联系网宿技术支持,详细信息请看logcat
6115 安全网关鉴权失败 请重新登录
6116 安全网关连接失败 请检查网络或稍后重试,如果未解决,请联系网宿技术支持,详细信息请看logcat
6117 服务端配置获取失败 请尝试重新启动SDP,如果还未解决,请联系网宿技术支持
6118 无可用的安全网关 请检查网络连接后重试,若仍旧失败,请联系网宿技术支持
6124 TUN配置失败 请联系网宿技术支持,详细信息请看logcat
6307 已达最大设备连接数 请联系企业管理员
6312 配置文件找不到 请联系网宿技术支持
6305 用户拒绝开启VPN 提示用户需要开启VPN才可以使用
6304 当前手机不支持VPN 当前手机不支持VPN
6313 绑定状态服务失败 请尝试重新调用startSdp接口,建议是隔5秒再尝试
6314 绑定SDP服务失败 请尝试重新调用startSdp接口
6800 SDK未做初始化 请先调用WSLink init接口
6801 用户关闭SDP
6802 用户登出登录
6803 未登录就启动SDP 请先登录再启动SDP
本篇文档内容对您是否有帮助?
有帮助
我要反馈
提交成功!非常感谢您的反馈,我们会继续努力做到更好!