集成与接口参考

Android

4.1.3-alpha.43

版本与入口

通过 Maven 引入 cn.org.bjca.trust.android:ywx-sdk:4.1.3-alpha.43。

仓库：https://nexus-inner.51trust.com/repository/android/。

主入口：cn.org.bjca.sdk.core.kit.BJCASDK.getInstance() 返回 SdkInterface。

Gradle与工程要求

最低 Android 7.0（API 24），Java 8。AndroidX 工程启用 Jetifier。

groovy

// settings.gradle的dependencyResolutionManagement或既有repositories
repositories {
    google()
    mavenCentral()
    maven { url 'https://nexus-inner.51trust.com/repository/android/' }
}
// app/build.gradle
android {
    buildFeatures { buildConfig true }
    defaultConfig {
        minSdkVersion 24
        buildConfigField 'String', 'SIGN_CLIENT_ID', '"您的clientId"'
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
dependencies {
    implementation 'cn.org.bjca.trust.android:ywx-sdk:4.1.3-alpha.43'
}

AndroidX 工程的 gradle.properties

java

android.useAndroidX=true
android.enableJetifier=true

初始化与环境配置

重点：认证客户使用 EnvType.PUBLIC，医信客户使用 EnvType.SZYX。

java

import android.app.Application;
import cn.org.bjca.sdk.core.kit.BJCASDK;
import cn.org.bjca.sdk.core.kit.SdkInterface;
import cn.org.bjca.sdk.core.values.EnvType;

public final class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        SdkInterface sdk = BJCASDK.getInstance();
        sdk.initialize(this, BuildConfig.SIGN_CLIENT_ID);
        sdk.setServerUrl(EnvType.PUBLIC); // 生产环境
        // 集成环境改为：sdk.setServerUrl(EnvType.INTEGRATE);
    }
}

xml

<application android:name=".YourApplication" />

错误码

status	本版含义
0	业务成功
3000	用户取消/当前操作取消
2001	网络或接口响应结构错误
2002	二维码格式或业务校验失败
2003	需要选择授权人
1020	二维码平台与当前环境不符
1001	本地证书不存在
1002	签章不存在
1003	必需参数为空
1004	缺少权限
1006	批量数量不合法
1007	未到可更新时间
1008	免密天数不合法
1009	手机号格式错误
1011 / 1012	生物已开启 / 已关闭或不可用，见方法返回
1013	签名过程中PIN重置成功的流程状态
1014	非托管证书
1015	用户身份不一致
007x001	本地存储或处理失败
002x065	用户与厂商未关联
003x081 / 003x070 / 003x072	数据不存在 / 状态异常 / 非本人待签数据
004x007	服务端证书不存在
004x001	证书身份关键字段异常（004x021按该码归一）
002x039	证书绑定在其他设备
004x009 / 002x033	用户停用 / 注销
002x064 / 005x017	厂商凭证包不足 / 服务凭证数量不足
004x030	证书过期
003x043	当前厂商自动签授权已退出/未匹配

接口说明

初始化 SDK

接口： initialize

设置应用上下文和 clientId。

方法签名

java

void initialize(Context context, String clientId);

调用示例

java

sdk.initialize(context, clientId);

参数	类型	说明
`context`	`Context`	应用或 Activity Context
`clientId`	`String`	分配给接入应用的 clientId

返回结果

无返回值。

设置服务环境

接口： setServerUrl

选择集成环境或生产环境。

方法签名

java

String setServerUrl(EnvType envType);

调用示例

java

String result = sdk.setServerUrl(envType);

参数	类型	说明
`envType`	`EnvType`	PUBLIC／SZYX／INTEGRATE

返回结果

返回设置后的服务根地址；envType 为 null 时返回 null。

envType 取值

环境	EnvType	服务地址
集成	`INTEGRATE`	`https://test.51trust.com/`
生产	`PUBLIC`	`https://www.51trust.com/`
医信生产	`SZYX`	`https://www.51szyx.com/`

设置页面导航栏

接口： changeActionBar

设置 SDK 页面标题、颜色和返回图标。

方法签名

java

void changeActionBar(ActionbarBean bean);

调用示例

java

ActionbarBean bean = new ActionbarBean(
    "#FFFFFF", "#FFFFFF", R.drawable.ic_back, "签名", "#333333");
