在 HarmonyOS 工程里集成wps/wps_sdk之前很多人会先写OpenFileRequest打开样例文档结果在真机上立刻卡在鉴权。对接文档把链路写得很清楚先拿到与包名绑定的接入凭据和匹配的 HAR再registerApp成功然后才能sendRequest。本文按「申请材料 → 集成 HAR → 注册封装 → 失败归因 → 联调清单」整理一版可落地的实现说明字段语义以官方对接文档为准。一、凭据在调用链中的位置完整接入时序可以概括为通过官方对接文档给出的申请渠道提交应用信息与 Bundle 包名获取appKey/appSecret与 SDK HAR。工程依赖wps/wps_sdk本地 HAR并执行ohpm install。应用启动阶段调用RegisterAppRequest/registerApp等待ResultCode.OK。若当前交付约定需要激活序列号在注册成功回调中调用setWpsFileToken。业务再构造OpenFileRequest等请求走sendRequest。若跳过第 3 步直接打开文档常见表现不是「打开失败的业务 code」而是 Promisereject尚未注册成功。联调时要把「注册态」和「打开态」拆开看日志否则会把鉴权问题误判成路径或客户端版本问题。材料作用绑定关系HAR提供WPSApi与请求类型与申请时声明的 SDK 形态匹配appKey / appSecret校验三方应用接入资格与 Bundle 包名绑定激活序列号按约定产品侧授权补齐与注册成功后的全局 token 设置相关二、申请时要一次性说清的信息申请侧不必堆砌商务话术工程同学最该写清楚的是可核对字段应用名称与简要用途预览 / 编辑 / 是否需要关窗回传。最终安装包的 Bundle 名称调试包与上架包若不同通常要分别申请或明确以哪套为准。联系人与可回访方式按官方渠道要求填写。需要的 SDK 交付形态与 HAR 批次一致避免混用。包名写错是后续ERROR_CODE_AUTH_FAILURE文档码值常见为 1013的高频根因本地代码、签名配置、申请单三者不一致。建议在 CI 或打包脚本里打印一次bundleName和申请单截图并排归档。凭据本身由 WPS 签发与管理应用侧只负责安全保存与注入不要把 secret 打进 Release 日志或公开仓库。三、集成 HAR 与最小注册封装oh-package.json5典型依赖写法{ dependencies: { wps/wps_sdk: file:./libs/wps_sdk.har } }将交付的wps_sdk.har放入./libs/后执行ohpm install。换 HAR 批次后务必 clean避免旧 so / 旧类型定义让联调结论漂移。注册建议收成可复用函数避免每个页面各写一份回调import{common}fromkit.AbilityKit;import{WPSApi,RegisterAppRequest,ResultCode,}fromwps/wps_sdk;letwpsReadyfalse;asyncfunctionensureRegistered(ctx:common.UIAbilityContext,appKey:string,appSecret:string,activationSn?:string):Promisevoid{if(wpsReady)return;constresultawaitWPSApi.sendRequest(newRegisterAppRequest(ctx,appKey,appSecret));if(result.codeResultCode.ERROR_CODE_AUTH_FAILURE){thrownewError(auth failure:${result.msg});}if(result.code!ResultCode.OK){thrownewError(register failed:${result.code}${result.msg});}if(activationSn){// 按当前交付约定注入无序列号需求时不要传WPSApi.setWpsFileToken(activationSn);}wpsReadytrue;}说明wpsReady短路重复注册适合冷启动后多入口连点。鉴权失败单独分支方便 UI 提示「凭据或包名不匹配」。setWpsFileToken放在注册成功之后、全局设置一次不要每次OpenFileRequest再塞一遍 token对接文档也更推荐全局设置。四、两套凭证不要混为一谈工程里经常把「SDK 接入凭据」和「激活序列号」说成同一件事联调就会绕弯路。类型典型用途设置时机appKey / appSecret证明应用有权调用 SDKregisterApp/RegisterAppRequest激活序列号按产品授权约定补齐客户端能力注册成功后setWpsFileToken若需要本地校验接入凭据时一般不依赖额外联网失败原因优先查空参、错参、包名不一致、限时凭据过期。序列号是否需要、从哪条渠道获取以你拿到的交付说明与官方对接文档为准不要用包名猜。五、注册失败与打开失败的分层处理现象更可能的原因处理方向sendRequestreject尚未注册成功先看ensureRegistered是否 await 完成code提示参数不完整key/secret 为空或未注入检查 rawfile / 构建 flavorERROR_CODE_AUTH_FAILURE凭据错误或包名不一致对照申请单与实际 Bundle注册 OK打开 ERROR路径、客户端、参数层与凭据解耦排查限时凭据失效过期按官方渠道续期或重申生产提示建议拆开「注册失败」「打开失败」「回传失败」不要合成一句「WPS 坏了」。Debug 日志统一前缀例如[WPS][auth]输出code/msg/bundleName勿打印完整 secret。六、联调清单与工程约定建议固定几条门禁减少「预发正常、上架才炸」申请单 Bundle 与安装包一致含调试包策略。HAR 与凭据来自同一申请批次未混用。启动路径必定先注册成功再亮打开按钮。多 flavor 使用不同 rawfile 注入 keyCI 打印包名。换 HAR 后 clean 重装依赖。需要序列号时只在注册成功回调设置一次。单测覆盖重复调用短路、鉴权失败、注册 OK 无 token、注册 OK 有 token。页面层禁止直接new RegisterAppRequest散落各处统一走ensureRegistered。后续叠水印、extraOptions、关闭回传都建立在「注册态已就绪」之上。七、小结鸿蒙侧 WPS Open SDK 的接入门槛表面上是几个字符串实际上是申请材料正确性 HAR 匹配 注册时序三条线。把 Bundle 包名写准、把注册收成模块、把鉴权失败与打开失败分层联调成本会明显下降。字段与错误码以官方对接文档为准工程稳定后日常只是换 flavor 或续期凭据不必每次从打开按钮反向排查。基于 WPS Open SDK 鸿蒙版对接实践整理仅供开发者参考。官方对接文档https://365.kdocs.cn/l/clQl5cek2NoT
在 HarmonyOS 工程里集成wps/wps_sdk之前很多人会先写OpenFileRequest打开样例文档结果在真机上立刻卡在鉴权。对接文档把链路写得很清楚先拿到与包名绑定的接入凭据和匹配的 HAR再registerApp成功然后才能sendRequest。本文按「申请材料 → 集成 HAR → 注册封装 → 失败归因 → 联调清单」整理一版可落地的实现说明字段语义以官方对接文档为准。一、凭据在调用链中的位置完整接入时序可以概括为通过官方对接文档给出的申请渠道提交应用信息与 Bundle 包名获取appKey/appSecret与 SDK HAR。工程依赖wps/wps_sdk本地 HAR并执行ohpm install。应用启动阶段调用RegisterAppRequest/registerApp等待ResultCode.OK。若当前交付约定需要激活序列号在注册成功回调中调用setWpsFileToken。业务再构造OpenFileRequest等请求走sendRequest。若跳过第 3 步直接打开文档常见表现不是「打开失败的业务 code」而是 Promisereject尚未注册成功。联调时要把「注册态」和「打开态」拆开看日志否则会把鉴权问题误判成路径或客户端版本问题。材料作用绑定关系HAR提供WPSApi与请求类型与申请时声明的 SDK 形态匹配appKey / appSecret校验三方应用接入资格与 Bundle 包名绑定激活序列号按约定产品侧授权补齐与注册成功后的全局 token 设置相关二、申请时要一次性说清的信息申请侧不必堆砌商务话术工程同学最该写清楚的是可核对字段应用名称与简要用途预览 / 编辑 / 是否需要关窗回传。最终安装包的 Bundle 名称调试包与上架包若不同通常要分别申请或明确以哪套为准。联系人与可回访方式按官方渠道要求填写。需要的 SDK 交付形态与 HAR 批次一致避免混用。包名写错是后续ERROR_CODE_AUTH_FAILURE文档码值常见为 1013的高频根因本地代码、签名配置、申请单三者不一致。建议在 CI 或打包脚本里打印一次bundleName和申请单截图并排归档。凭据本身由 WPS 签发与管理应用侧只负责安全保存与注入不要把 secret 打进 Release 日志或公开仓库。三、集成 HAR 与最小注册封装oh-package.json5典型依赖写法{ dependencies: { wps/wps_sdk: file:./libs/wps_sdk.har } }将交付的wps_sdk.har放入./libs/后执行ohpm install。换 HAR 批次后务必 clean避免旧 so / 旧类型定义让联调结论漂移。注册建议收成可复用函数避免每个页面各写一份回调import{common}fromkit.AbilityKit;import{WPSApi,RegisterAppRequest,ResultCode,}fromwps/wps_sdk;letwpsReadyfalse;asyncfunctionensureRegistered(ctx:common.UIAbilityContext,appKey:string,appSecret:string,activationSn?:string):Promisevoid{if(wpsReady)return;constresultawaitWPSApi.sendRequest(newRegisterAppRequest(ctx,appKey,appSecret));if(result.codeResultCode.ERROR_CODE_AUTH_FAILURE){thrownewError(auth failure:${result.msg});}if(result.code!ResultCode.OK){thrownewError(register failed:${result.code}${result.msg});}if(activationSn){// 按当前交付约定注入无序列号需求时不要传WPSApi.setWpsFileToken(activationSn);}wpsReadytrue;}说明wpsReady短路重复注册适合冷启动后多入口连点。鉴权失败单独分支方便 UI 提示「凭据或包名不匹配」。setWpsFileToken放在注册成功之后、全局设置一次不要每次OpenFileRequest再塞一遍 token对接文档也更推荐全局设置。四、两套凭证不要混为一谈工程里经常把「SDK 接入凭据」和「激活序列号」说成同一件事联调就会绕弯路。类型典型用途设置时机appKey / appSecret证明应用有权调用 SDKregisterApp/RegisterAppRequest激活序列号按产品授权约定补齐客户端能力注册成功后setWpsFileToken若需要本地校验接入凭据时一般不依赖额外联网失败原因优先查空参、错参、包名不一致、限时凭据过期。序列号是否需要、从哪条渠道获取以你拿到的交付说明与官方对接文档为准不要用包名猜。五、注册失败与打开失败的分层处理现象更可能的原因处理方向sendRequestreject尚未注册成功先看ensureRegistered是否 await 完成code提示参数不完整key/secret 为空或未注入检查 rawfile / 构建 flavorERROR_CODE_AUTH_FAILURE凭据错误或包名不一致对照申请单与实际 Bundle注册 OK打开 ERROR路径、客户端、参数层与凭据解耦排查限时凭据失效过期按官方渠道续期或重申生产提示建议拆开「注册失败」「打开失败」「回传失败」不要合成一句「WPS 坏了」。Debug 日志统一前缀例如[WPS][auth]输出code/msg/bundleName勿打印完整 secret。六、联调清单与工程约定建议固定几条门禁减少「预发正常、上架才炸」申请单 Bundle 与安装包一致含调试包策略。HAR 与凭据来自同一申请批次未混用。启动路径必定先注册成功再亮打开按钮。多 flavor 使用不同 rawfile 注入 keyCI 打印包名。换 HAR 后 clean 重装依赖。需要序列号时只在注册成功回调设置一次。单测覆盖重复调用短路、鉴权失败、注册 OK 无 token、注册 OK 有 token。页面层禁止直接new RegisterAppRequest散落各处统一走ensureRegistered。后续叠水印、extraOptions、关闭回传都建立在「注册态已就绪」之上。七、小结鸿蒙侧 WPS Open SDK 的接入门槛表面上是几个字符串实际上是申请材料正确性 HAR 匹配 注册时序三条线。把 Bundle 包名写准、把注册收成模块、把鉴权失败与打开失败分层联调成本会明显下降。字段与错误码以官方对接文档为准工程稳定后日常只是换 flavor 或续期凭据不必每次从打开按钮反向排查。基于 WPS Open SDK 鸿蒙版对接实践整理仅供开发者参考。官方对接文档https://365.kdocs.cn/l/clQl5cek2NoT
