iOS小技能：开发 uni 原生插件(支持iOS Extension)

2023-01-07 477

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

简介： 背景：app采用uni实现需求： iOS App前台后台离线（杀死情况下）推送语音播报（到账xx元、收款播报、自定义推送铃）。实现方式：uni-app 原生插件(支持iOS Extension)

引言

背景：app采用uni实现
需求： iOS App前台后台离线（杀死情况下）推送语音播报（到账xx元、收款播报、自定义推送铃）。

实现方式：uni-app 原生插件(支持iOS Extension)

术语：uni原生插件指的是将 原生开发的功能按照规范封装成插件包，然后即可在 uni-app 前端项目中通过js调用原生能力。

开发环境：

Xcode 12.1 及以上版本
下载开发插件需要的 SDK包并解压
安装 uni-app 开发工具 HBuilderX

I 开发 uni-app 原生插件

1.1 SDK 包结构说明

|--iOSSDK    
    |-- HBuilder-Hello                // uni-app 离线打包工程
    |-- HBuilder-uniPluginDemo        // uni-app 插件开发主工程 （本文档需要使用的工程）
    |-- SDK                            // 依赖库及依赖资源文件
    |-- Feature-iOS.xls                // 功能模块与依赖库对应关系说明表格
    |-- readme.txt                    // 目录说明

SDK 目录中的 HBuilder-uniPluginDemo为 uni原生插件开发主工程，该工程已经将各项配置都配置齐全，开发uni原生插件需要依赖此工程。

1.2 目录格式配置

uni原生插件（native plugin）提交DCloud插件市场需按以下目录格式配置：

package.json: 仅云端打包生效，json 格式，不能有注释。

{
    "name": "插件名称",
    "id": "插件标识，需要保证唯一性",
    "version": "插件版本号",
    "description": "插件描述信息",
    "_dp_type":"nativeplugin",
    "_dp_nativeplugin":{
        "android": {
            "plugins": [
                {
                    "type": "module|component, 必填, 根据插件类型选择",
                    "name": "必填, 注册插件的名称, 注意：module 的 name 必须以插件id为前缀或和插件id相同，比如 `DCTestUniPlugin-TestModule`，其中 DCTestUniPlugin 为插件的id，避免与其他插件冲突，component 的 name 没有强制要求，但是也要保证唯一比如 `dc-map`",
                    "class": "必填, 注册插件的类名"
                }
            ],
            "hooksClass": "可选, 事件钩子注册类名",
            "integrateType": "必填, 可取值aar|jar",
            "dependencies": [
                "可选, 依赖的库名称"
            ],
            "excludeDependencies": [
                "可选，需要排除的HX内置模块依赖库名称"  //HBuilderX3.1.18+支持：仅在插件与HX内置模块依赖库存在冲突时可能需要，使用前请在官方QQ交流群“DCloud原生开发者群”中联系管理员确认
            ],
            "compileOptions": {  //可选，Java编译参数配置
                "sourceCompatibility": "1.8",
                "targetCompatibility": "1.8"
            },
            "abis": [
                "可选, 支持的abi类型, 可取值armeabi-v7a|arm64-v8a|x86"
            ],
            "minSdkVersion": "可选，支持的Android最低版本，如21",
            "useAndroidX": false,   //可选，是否兼容使用AndroidX  3.2.5+版本后废弃该属性
            "permissions": [
                "可选, 要使用的Android权限列表"
            ],
            "parameters": {
                "插件需要配置的参数名称, 如appid": {
                    "des": "参数描述",
                    "key": "AndroidManifest.xml中添加meta-data节点！对应android:name属性值, 如GETUI_APPID",
                    "placeholder": "build.gradle中添加到manifestPlaceholders中的字段名"
                }
            }
        },
        "ios": {
            "plugins": [
                {
                    "type": "必填, module|component, 根据插件类型选择",
                    "name": "必填, 注册插件的名称, 通常与插件标识一致",
                    "class": "必填, 注册插件的类名" 
                }
            ],
            "integrateType": "必填, 可取值framework|library",
            "hooksClass": "可选, 事件钩子注册类名",
            "frameworks": [
                "依赖的系统库(系统库有.framework和.tbd和.dylib类型)，和第三方.framework动态库;（.a 库或 .framework**静态库**直接放到ios根目录即可，不需要配置）"
            ],
            "embedFrameworks": [
                "依赖的.framework动态库（注意.framework动态库也需要在上面的 frameworks 节点添加配置，同样将动态库.framework文件放到 ios 目录）"
            ],
            "capabilities": {    // 配置应用的capabilities数据（根据XCode规范分别配置到entitlements和plist文件中）
                "entitlements": {    // 合并到工程entitlements文件的数据（json格式）
                },
                "plists": {    // 合并到工程Info.plist文件的数据（json格式）
                }
            },
            "plists": {    // 自定义配置工程Info.plist文件的数据（json格式），优先级高于capabilities->plists
            },
            "assets": [    //HBuilderX2.3.4及以上版本支持
                 "可选，插件要使用的xcassets文件列表，相对于ios目录的路径"
            ],
            "privacies": [
                "可选, 插件使用到的隐私列表，如NSPhotoLibraryUsageDescription"
            ],
            "embedSwift": false,   // 开启 swift 编译支持，如果插件使用了 swift 需要配置此项
            "deploymentTarget": "8.0, 可选，注意：使用 Xcode14 需配置为 "11.0"
            "validArchitectures": [    // 可选，支持的CPU架构类型
                 "arm64"    // 支持多个值，可取值："arm64", "armv7"，注意：使用 Xcode14 需要配置为 “arm64” 
            ],
            "parameters": {
                "插件需要配置的参数名称, 如appid": {
                    "des": "参数描述信息",
                    "key": "参数需要配置到info.plist中的键名, 嵌套时使用:分割，如getui:appid"
                }
            },
            "resources": [
                "可选, 插件要使用的资源文件列表，相对于ios目录的路径 ，HX 3.2.0+ 版本不在推荐使用，请参考文档下面的 “依赖资源文件” 说明"
            ]
        }
    }
}

