HarmonyOS WPS Open SDK 实践：上线前检查清单怎么落地

用户093407773514
18 阅读5分钟

把 WPS Open SDK 接到 HarmonyOS 工程后，Demo 能打开文档并不等于可以发版。上线前真正要盯的是：专业版 / 个人版 HAR 与凭据是否配对、registerApp 是否成为硬门禁、enableEdit 与回传开关是否对齐验收、以及 1013 / 未注册异常有没有被业务层吞掉。本文按「身份 → 注册 → 打开 → 回传 → 发布评审」写一版可执行清单，并附可直接改的 TypeScript 片段。

为什么要单独做上线检查

统一版对外口径是接口统一、流程统一，但厂商侧仍会踩两类坑：

  • 申请阶段：调试包与正式包包名不同，却共用一套凭据；或专业版 / 个人版 HAR 混用。
  • 工程阶段：页面里直接 sendRequest，没有「SDK 就绪」状态；编辑验收时忘了 enableEdit = true；开了回传却把 fileUri 当长期路径。

把检查写成发布阻塞项，比发版后热修 registerApp 便宜得多。

身份与版本：发邮件时就定版

发往 m_open_sdk@wps.cn 时写清 Bundle、用途、专业版（ToB）或个人版（ToC）。激活序列号走商务 / 技术支持，与 SDK 凭据不是同一渠道。

检查项专业版个人版
registerApp必须成功必须成功
setWpsFileToken成功回调中设置一般不需要
HAR / 凭据不可与个人版混用不可与专业版混用
enableLocalization 等按专业版语义部分开关设置后不生效

运行时可用 SdkConstants.isPersonalSdk() 分支，但不能用分支「兼容」错误 HAR。上线包打印一次 bundleName，与申请单并排归档。

注册门禁：没有 ready 就不要打开

import {
  WPSApi, Result, ResultCode, SdkConstants,
} from '@wps/wps_sdk';

export function registerForRelease(
  appKey: string,
  appSecret: string,
  proSn?: string
): Promise<void> {
  return new Promise((resolve, reject) => {
    WPSApi.registerApp(appKey, appSecret, {
      onCallback: (r: Result) => {
        if (r.code !== ResultCode.OK) {
          reject(new Error(`${r.code}:${r.msg}`));
          return;
        }
        if (!SdkConstants.isPersonalSdk() && proSn) {
          WPSApi.setWpsFileToken(proSn);
        }
        resolve();
      },
    });
  });
}

上线检查：

  • 冷启动只注册一次，成功后置 ready。
  • 打开入口 await registerForRelease(...) 或订阅就绪态。
  • appSecret / 完整 SN 不进崩溃明文。
  • 限时凭据临近过期提前邮件续期。

打开与回传：参数对齐验收

import { common } from '@kit.AbilityKit';
import {
  WPSApi, OpenFileRequest, TransferType, ResultCode,
} from '@wps/wps_sdk';

async function openChecked(
  ctx: common.UIAbilityContext,
  path: string,
  opts: { edit: boolean; transfer: boolean }
) {
  await registerForRelease(APP_KEY, APP_SECRET, PRO_SN);
  const req = new OpenFileRequest(ctx, path);
  if (opts.edit) req.enableEdit = true;
  if (opts.transfer) req.wpsTransferType = TransferType.URI;
  try {
    const result = await WPSApi.sendRequest(req);
    if (result.code !== ResultCode.OK) {
      throw new Error(result.msg ?? String(result.code));
    }
    // transfer：拷贝 result.data.fileUri 到本应用沙箱
  } catch (e) {
    // 未注册 / 客户端异常等
    console.error(e);
  }
}

勾选：

  1. 系统选择器路径已拷进沙箱。
  2. 编辑用例显式 enableEdit = true。
  3. 需要关窗上传时配置了 wpsTransferType，且完成拷贝联调。
  4. 真机安装匹配版本的 WPS 客户端。
  5. 专业版若不落地，确认分享 / 打印等被覆盖关闭的行为符合产品说明。

失败矩阵与发布评审

现象先查
ResultCode.ERRORkey/secret 空值
1013 / ERROR_CODE_AUTH_FAILURE包名、凭据、HAR 批次
sendRequest 抛异常是否等注册成功
打开非 OK路径 / 客户端
回传 data 空是否开回传

发布评审阻塞项建议写成：身份归档一致；注册成功日志；门禁生效；编辑 / 回传验收通过；密钥脱敏；目标机型端到端通过。邮件回复、HAR 哈希、成功日志一并进仓库或工单附件。

联调节奏、安全与小结

推荐节奏：定版发邮件 → 空壳工程只验证注册 + 打开样例 → 再叠水印 / 回传 → 发布清单勾选。同一 ISV 维护 ToB / ToC 两套 App 时，工程目录隔离 HAR，避免条件编译混包导致偶发 1013。密钥管理上 Debug / Release 分配置；崩溃上报过滤 appSecret 与完整 SN；演示包若必须内置凭据，使用限时试用并标注过期日。

建议把「SDK 就绪」做成可观测状态机：idle → registering → ready / failed。打开入口只订阅 ready；failed 展示错误码与重试，而不是静默再次 sendRequest。热重启 Ability 后优先复用已成功状态，仅在失败或密钥轮换后再次注册。轮换流程写成：停用打开入口 → 替换配置 → 重新注册 → 观察 OK → 恢复入口。

现场支持可准备一键导出：Bundle、HAR 标识、注册结果、最近一次打开 code、客户端版本。有了这些字段，远程排查不必反复要录屏。负面用例也要覆盖：空凭据、未就绪打开、非沙箱路径，确认门禁真的生效。

上线前检查的价值，是把 HarmonyOS 上 WPS 二开的「能演示」推进到「可运维」。registerApp 门禁清楚、参数与验收对齐、回传真正落盘，发版后才不容易被鉴权与路径问题反复打断。字段语义以官方对接文档为准。把清单写进发布模板与 CI 备注，换人维护时成本会明显下降；真机验证时先确认 WPS 客户端可独立打开同类文档，再对照 SDK 日志区分客户端问题与凭据问题。

补充：若业务同时需要只读预览与可编辑两种入口，请用两个明确的打开封装，而不是共用一个默认只读请求再临时改字段，避免验收口径漂移。关窗回传联调时，分别验证「未开回传 data 为空」与「开启回传后拷贝成功」两条路径，UI 文案不要混用「打开成功」与「保存成功」。发版当天再核对一次 HAR 文件修改时间，防止错误合并带回旧包。把发布阻塞项同步到测试用例标题，评审时逐条打勾，比口头确认更可靠。以上检查完成后再切正式流量。

本文基于 WPS Open SDK 鸿蒙版官方对接实践整理，仅供开发者参考。 官方对接文档：365.kdocs.cn/l/clQl5cek2… 技术交流 QQ 群：628436767

avatar
文章
阅读
粉丝