# 鸿蒙集成

# 1 . 获取凭据

集成 SDK 需要先在 FinClip 平台中创建应用并绑定小程序，获得每个应用专属的 SDK KEY 及 SDK SECRET 后，随后就可以在集成 SDK 时填写对应的参数。打开小程序时 SDK 会自动初始化，并校验 SDK KEY，SDK SECRET 与 BundleID(Application ID) 是否正确。您可以【点击这里】 (opens new window) 查看如何获取所需要的 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，所以需要宿主 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	saveImageToPhotosAlbum 等
传感器	ohos.permission.ACCELEROMETER、ohos.permission.GYROSCOPE	enableAccelerometer、enableDeviceMotion、enableGyroscope、enableCompass 等
联系人	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/sdk';

const finAppConfig: IFinAppConfig.IFinAppConfig = {  
  finStoreConfigs
}

const client = FinAppClient.init(  
  finAppConfig,  
  context:this.context,  
  entryInfo:'AppletAbility',  
)

# 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小程序指引