FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

# 鸿蒙集成

# 1 . 获取凭据

集成 SDK 需要先在 FinClip 平台中创建应用绑定小程序,获得每个应用专属的 SDK KEYSDK SECRET 后,随后就可以在集成 SDK 时填写对应的参数。打开小程序时 SDK 会自动初始化,并校验 SDK KEYSDK SECRETBundleID(Application ID) 是否正确。 您可以 【点击这里】 查看如何获取所需要的 SDK KEYSDK 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 依赖

  1. 在项目根目录创建 .ohpmrc 文件,添加以下内容
registry=https://ohpm.openharmony.cn/ohpm/
@finclip:registry=https://ohpm.finogeeks.com/repos/ohpm
  1. 在项目的 oh-package.json5dependencies 字段添加依赖
"@finclip/sdk": "latest"
  1. 执行 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" 的具体配置方式

  1. module.json5module.srcEntry 配置 ./ets/myabilitystage/MyAbilityStage.ts,文件名和文件位置可自定义,后续说明以这个路径为例子
  2. 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 注意事项

  1. 启动方式只能在初始化设置,且不允许重复调用初始化方法来更新,如果修改可能会出现未知问题
  2. 由于 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,当需要使用 openLocationchooseLocationMap 组件 等的时候,需要集成方按照华为文档 (opens new window)开启地图服务和配置项目后才可正常显示地图。

© FinClip with ❤ , Since 2017