泡椒云网络验证系统文档

# Android 快速接入

泡椒云网络验证官方提供的 Android SDK（Java、零第三方依赖，以 AAR 形式提供），方便 Android 开发者接入。

除 Android 版外，官方还提供纯 JVM 可用的 Java 版 jar（内置依赖，Java 8+）， 适用于桌面/服务端等非 Android 的 Java 程序。Java 版 API 与本文档一致， 区别：异步回调在 SDK 工作线程执行（无主线程派发）；设备唯一 ID 需自行生成后传入。

# 接入须知

# 获取方式

  • 下载地址：请登录开发者后台，在首页「最新 SDK」处下载
  • 压缩包内容：sdk/pjysdk-release.aar（SDK 本体）+ app/（示例工程，可直接构建运行）

把 sdk/pjysdk-release.aar 复制到你的工程 app/libs/ 目录，然后在 app/build.gradle 中添加：

dependencies {
    implementation files('libs/pjysdk-release.aar')
}
1
2
3

# 权限与网络配置

SDK 的 AAR 已自带 INTERNET 权限声明。API 走 http，若你的 App targetSdk >= 28，需在 Manifest 的 <application> 上放开明文流量：

<application android:usesCleartextTraffic="true" ...>
1

# 调用形式

每个 API 都有两种形式：

  • 同步：如 Resp<LoginResult> cardLogin()，会阻塞并发起网络请求，禁止在主线程调用，网络异常或签名校验失败时抛出 PJYException；
  • 异步：如 cardLogin(Callback<LoginResult> cb)，内部在工作线程执行，onResult/onError 回调在主线程执行，可直接更新 UI。推荐 Android 上使用异步形式。

# 使用示例

import com.paojiaoyun.PJYSDK;

// 初始化sdk, appKey 和 appSecret 在泡椒云开发者后台获取
PJYSDK pjysdk = new PJYSDK("AppKey", "AppSecret");
pjysdk.setDebug(true);

// 心跳失败回调（主线程）
pjysdk.setOnHeartbeatFailListener(resp -> {
    Log.w("APP", "心跳失败: " + resp.code + " " + resp.message);
    if (resp.code == 10214) {
        // 登录状态已失效（被挤下线等），跳回登录页
        return;
    }
    // 也可以在此尝试重新登录
});

pjysdk.setDeviceId(deviceId); // 设置设备唯一ID，需自行获取并持久化
pjysdk.setCard("Card");       // 设置卡密

// 卡密登录（异步，回调在主线程）
pjysdk.cardLogin(new PJYSDK.Callback<PJYSDK.LoginResult>() {
    @Override
    public void onResult(PJYSDK.Resp<PJYSDK.LoginResult> resp) {
        if (resp.code != 0) {
            Log.e("APP", "登录失败: " + resp.message);
            return;
        }
        // 登录成功，SDK 已自动开始心跳保活
        Log.i("APP", "卡密类型: " + resp.result.cardType
                + " 到期: " + resp.result.expires);
        long remaining = pjysdk.getTimeRemaining(); // 剩余秒数
    }

    @Override
    public void onError(PJYSDK.PJYException e) {
        Log.e("APP", "登录请求异常: " + e.getMessage());
    }
});

// 退出应用时释放（停止心跳并关闭内部线程池）
// pjysdk.release();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 可更改变量

  • pjysdk.setDebug(boolean debug) : 默认为 true，开启后会在 Logcat 输出每次请求的详细信息
  • pjysdk.setDeviceId(String deviceId) : 需自行获取设备码并设置，且不能为空
  • pjysdk.setAutoHeartbeat(boolean enable) : 是否自动开启心跳，默认 true，不建议修改
  • pjysdk.setRetryCount(int count) : 请求失败重试次数，默认为 9 次，调大重试次数有助于提升稳定性

# 可获取变量

以下变量在登录成功后才有有效值，可通过 pjysdk.getLoginResult() 获取（未登录时返回 null）：

  • pjysdk.getLoginResult().cardType : 卡密类型，如 "年卡"
  • pjysdk.getLoginResult().expires : 过期时间字符串，如 "2020-10-16 00:47:58"
  • pjysdk.getLoginResult().expiresTs : 过期时间戳（秒）
  • pjysdk.getLoginResult().config : 卡密或用户的自定义配置
  • pjysdk.getIsTrial() : 是否为试用登录
  • pjysdk.getTimeRemaining() : 剩余有效秒数，可在主线程随时调用
  • pjysdk.getHeartbeatResult() : 最近一次心跳结果

# 初始化

# 初始化 SDK

PJYSDK pjysdk = new PJYSDK(String appKey, String appSecret);
1
参数 必传 类型 说明
appKey 是 String 软件的 app_key，开发者后台获取
appSecret 是 String 软件的 app_secret，开发者后台获取

# 设置设备唯一 ID