sdk.changeActionBar(bean);

参数	类型	说明
`bean`	`ActionbarBean`	导航栏样式，构造参数见下表

bean 构造参数（按表格顺序传入）

字段	类型	含义
actionBarColor	String	导航栏背景色
statusBarColor	String	状态栏背景色
backIcon	int	返回图标 drawable 资源 ID
title	String	页面标题
titleColor	String	标题颜色

返回结果

无返回值。

获取当前环境

接口： getServerEnvType

读取 SDK 当前使用的服务环境。

方法签名

java

EnvType getServerEnvType();

调用示例

java

EnvType result = sdk.getServerEnvType();

参数： 无。

返回结果

返回当前 EnvType；默认 PUBLIC。

设置页面语言

接口： setLanguage

切换 SDK 页面的显示语言。

方法签名

java

void setLanguage(String language);

调用示例

java

sdk.setLanguage(language);

参数	类型	说明
`language`	`String`	语言标识，取值见返回说明

返回结果

无返回值；language 支持 zh、en。

获取 SDK 版本

接口： getVersion

读取当前集成的 SDK 版本号。

方法签名

java

String getVersion();

调用示例

java

String result = sdk.getVersion();

参数： 无。

返回结果

返回 SDK 版本字符串 4.1.3-alpha.43。

查询当前用户证书

接口： existsCert

查询当前用户是否有本地证书。

方法签名

java

boolean existsCert(Context context);

调用示例

java

boolean result = sdk.existsCert(context);

参数	类型	说明
`context`	`Context`	应用或 Activity Context

返回结果

返回 boolean；存在本地证书为 true，否则为 false。

查询指定手机号证书

接口： existsCert

查询指定手机号的本地证书。

方法签名

java

boolean existsCert(Context context, String phone);
boolean existsCert(Context context, String phone, String firmId);

调用示例

java

boolean result = sdk.existsCert(context, phone);

参数	类型	说明
`context`	`Context`	应用或 Activity Context
`phone`	`String`	当前用户的 11 位手机号

指定厂商的调用示例

java

boolean scopedResult = sdk.existsCert(context, phone, firmId);

字段	类型	说明
firmId	String	查询的厂商标识；空值使用初始化的 clientId。

返回结果

返回 boolean；存在本地证书为 true，否则为 false。

清除本地证书

接口： clearCert

清除当前环境分区的全部本地证书及相关授权状态。

方法签名

java

String clearCert(Context context);

调用示例

java

String result = sdk.clearCert(context);

参数	类型	说明
`context`	`Context`	应用或 Activity Context

返回结果

返回清除前的 OpenId；无对应记录时为空字符串。清除本地证书、签章及免密和生物识别授权。

获取用户信息

接口： getUserInfo

查询当前证书用户的资料。

方法签名

java

void getUserInfo(Context context, String clientIdOrFirmId, YWXListener listener);

调用示例

java

sdk.getUserInfo(context, clientId, listener);

参数	类型	说明
`context`	`Context`	应用或 Activity Context
`clientId`	`String`	分配给接入应用的 clientId
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回用户资料 JSON；status 为 0 时成功。

字段	类型	说明
data.openId	String	用户 OpenId
data.userName	String	用户姓名
data.startTime / data.endTime	String	证书起止时间
data.nowTime	String	服务端时间
data.existsStamp	boolean	是否有签章
data.deviceFit	boolean	是否与证书绑定设备一致
data.enableUpdateCert	boolean	是否进入证书可更新期
data.certUpdateTipDay	int	证书到期前可更新天数

获取用户 OpenId

接口： getOpenId

读取当前证书用户的 OpenId。

方法签名

java

String getOpenId(Context context);

调用示例

java

String result = sdk.getOpenId(context);

参数	类型	说明
`context`	`Context`	应用或 Activity Context

返回结果

同步返回当前用户 OpenId；无记录时为空字符串，context 无效时为 null。

下载证书

接口： certDown

打开 SDK 证书申领与下载流程。

方法签名

java

void certDown(Activity activity, String clientIdOrFirmId, String phone, YWXListener listener);

调用示例

java

