# 鸿蒙集成

# 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 等
隐私窗口	ohos.permission.PRIVACY_WINDOW	setVisualEffectOnCapture 等

# 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 启动小程序，该参数可以省略
)

最低支持版本 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
)

路由具体区别可以参考官方文档 (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)开启地图服务和配置项目后才可正常显示地图。

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

# 鸿蒙集成

# 1 . 获取凭据

# 2. 导入 SDK

# 2.1 配置 SDK

# 2.1.1 通过 oh-package.json5 依赖

# 2.1.2 在 module.json5 配置

# 关键字段说明

# launchType: "specified" 的具体配置方式

# 2.2 SDK 涉及到的敏感权限

# 2.2.1 必要权限

# 2.2.2 非必要权限

# 2.2.3 权限配置方式

# 3. SDK 初始化

# 3.1 小程序框架的配置信息

# 3.2 初始化 SDK

# 3.2.1 以 Ability 启动小程序（推荐）

# 3.2.2 以 Navigation 启动小程序（推荐）

# 3.2.3 以 Router 启动小程序（不推荐）

# 3.2.4 Navigation 和 Router 启动方式的区别

# 3.2.5 注意事项

# 4. SDK 使用示例

# 4.1 启动小程序

# 5. 地图集成