pjysdk.setDeviceId(String deviceId); // 不能为空
1
参数 必传 类型 说明
deviceID 是 String 用户设备唯一标识（长度不超过 45 位）

Android 上建议使用 Settings.Secure.ANDROID_ID，取不到时生成 UUID 并用 SharedPreferences 持久化。

# 设置卡密

pjysdk.setCard(String card);
1
参数 必传 类型 说明
card 是 String 用户填写的卡密（长度不超过 45 位）

# 设置用户账号

pjysdk.setUser(String username, String password);
1
参数 必传 类型 说明
username 是 String 用户名（长度不超过 20 位）
password 是 String 用户密码（长度 6-30 位）

# 心跳

登录成功后 SDK 自动启动心跳，无需手动管理。

# 心跳失败回调

pjysdk.setOnHeartbeatFailListener(PJYSDK.HeartbeatFailListener listener);
1

心跳返回 code != 0 时在主线程回调。未设置时默认只打印日志。常见的 code == 10214 表示登录状态已失效（超时未发心跳、被挤下线、后台冻结等），应引导用户重新登录。

# 获取心跳结果

PJYSDK.Resp<PJYSDK.HeartbeatResult> ret = pjysdk.getHeartbeatResult();
1

ret.code == 0 表示心跳正常，否则 ret.message 包含错误信息。

# 获取剩余时长

long remaining = pjysdk.getTimeRemaining();
1

返回剩余有效秒数，不发起网络请求，可在主线程调用。

# 卡密登录

调用前需先调用 setCard 和 setDeviceId。登录成功后自动启动心跳。

Resp<LoginResult> cardLogin() throws PJYException                 // 同步
void cardLogin(Callback<LoginResult> cb)                          // 异步
1
2

返回值：

  • resp.code == 0 表示成功，此时 resp.result 包含详细信息（cardType、expires、expiresTs、config 等）；否则 resp.message 为错误信息。
  • PJYException：仅在网络异常或签名校验失败时抛出（异步形式走 onError 回调）。

# 卡密退出登录

Resp<Void> cardLogout() throws PJYException
void cardLogout(Callback<Void> cb)
1
2

退出登录会停止心跳。

# 卡密解绑设备

需在开发者后台配置软件允许解绑，且需在卡密登录后调用。

Resp<Void> cardUnbindDevice() throws PJYException
void cardUnbindDevice(Callback<Void> cb)
1
2

# 卡密设置解绑密码

需在开发者后台配置软件允许解绑。该密码用于设备丢失等情况解绑。需在卡密登录后调用。

Resp<Void> setCardUnbindPassword(String password) throws PJYException
void setCardUnbindPassword(String password, Callback<Void> cb)
1
2
参数 必传 类型 说明
password 是 String 解绑密码，6-10 位

# 卡密通过密码解绑设备

无需登录，调用前需先 setCard。

Resp<Void> cardUnbindDeviceByPassword(String password) throws PJYException
void cardUnbindDeviceByPassword(String password, Callback<Void> cb)
1
2
参数 必传 类型 说明
password 是 String 解绑密码，6-10 位

# 卡密充值（以卡充卡）

Resp<Void> cardRecharge(String card, String useCard) throws PJYException
void cardRecharge(String card, String useCard, Callback<Void> cb)
1
2
参数 必传 类型 说明
card 是 String 被充值的卡密
useCard 是 String 用于充值的卡密

# 用户注册（通过卡密）

调用前需先调用 setDeviceId。

Resp<Void> userRegister(String username, String password, String card) throws PJYException
void userRegister(String username, String password, String card, Callback<Void> cb)
1
2
参数 必传 类型 说明
username 是 String 用户名（不超过 20 位）
password 是 String 密码（6-30 位）
card 是 String 注册使用的卡密

# 用户登录

调用前需先调用 setUser 和 setDeviceId。登录成功自动心跳。

Resp<LoginResult> userLogin() throws PJYException
void userLogin(Callback<LoginResult> cb)
1
2

# 用户退出登录

Resp<Void> userLogout() throws PJYException
void userLogout(Callback<Void> cb)
1
2

# 用户修改密码

Resp<Void> userChangePassword(String username, String password, String newPassword) throws PJYException
void userChangePassword(String username, String password, String newPassword, Callback<Void> cb)
1
2
参数 必传 类型 说明
username 是 String 用户名
password 是 String 当前密码
newPassword 是 String 新密码（6-30 位）

# 用户充值（通过卡密）

Resp<Void> userRecharge(String username, String card) throws PJYException
void userRecharge(String username, String card, Callback<Void> cb)
1
2
参数 必传 类型 说明
username 是 String 用户名
card 是 String 充值卡密

# 用户解绑设备

需在用户登录后调用。

Resp<Void> userUnbindDevice() throws PJYException
void userUnbindDevice(Callback<Void> cb)
1
2

# 试用登录

