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

# 鸿蒙集成

# 1 . 获取凭据

集成 SDK 需要先在 FinClip 平台中创建应用绑定小程序,获得每个应用专属的 SDK KEYSDK SECRET 后,随后就可以在集成 SDK 时填写对应的参数。打开小程序时 SDK 会自动初始化,并校验 SDK KEYSDK SECRETBundleID(Application ID) 是否正确。 您可以 【点击这里】 (opens new window) 查看如何获取所需要的 SDK KEYSDK SECRET。请务必确认集成 SDK 时填写的参数正确,否则会导致小程序无法打开。

# 2. 导入 SDK

请注意

注意:DevEco Studio 至少需要升级到 5.0.3.300,鸿蒙系统版本至少升级到 3.0.0.22

# 2.1 配置 SDK

# 2.1.1 通过 oh-package.json5 依赖

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

"@finclip/finclip-sdk": "file:../FinClipSDk.tgz"

sdk 在 【点击这里】 (opens new window) 下载

然后注意在鸿蒙工程根目录下的 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" 的具体配置方式

  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 拿到启动时的部份数据,建议使用 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)

© FinClip with ❤ , Since 2017