sdk.certDown(activity, clientId, phone, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`phone`	`String`	当前用户的 11 位手机号
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回结果：0 下载成功，3000 用户取消，其余状态为失败。

listener 回调字段

字段	类型	说明
status	String	0 成功，3000 取消，其余为失败码
message	String	结果说明
data	Object 或 null	接口返回数据

回调处理示例

java

YWXListener listener = raw -> runOnUiThread(() -> {
    try {
        JSONObject result = new JSONObject(raw);
        String status = result.optString("status");
        String message = result.optString("message");
        Object data = result.opt("data");
        if ("0".equals(status)) {
            // 读取 data。
        } else {
            // 显示 message。
        }
    } catch (JSONException error) {
        // 处理 JSON 解析错误。
    }
});

更新证书

接口： certUpdate

打开当前用户的证书更新流程。

方法签名

java

void certUpdate(Activity activity, String clientIdOrFirmId, YWXListener listener);

调用示例

java

sdk.certUpdate(activity, clientId, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回结果：0 更新成功，1007 未到可更新时间，3000 用户取消。

重置签名密码

接口： certResetPin

打开签名 PIN 重置流程。

方法签名

java

void certResetPin(Activity activity, String clientIdOrFirmId, YWXListener listener);

调用示例

java

sdk.certResetPin(activity, clientId, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回结果：0 重置成功，3000 用户取消。

查看证书详情

接口： showCertActivity

打开 SDK 证书详情页面。

方法签名

java

void showCertActivity(Activity activity, String clientIdOrFirmId, YWXListener listener);

调用示例

java

sdk.showCertActivity(activity, clientId, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回结果：0 表示已取得详情并打开页面；1001 表示本地证书不存在，其余为查询失败。

查询签章是否存在

接口： existsStamp

检查当前用户是否已设置签章图片。

方法签名

java

boolean existsStamp(Context context);
boolean existsStamp(Context context, String firmId);

调用示例

java

boolean result = sdk.existsStamp(context);

参数	类型	说明
`context`	`Context`	应用或 Activity Context

指定厂商的调用示例

java

boolean scopedResult = sdk.existsStamp(context, firmId);

字段	类型	说明
firmId	String	查询的厂商标识；空值使用初始化的 clientId。

返回结果

返回 boolean；有签章为 true，无签章为 false。

获取签章图片

接口： getStampPic

读取当前用户的 Base64 签章图片。

方法签名

java

String getStampPic(Context context);
String getStampPic(Context context, String firmId);

调用示例

java

String result = sdk.getStampPic(context);

参数	类型	说明
`context`	`Context`	应用或 Activity Context

指定厂商的调用示例

java

String scopedResult = sdk.getStampPic(context, firmId);

字段	类型	说明
firmId	String	查询的厂商标识；空值使用初始化的 clientId。

返回结果

返回 Base64 签章图片；无签章为空字符串，context 无效时可为 null。

设置签章图片

接口： drawStamp

打开 SDK 手写签章页面并保存签章。

方法签名

java

void drawStamp(Activity activity, String clientIdOrFirmId, YWXListener listener);

调用示例

java

sdk.drawStamp(activity, clientId, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回结果：0 保存成功，3000 取消；成功后可调用 getStampPic 获取图片。

查询免密状态

接口： isPinExempt

读取当前用户是否已开启免密签名。

方法签名

java

boolean isPinExempt(Context context);

调用示例

java

boolean result = sdk.isPinExempt(context);

参数	类型	说明
`context`	`Context`	应用或 Activity Context

返回结果

返回 boolean；免密有效为 true，否则为 false。

开启免密签名

接口： keepPin

校验 PIN 并设置免密有效天数。

方法签名

java

void keepPin(Activity activity, String clientId, int keepDay, YWXListener listener);

调用示例

java

sdk.keepPin(activity, clientId, keepDay, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	初始化时传入的 clientId
`keepDay`	`int`	免密有效天数，1～60
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回结果：0 开启成功，1008 天数不合法，3000 用户取消。

关闭免密签名

接口： clearPin

关闭免密签名。

方法签名

java

boolean clearPin(Context context);

调用示例

java

boolean result = sdk.clearPin(context);

参数	类型	说明
`context`	`Context`	应用或 Activity Context

返回结果

返回 boolean；关闭成功为 true，无对应证书或参数无效为 false。

设置生物识别签名

接口： alterFingerSignState

开启或关闭当前用户的生物识别签名。

方法签名

java

void alterFingerSignState(Context context, FingerSignState fingerSignState, YWXListener listener);

调用示例

java

sdk.alterFingerSignState(activity, FingerSignState.on, listener);

参数	类型	说明
`context`	`Context`	用于展示 PIN 和生物识别弹窗的 Activity
`fingerSignState`	`FingerSignState`	生物签名状态：on／off
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回设置结果：0 成功、3000 取消、1011 已开启、1012 已关闭或设备不可用。

查询生物识别状态

接口： getFingerSignState

读取当前用户的生物识别签名开关状态。

方法签名

java

FingerSignState getFingerSignState(Context context);

调用示例

java

FingerSignState result = sdk.getFingerSignState(context);

参数	类型	说明
`context`	`Context`	应用或 Activity Context

返回结果

返回 FingerSignState.on 或 FingerSignState.off。

显示 PIN 输入框

接口： showPinWindow

打开 SDK PIN 输入窗口并取得输入结果。

方法签名

java

void showPinWindow(Activity activity, YWXListener listener);

调用示例

java

sdk.showPinWindow(activity, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

成功 data 包含 pin（输入的 PIN 字符串）和 pinForNet（用于请求传输的加密 PIN 字符串）；用户取消为 3000，忘记密码重置完成返回 1013。

关闭 PIN 输入框

接口： hidePinWindow

关闭已显示的 SDK PIN 输入窗口。

方法签名

java

void hidePinWindow(YWXListener listener);

调用示例

java

sdk.hidePinWindow(listener);

参数	类型	说明
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回 status="0"；未显示窗口时同样成功。被关闭窗口的 showPinWindow 回调返回 3000。

签署待签数据

接口： sign

对服务端生成的待签 ID 列表完成签署。

方法签名

java

void sign(Activity activity, String clientIdOrFirmId, List<String> uniqueIdList, YWXListener listener);

调用示例

java

sdk.sign(activity, clientId, uniqueIdList, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`uniqueIdList`	`List<String>`	服务端生成的待签 ID 列表，1～100 项
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回签署结果；单次 1～100 个待签 ID，0 成功、3000 取消。

开启自动签名

接口： signForSignAuto

打开自动签名授权流程。

方法签名

java

void signForSignAuto(Activity activity, String clientIdOrFirmId, String sysTag, YWXListener listener);

调用示例

java

sdk.signForSignAuto(activity, clientId, sysTag, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`sysTag`	`String`	业务系统标识
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回开启结果，0 成功、3000 取消。

查询自动签名信息

接口： signAutoInfo

查询当前用户的自动签授权信息。

方法签名

java

void signAutoInfo(Activity activity, String clientIdOrFirmId, YWXListener listener);

调用示例

java

sdk.signAutoInfo(activity, clientId, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回自动签授权信息；未开通或未匹配授权时可返回 003x043。

字段	类型	说明
data.signTotal	number	已签数量
data.selfSignSession.clientId	String	授权厂商标识
data.selfSignSession.clientName	String	授权厂商名称
data.selfSignSession.endTime	String	授权到期时间
data.selfSignSession.sdk	boolean	是否 SDK 授权
data.selfSignSession.version	String	授权版本
data.selfSignSession.sysTags	String[]	授权业务系统标识列表

关闭自动签名

接口： stopSignAuto

关闭指定业务系统的自动签授权。

方法签名

java

void stopSignAuto(Activity activity, String clientIdOrFirmId, String sysTag, YWXListener listener);

调用示例

java

sdk.stopSignAuto(activity, clientId, sysTag, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`sysTag`	`String`	业务系统标识
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回关闭结果；0 表示关闭成功。

处理业务二维码

接口： qrDispose

接收扫码文本并执行签名或授权登录流程，默认直接进入当前用户的授权登录。

方法签名

java

void qrDispose(Activity activity, String clientIdOrFirmId, String qrText, YWXListener listener);

调用示例

java

sdk.qrDispose(activity, clientId, qrText, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`qrText`	`String`	扫码取得的完整文本
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回二维码业务处理结果；2002 为二维码校验失败，2003 为需要选择授权人，1020 为二维码平台与当前环境不符。

处理二维码与授权登录

接口： qrDispose

接收扫码文本并执行签名或授权登录流程。

方法签名

java

void qrDispose(Activity activity, String clientIdOrFirmId, String qrText, boolean isHandleGrantOauth, YWXListener listener);

调用示例

java

sdk.qrDispose(activity, clientId, qrText, isHandleGrantOauth, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`qrText`	`String`	扫码取得的完整文本
`isHandleGrantOauth`	`boolean`	true：查询授权人列表；false：直接进入当前用户的授权登录
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回二维码业务处理结果；2002 为二维码校验失败，2003 为需要选择授权人，1020 为二维码平台与当前环境不符。

status 为 2003 时的 data

字段	类型	说明
uuid	String	传给 startOauthLogin 的授权请求 ID
granted	Object[]	可选择的授权人列表
granted[].openId	String	传给 startOauthLogin 的 grantOpenId
granted[].grantDoctorName	String	授权人姓名
granted[].grantedDoctorName	String	被授权人姓名
granted[].startTime / endTime	String	授权起止时间
granted[].grantUniqueId	String	授权记录标识

完成授权登录

接口： startOauthLogin

根据授权请求和所选授权人完成登录流程。

方法签名

java

void startOauthLogin(Activity activity, String clientIdOrFirmId, String uuid, String grantOpenId, String grantUserName, YWXListener listener);

调用示例

java

sdk.startOauthLogin(activity, clientId, uuid, grantOpenId, grantUserName, listener);

参数	类型	说明
`activity`	`Activity`	当前前台 Activity
`clientId`	`String`	分配给接入应用的 clientId
`uuid`	`String`	授权登录请求 ID
`grantOpenId`	`String`	所选授权人的 OpenId
`grantUserName`	`String`	所选授权人的姓名
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

通过 listener 返回授权登录结果；0 成功、3000 取消、1015 用户不匹配。

获取设备标识

接口： getDeviceId

获取 SDK 请求使用的设备标识，返回值位于 data.deviceId。

方法签名

java

void getDeviceId(Context context, YWXListener listener);

调用示例

java

sdk.getDeviceId(context, raw -> {
    try {
        JSONObject result = new JSONObject(raw);
        if ("0".equals(result.optString("status"))) {
            String deviceId = result.getJSONObject("data").getString("deviceId");
        }
    } catch (JSONException error) {
        // 处理回调 JSON 解析失败。
    }
});

参数	类型	说明
context	Context	应用或 Activity Context
listener	YWXListener	在调用线程同步回调

返回结果

成功 data.deviceId 为设备标识字符串；读取或保存失败为 007x001。

导出加密日志

接口： exportEncryptedLogs

导出 SDK 本地加密日志文件。

方法签名

java

void exportEncryptedLogs(Context context, YWXListener listener);

调用示例

java

sdk.exportEncryptedLogs(context, listener);

参数	类型	说明
`context`	`Context`	应用或 Activity Context
`listener`	`YWXListener`	YWXListener 结果回调

返回结果

成功 data 包含 path、segmentCount 和可空的 recordingFailure；失败为 007x001。回调在工作线程执行。

升级指引

必做配置

1. Maven 仓库使用 https://nexus-inner.51trust.com/repository/android/。

2. 依赖更新为 cn.org.bjca.trust.android:ywx-sdk:4.1.3-alpha.43。

3. minSdkVersion 设置为 24 或以上，Java 编译版本使用 8。

4. Application 启动时调用 initialize(context, clientId)，随后设置环境。

java

SdkInterface sdk = BJCASDK.getInstance();
sdk.initialize(this, BuildConfig.SIGN_CLIENT_ID);
sdk.setServerUrl(EnvType.PUBLIC); // 医信客户使用 EnvType.SZYX

旧调用需要修改

使用了旧接口	必须修改为
`showPinWindow(activity, clientId, listener)`	`showPinWindow(activity, listener)`，移除 clientId 参数

按需接入的新接口

需要的功能	接入方法
获取设备标识	`getDeviceId(context, listener)`
导出加密日志	`exportEncryptedLogs(context, listener)`，从 data.path 读取文件路径