当 PWC H5 应用运行在第三方 app 中时，部分能力（扫码、定位、拍照等）需要调用宿主 app 的原生接口。由于不同 app 提供的 jsapi 名称和参数各不相同，需要通过"第三方 app 集成插件"来完成适配。

典型场景例如：

• PWC H5 嵌入自研 app，需要调用该 app 的定位接口
• 宿主 app 拦截了系统级拍照，需要走 app 自己的拍照通道

适配原理

PWC 内部已封装了对各类能力的标准调用，开发者无需关心调用时机。适配插件的作用是：将 PWC 的标准方法重写为对宿主 jsapi 的实际调用。

每个宿主 app 对应一个独立插件，通过 UA 关键字与插件绑定。运行时流程如下：

需要适配的能力

能力	方法名	是否必须	说明
扫码	scanCode	强制	用于单行文本字段的扫码功能
获取定位	getLocation	非强制	用于外勤、定位字段等，H5 有实现但可能精度不足
打电话	makePhoneCell	非强制	用于电话字段，H5 无法触发回调导致无法同步新建记录
预览图片	previewImage	非强制	用于图片字段，H5 实现不支持手势缩放
拍照	imageCapture	非强制	宿主 app 拦截系统拍照时需适配
选图片	chooseImage	非强制	宿主 app 拦截系统选图时需适配
关闭 WebView	closeWebView	非强制	用于页面返回/关闭无法正常触发的场景
设置默认标题	getTitle	非强制	返回字符串，用于覆盖默认标题"纷享销客CRM"
控制标题栏显示	isShowTitleBar	非强制	返回 true/false，默认不展示标题栏
设置标题	setWebViewTitle	非强制	宿主不支持 H5 原生设置标题时使用
审批操作完成	approvalOperationCompleted	非强制	审批操作状态回调

不需要适配的方法直接删除即可，无需保留空实现。

开发流程

1. 创建插件

   进入后台，创建自定义插件，支持终端选择 Mobile 端，插件类型选择 第三方 app 集成插件。

   

2. 配置 UA 匹配规则

   在插件配置页填写宿主 app 的 UA 匹配规则。该字段用于将插件绑定到特定 app，值为宿主 app 浏览器 userAgent 中的关键字符，遵循正则表达式规则（不需要加 /）。

   

   示例： 企业微信的 UA 包含 wechat，填写 wechat 即可命中企业微信环境。

   注意

   请先确认宿主 app 的实际 UA 再填写，避免误匹配其他 app。

3. 编写适配代码

   插件代码通过重写 jsapiAdapter 对象上的方法来完成适配。只需实现需要适配的方法，其余方法删除即可。

   每个方法的关键点：

   • 入参：opts 对象，包含 onSuccess、onFail 等回调
   • 出参：调用 opts.onSuccess(result) 时需按规定格式传参
   • 实现：在方法内部调用宿主 app 的实际 jsapi

   详见下方代码示例。

4. 发布并验证

   发布插件后，在对应宿主 app 环境中打开 PWC H5，验证各适配能力是否正常工作。

代码示例

以下示例展示适配写法的基本结构，以扫码和定位为例。每个方法接收 opts 对象，调用宿主 jsapi 后将结果按规定格式传给 opts.onSuccess。

(function(root) {
    root.jsapiAdapter = {

        /**
         * @desc 扫码
         * @param { Function } opts.onSuccess - 成功回调
         * @param { Function } opts.onFail - 失败回调
         */
        scanCode(opts) {
            // 将宿主 app 的扫码调用映射到 PWC 标准格式
            window.xx.scan().then(res => {
                opts.onSuccess({
                    errorCode: 0,
                    success: true,
                    result: res.text
                });
            });
        },

        /**
         * @desc 获取定位
         * @param { Function } opts.onSuccess - 成功回调
         * @param { Function } opts.onFail - 失败回调
         */
        getLocation(opts) {
            jsBridge.invoke('getLocation', {
                onSuccess(res) {
                    opts.onSuccess({
                        errorCode: 0,
                        success: true,
                        longitude: res.long,
                        latitude: res.lant,
                        address: res.address,
                        title: '',
                        country: '',
                        province: '',
                        city: '',
                        district: ''
                    });
                },
                onFail() {
                    opts.onFail('调用失败');
                }
            });
        },

        // 其他需要适配的方法参见下方"下一步"中的钩子文档
    };
})(window);

下一步

• 查看所有可适配的 jsapi 钩子：第三方 app 集成插件钩子