调用前需先调用 setDeviceId。登录成功自动心跳。

Resp<TrialLoginResult> trialLogin() throws PJYException
void trialLogin(Callback<TrialLoginResult> cb)
1
2

# 试用退出登录

Resp<Void> trialLogout()
void trialLogout(Callback<Void> cb)
1
2

仅清除本地状态并停止心跳，无网络请求。

# 获取卡密配置

Resp<ConfigResult> getCardConfig() throws PJYException
void getCardConfig(Callback<ConfigResult> cb)
1
2

成功时 resp.result.config 为配置内容。

# 更改卡密配置

Resp<Void> updateCardConfig(String config) throws PJYException
void updateCardConfig(String config, Callback<Void> cb)
1
2
参数 必传 类型 说明
config 是 String 自定义配置（不超过 512 位）

# 获取用户配置

Resp<ConfigResult> getUserConfig() throws PJYException
void getUserConfig(Callback<ConfigResult> cb)
1
2

# 更改用户配置

Resp<Void> updateUserConfig(String config) throws PJYException
void updateUserConfig(String config, Callback<Void> cb)
1
2
参数 必传 类型 说明
config 是 String 自定义配置（不超过 512 位）

# 获取软件配置

Resp<ConfigResult> getSoftwareConfig() throws PJYException
void getSoftwareConfig(Callback<ConfigResult> cb)
1
2

# 获取软件公告

Resp<NoticeResult> getSoftwareNotice() throws PJYException
void getSoftwareNotice(Callback<NoticeResult> cb)
1
2

成功时 resp.result.notice 为公告内容。

# 获取软件最新版本

Resp<VersionResult> getSoftwareLatestVersion(String currentVersion) throws PJYException
void getSoftwareLatestVersion(String currentVersion, Callback<VersionResult> cb)
1
2
参数 必传 类型 说明
currentVersion 是 String 当前本地版本（不超过 30 位）

成功时 resp.result 包含 version、downloadUrl、updateLog。

# 获取远程变量

Resp<ValueResult> getRemoteVar(String key) throws PJYException
void getRemoteVar(String key, Callback<ValueResult> cb)
1
2
参数 必传 类型 说明
key 是 String 远程变量名（不超过 64 位）

# 获取远程数据

Resp<ValueResult> getRemoteData(String key) throws PJYException
void getRemoteData(String key, Callback<ValueResult> cb)
1
2
参数 必传 类型 说明
key 是 String 数据 key（不超过 64 位）

# 操作远程数据

# 新增远程数据

Resp<Void> createRemoteData(String key, String value) throws PJYException
void createRemoteData(String key, String value, Callback<Void> cb)
1
2
参数 必传 类型 说明
key 是 String 数据 key（不超过 64 位）
value 是 String 数据值（不超过 256 位）

# 修改远程数据

Resp<Void> updateRemoteData(String key, String value) throws PJYException
void updateRemoteData(String key, String value, Callback<Void> cb)
1
2
参数 必传 类型 说明
key 是 String 数据 key（不超过 64 位）
value 是 String 数据值（不超过 256 位）

# 删除远程数据

Resp<Void> deleteRemoteData(String key) throws PJYException
void deleteRemoteData(String key, Callback<Void> cb)
1
2
参数 必传 类型 说明
key 是 String 数据 key（不超过 64 位）

# 调用远程函数

Resp<RemoteFuncResult> callRemoteFunc(String funcName, Object... params) throws PJYException
void callRemoteFunc(String funcName, Object[] params, Callback<RemoteFuncResult> cb)
1
2
参数 必传 类型 说明
funcName 是 String 远程函数名（不超过 64 位）
params 是 Object... 参数列表，如 1, 2

示例 远程函数定义（JavaScript）：

function add(a, b) {
  return a + b;
}
1
2
3

Java 调用：

pjysdk.callRemoteFunc("add", new Object[]{1, 2},
        new PJYSDK.Callback<PJYSDK.RemoteFuncResult>() {
    @Override
    public void onResult(PJYSDK.Resp<PJYSDK.RemoteFuncResult> resp) {
        if (resp.code == 0 && resp.result != null) {
            Log.i("APP", "计算结果: " + resp.result.returnValue);
        }
    }

    @Override
    public void onError(PJYSDK.PJYException e) {
        Log.e("APP", "调用异常: " + e.getMessage());
    }
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 释放资源

pjysdk.release();
1

停止心跳并关闭内部线程池，退出应用（如 Activity.onDestroy）时调用。实例释放后不可再使用。

提示：所有 API 的返回值均为 Resp<T>：

  • 同步形式在网络请求或签名校验失败时抛出 PJYException，异步形式走 onError 回调；
  • 未抛异常时，通过 resp.code 判断业务状态：0 成功，非 0 失败，详细信息见 resp.message。返回码含义见接入须知中的对照表。

← Auto.js 快速接入 →