II iOS Extension（扩展）

HBuilderX3.1.5+版本uni原生插件支持iOS Extension（扩展）。

插件获取方式：

插件市场：todo (500)
公z号：iOS逆向：离线包x10，源码是x15。

2.1 插件作者配置

首先在XCode环境中编译出ipa，将ipa解压后在Payload/XXX.app/PlugIns/ 下可以找到.appex文件将.appex添加到uni原生插件下的 ios/Plugins/ 目录中即可。

2.2 插件使用者配置

默认情况下云端打包不会包含uni原生插件中的iOS扩展，需要在nativeplugins/XX-XXX插件目录下添加ios-extension.json文件配置使用iOS扩展。

插件的目录结构如下:

需要插件作者在使用说明中详细描述告诉插件使用者如何配置ios-extension.json文件

-- HelloUniApp项目目录
  |-- nativeplugins
    |-- KN-NotificationService(实际包含iOS Extension的uni原生插件标识)
      |-- ios-extension.json
      |-- ios-XXXExt.mobileprovision #在苹果开发者中心下载

ios-extension.json文件格式如下：

{
  "XXX.appex": {      //必填，多个iOS Extension需使用多个节点
    "identifier": "uni.XXX.ext",                //必填，Bundle identifier
    "profile": "ios-XXXExt.mobileprovision",    //必填，Provisioning Profile，相对于插件目录的路径。注意：在插件目录中文件必须以ios开头，否则HX不会提交云端打包（后续版本会修复此Bug）
    "plists": {      //可选，合并到iOS Extension的Info.plist中的数据（json格式）
            "KNGroupIdentifier": "group.com.kn.KNDocument.pushvoice"

    },
    "entitlements": { //可选，覆盖iOS Extension的entitlements.plist中的数据（json格式）
                "com.apple.security.application-groups": ["group.com.kn.KNDocument.pushvoice"]

    }
  }
}

plists 可选，JSON类型，需要合并到iOS Extension插件Info.plist文件中的数据。

例如消息推送扩展，可在plists配置GroupIdentifier信息,便于 采用语音合成音频文件后，将文件写到AppGroups的Library/Sounds文件夹下，最后更改UNNotificationSound属性来自定义的收款到账语音。

            "KNGroupIdentifier": "group.com.kn.KNDocument.pushvoice"

从info.plist 获取配置信息KNGroupIdentifier

    // 
    NSDictionary *infoDic=[[NSBundle mainBundle] infoDictionary];
    NSString*  VersionFrontNo =  [infoDic valueForKey:@"KNGroupIdentifier"];

entitlements 可选，JSON类型，需要覆盖到iOS Extension插件entitlements.plist中的数据。

    <key>com.apple.security.application-groups</key>
    <array>
        <string>group.com.kn.KNDocument.pushvoice</string>
    </array>

III 注意事项

3.1 用 Xcode14 制作的原生插件

需要在文档里写清楚仅支持 iOS11 及以上系统版本。

https://blog.csdn.net/z929118967/article/details/127089630
package.json 里添加如下配置

"ios": {
    "deploymentTarget": "11.0",    
    "validArchitectures": [    
        "arm64"
    ],
}
...

3.2 不要将系统的私有API暴露给JS

不要将 oc 的 runtime 暴露给 JS ，不要将一些诸如 dlopen()， dlsym()， respondsToSelector:，performSelector:，method_exchangeImplementations() 动态和不可控的方法暴露给JS，也不要将系统的私有API暴露给JS。否则将可能面临苹果上架审核问题。

3.3 使用推送插件收不到消息

使用第三方推送插件时，云打包需要勾选Push模块，离线SDK需要引入liblibPush.a
本地通知/个推/uniPush平台，在前台时，不会走apns通道，不走apns通道，就不会触发ios通知扩展，极_光推送则可以。

3.4 原生插件支持付费

只有uniCloud插件和原生插件支持付_费，付_费插件不支持下载，也就是付费原生插件目前不支持离线打包。

iOS小技能：开发 uni 原生插件(支持iOS Extension)

引言

I 开发 uni-app 原生插件

1.1 SDK 包结构说明

1.2 目录格式配置

II iOS Extension（扩展）

2.1 插件作者配置

2.2 插件使用者配置

III 注意事项

3.1 用 Xcode14 制作的原生插件

3.2 不要将系统的私有API暴露给JS

3.3 使用推送插件收不到消息

3.4 原生插件支持付费

see also

热门文章

最新文章

相关课程

相关电子书

相关实验场景

热门

活动广场

任务中心

开发者评测

高校计划

乘风者计划

训练营

阿里云MVP

话题

直播

下载

镜像站

技术资料

插件

iOS小技能： 开发 uni 原生插件(支持iOS Extension)

引言

I 开发 uni-app 原生插件

1.1 SDK 包结构说明

1.2 目录格式配置

II iOS Extension（扩展）

2.1 插件作者配置

2.2 插件使用者配置

III 注意事项

3.1 用 Xcode14 制作的原生插件

3.2 不要将系统的私有API暴露给JS

3.3 使用推送插件收不到消息

3.4 原生插件支持付费

see also

热门文章

最新文章

相关课程

相关电子书

相关实验场景

iOS小技能：开发 uni 原生插件(支持iOS Extension)