# 鸿蒙集成
# 1 . 获取凭据
集成 SDK 需要先在 FinClip 平台中创建应用并绑定小程序,获得每个应用专属的
SDK KEY
及SDK SECRET
后,随后就可以在集成 SDK 时填写对应的参数。打开小程序时 SDK 会自动初始化,并校验SDK KEY
,SDK SECRET
与BundleID(Application ID)
是否正确。 您可以 【点击这里】 查看如何获取所需要的SDK KEY
及SDK SECRET
。请务必确认集成 SDK 时填写的参数正确,否则会导致小程序无法打开。
# 2. 导入 SDK
请注意
注意:DevEco Studio 至少需要升级到 5.0.3.300,手机系统版本至少升级到 3.0.0.22,对应的鸿蒙版本:5.0.0(12)
# 2.1 配置 SDK
# 2.1.1 通过 oh-package.json5 依赖
- 在项目根目录创建
.ohpmrc
文件,添加以下内容
registry=https://ohpm.openharmony.cn/ohpm/
@finclip:registry=https://ohpm.finogeeks.com/repos/ohpm
- 在项目的
oh-package.json5
的dependencies
字段添加依赖
"@finclip/sdk": "latest"
- 执行
ohpm install
然后注意在鸿蒙工程根目录下的 build-profile.json5 中 app/products
里的元素添加以下代码
"buildOption": {
"strictMode": {
"useNormalizedOHMUrl": true
}
}
# 2.1.2 在 module.json5 配置
如果是以非 Ability 启动的方式可以 跳过这一步骤
由于在鸿蒙上的限制,共享包无法注册 Ability,所以需要宿主 App 注册 Ability 供 FinClip SDK 使用。注册的参考代码如下,可以参考鸿蒙文档 (opens new window)自行修改
{
"name": "AppletAbility",
"srcEntry": "./ets/appletAbility/AppletAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:app_icon",
"launchType": "specified",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:app_icon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"removeMissionAfterTerminate": true
}
# 关键字段说明
字段 | 说明 |
---|---|
name | 自定义 Ability name,在 SDK 初始化时用到 |
srcEntry | 保持默认的 ets 文件即可,可以根据宿主应用的业务逻辑自行修改 |
launchType | 建议使用 specified ,可以同时打开多个小程序且不会重复创建,详细说明可以参考鸿蒙文档 (opens new window) |
removeMissionAfterTerminate | 设置为 true 可以让小程序停止时不在任务列表显示已停止的小程序 |
# launchType: "specified" 的具体配置方式
- 在
module.json5
的module.srcEntry
配置./ets/myabilitystage/MyAbilityStage.ts
,文件名和文件位置可自定义,后续说明以这个路径为例子 MyAbilityStage.ts
内容可参考以下代码
import AbilityStage from '@ohos.app.ability.AbilityStage';
export default class MyAbilityStage extends AbilityStage {
onCreate() {
// 应用的HAP在首次加载的时,为该Module初始化操作
}
onAcceptWant(want): string {
if (want.abilityName === 'AppletAbility') { // 宿主配置的自定义 Ability name
// 返回的字符串Key标识为自定义拼接的字符串内容
// 这里可以通过 want.parameters.request 拿到启动时的部份数据,建议使用 sign 做为小程序唯一标识符
return `ControlModule_AppletAbilityInstance_${want.parameters.request.sign}`;
}
return '';
}
}
# 2.2 SDK 涉及到的敏感权限
如果您集成所有的 SDK,那么涉及到的敏感权限包括:存储、摄像头、录音、读取手机状态、位置、蓝牙、通讯录。这些权限,基本都是调用相应的 api 和组件时才会触发。
以下权限及说明基于目前已实现的 api 和组件,当后续 api 和组件完善后所涉及到的权限列表会更新,请以正式发布的文档为准
# 2.2.1 必要权限
必要权限是指核心功能必须的权限,如果未声明会影响 SDK 正常使用
权限 | 权限名称 |
---|---|
网络 | ohos.permission.INTERNET |
# 2.2.2 非必要权限
非必要权限是指不影响核心功能的使用,只是在某些涉及该权限的 API 或组件无法正常使用或者获取不到正确数据
权限 | 权限名称 | 涉及 API |
---|---|---|
位置 | ohos.permission.APPROXIMATELY_LOCATION、ohos.permission.LOCATION、ohos.permission.LOCATION_IN_BACKGROUND | getLocation、startLocationUpdate、startLocationUpdateBackground 等 |
网络信息 | ohos.permission.GET_NETWORK_INFO、ohos.permission.GET_WIFI_INFO、ohos.permission.SET_WIFI_INFO | getSystemInfo、getNetworkInfo 等 |
蓝牙信息 | ohos.permission.ACCESS_BLUETOOTH | getSystemInfo、蓝牙相关 API 等 |
媒体 | ohos.permission.WRITE_IMAGEVIDEO、ohos.permission.MICROPHONE,ohos.permission.CAMERA | saveImageToPhotosAlbum、Camera相关API 等 |
传感器 | ohos.permission.ACCELEROMETER、ohos.permission.GYROSCOPE,ohos.permission.VIBRATE | enableAccelerometer、enableDeviceMotion、enableGyroscope、enableCompass、vibrateShort、vibrateLong 等 |
联系人 | ohos.permission.WRITE_CONTACTS、ohos.permission.READ_CONTACTS | addPhoneContact 等 |
# 2.2.3 权限配置方式
在 module.json5
文件中 module.requestPermissions
添加对应的权限,否则会出现无法正常使用功能的情况,代码参考如下
"requestPermissions": [
{
"name": "ohos.permission.INTERNET" // 网络权限,如不配置 SDK 启动会失败
},
{
"name" : "ohos.permission.APPROXIMATELY_LOCATION",
"usedScene": {
"abilities": [
"AppletAbility" // 宿主配置的自定义 Ability name
],
"when":"inuse"
}
}
],
# 3. SDK 初始化
我们强烈建议在 EntryAbility
(宿主应用的入口 Ability)中的 onWindowStageCreate
对 SDK 进行初始化,初始化 SDK 需要传入的各项参数如下(sdk 初始化只需要调用一次,应避免重复调用):
# 3.1 小程序框架的配置信息
支持配置多个服务器信息,可以同时打开不同环境中的小程序。配置参数如下:
import { IFinAppConfig } from '@finclip/sdk';
const finStoreConfigs: IFinAppConfig.IStoreConfig[] = [
{
apiServer: '服务器1的地址',
sdkKey: 'SDK Key信息',
sdkSecret: 'SDK Secret信息',
apmServer: '服务器1的数据上报服务器地址',
cryptType: '加密方式'
},
{
apiServer: '服务器2的地址',
sdkKey: 'SDK Key信息',
sdkSecret: 'SDK Secret信息',
apmServer: '服务器2的数据上报服务器地址',
cryptType: '加密方式'
}
]
# 3.2 初始化 SDK
调用初始化接口初始化 SDK:
import { FinAppClient,IFinAppConfig } from '@finclip/finclip-sdk';
const finAppConfig: IFinAppConfig.IFinAppConfig = {
finStoreConfigs
}
const startMode: IFinAppStartMode = {
startMode: EAppletStartMode.Ability,
uiContext: this.getUIContext()
}
const client = FinAppClient.init(
finAppConfig,
context:this.context,
entryInfo:'AppletAbility',
startMode
)
# 3.2.1 以 Ability 启动小程序(推荐)
SDK 会单独拉起一个 Ability 来运行小程序
示例代码:
import { FinAppClient,IFinAppConfig } from '@finclip/finclip-sdk';
const finAppConfig: IFinAppConfig.IFinAppConfig = {
finStoreConfigs
}
const startMode: IFinAppStartMode = {
startMode: EAppletStartMode.Ability,
uiContext: this.getUIContext()
}
const client = FinAppClient.init(
finAppConfig,
context:this.context,
entryInfo:'AppletAbility',
startMode // 如果是以 Ability 启动小程序,该参数可以省略
)
# 3.2.2 以 Navigation 启动小程序(推荐)
最低支持版本 1.1.0
SDK 使用宿主应用的 NavPathStack
来打开小程序,具体功能可以参考官方文档 (opens new window)。以这种方式启动可以跳过 2.1.2 的步骤。
示例代码:
import { FinAppClient,IFinAppConfig } from '@finclip/finclip-sdk';
const finAppConfig: IFinAppConfig.IFinAppConfig = {
finStoreConfigs
}
const startMode: IFinAppStartMode = {
startMode: EAppletStartMode.Navigation,
routerState: new NavPathStack(), // 该参数需要传入宿主应用的 NavPathStack,如果传没有和 Navigation 关联的会打不开小程序
uiContext: this.getUIContext()
}
const client = FinAppClient.init(
finAppConfig,
context:this.context,
entryInfo:'AppletAbility', // 如果是以 Navigation 启动小程序,该参数可以传 ''
startMode
)
完整页面代码:
import common from '@ohos.app.ability.common';
import { EAppletStartMode, FinAppClient, IFinAppConfig, IFinAppStartMode } from '@finclip/sdk';
@Entry
@Component
struct Index {
@State pageInfos: NavPathStack = new NavPathStack()
context = getContext(this) as common.UIAbilityContext
client?: FinAppClient
@State appId: string = ''appId
@State apiServer: string = 'apiServer'
initFinAppClient() {
const finAppConfig: IFinAppConfig.IFinAppConfig = {
finStoreConfigs: [{
apiServer: 'apiServer',
sdkKey: 'sdkKey',
sdkSecret: 'sdkSecret',
apmServer: 'apmServer'
}]
}
const startMode: IFinAppStartMode = {
startMode: EAppletStartMode.Navigation,
routerState: this.pageInfos,
uiContext: this.getUIContext()
}
this.client = FinAppClient.init(
finAppConfig,
this.context,
'',
startMode
)
}
async startApplet(appid: string, apiServer: string) {
await this.client?.startApplet({
appId: appid,
apiServer: apiServer,
})
}
@Builder
PageMap(name: string) {
// 宿主应用路由...
}
build() {
Navigation(this.pageInfos) {
Button('初始化小程序').onClick(() => {
this.initFinAppClient()
})
Button('打开小程序').onClick(() => {
this.startApplet(this.appId, this.apiServer)
})
}
.mode(NavigationMode.Stack)
.id('root')
.title('起始页')
.navDestination(this.PageMap)
}
}
# 3.2.3 以 Router 启动小程序(不推荐)
最低支持版本 1.1.0
SDK 以 Page
的形式来打开小程序。因为是基于鸿蒙的 router 路由来实现的,功能会有一定的限制,且鸿蒙官方也不推荐这种方式,可以参考官方文档 (opens new window) ,以这种方式启动可以跳过 2.1.2 的步骤。
示例代码:
import { FinAppClient,IFinAppConfig } from '@finclip/finclip-sdk';
const finAppConfig: IFinAppConfig.IFinAppConfig = {
finStoreConfigs
}
const startMode: IFinAppStartMode = {
startMode: EAppletStartMode.Router,
uiContext: this.getUIContext()
}
const client = FinAppClient.init(
finAppConfig,
context:this.context,
entryInfo:'AppletAbility', // 如果是以 Router 启动小程序,该参数可以传 ''
startMode
)
# 3.2.4 Navigation 和 Router 启动方式的区别
- 路由具体区别可以参考官方文档 (opens new window)
- Router 启动方式在小程序打开小程序时表现可能不符合预期
- 小程序转 APP 场景不支持 Router 方式启动
# 3.2.5 注意事项
- 启动方式只能在初始化设置,且不允许重复调用初始化方法来更新,如果修改可能会出现未知问题
- 由于 Navigation 和 Router 的方式是运行在宿主应用的 window 上,建议设置全屏布局获得更好的体验,参考官方文档 (opens new window)
# 4. SDK 使用示例
# 4.1 启动小程序
在平台中上架小程序之后,我们就可以通过调用 SDK 中启动小程序的接口来打开小程序了。启动小程序的代码如下:
client.startApplet({
appId: '小程序的 appId',
apiServer: '服务器的地址'
})
如果启动小程序时需要携带启动参数,则可以调用支持传递启动参数的接口,如下:
client.startApplet({
appId: '小程序的 appId',
apiServer: '服务器的地址',
startParams: {
path:'/pages/index/index',
query: "aaa=test&bbb=123"
}
})
# 5. 地图集成
目前鸿蒙 SDK 地图相关使用的是华为提供的 Map Kit
,当需要使用 openLocation
、chooseLocation
、Map 组件
等的时候,需要集成方按照华为文档 (opens new window)开启地图服务和配置项目后才可正常显示地图。