鸿蒙集成

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

2.1 配置 SDK

2.1.1 通过 oh-package.json5 依赖

在项目的 oh-package.json5 的 dependencies 字段添加依赖

"@finclip/finclip-sdk": "0.0.1"

目前 sdk 未正式发布，以上版本号仅供参考集成方式，并不能拉到对应的依赖包

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" 的具体配置方式

1. 在 module.json5 的 module.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 拿到启动时的部份数据，建议使用 apiServer 和 appId 拼接做为小程序唯一标识符
      return `ControlModule_AppletAbilityInstance_${want.parameters.request.apiServer}_${want.parameters.request.appId}`;  
    }  
  
    return '';  
  }  
}

2.2 SDK 涉及到的敏感权限

如果您集成所有的 SDK，那么涉及到的敏感权限包括：存储、摄像头、录音、读取手机状态、位置、蓝牙、通讯录。这些权限，基本都是调用相应的 api 和组件时才会触发。

以下权限及说明基于目前已实现的 api 和组件，当后续 api 和组件完善后所涉及到的权限列表会更新，请以正式发布的文档为准

权限	权限名称
位置	APPROXIMATELY_LOCATION

权限配置方式

在 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/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 client = FinAppClient.init(  
  finAppConfig,  
  context:this.context,  
  entryInfo:'AppletAbility',  
)

3.2.1 单任务栈启动小程序

SDK 也提供单任务栈的形式启动小程序，但由于鸿蒙的部份限制，可能在某些场景会有未知的问题，建议使用上述用 Ability 的初始化方式。

单任务栈：即打开小程序后不会在任务中心看到小程序任务，也无法在任务中心去切换小程序，小程序是运行在宿主应用上的

如果需要采用单任务栈的形式打开小程序可以跳过 2.1.2 的 Ability 注册，然后在初始化的时候传入当前 Ability 的 WindowState，示例代码如下

// entryAbility.ets
import { FinAppClient,IFinAppConfig } from '@finclip/finclip-sdk';

export default class EntryAbility extends UIAbility {  
  onWindowStageCreate(windowStage: window.WindowStage): void {
    const finAppConfig: IFinAppConfig.IFinAppConfig = {  
	  finStoreConfigs
	}
	
	const client = FinAppClient.init(  
	  finAppConfig,  
	  context:this.context,  
	  entryInfo:windowStage,   // entryInfo 需要改成 windowStage
	)
  
    windowStage.loadContent('pages/Index', (err, data) => {  
      if (err.code) {  
        return;  
      }  
    });  
  }  
}

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. 常见错误码

请点击链接查看常见错误码 (opens new window)