# 桌面端集成
集成样例代码
可以在这里获取集成样例代码https://github.com/finogeeks/finclip-desktop-demo (opens new window)
若您所在的环境无法访问 Github,也可以点击这里访问 gitee (opens new window) 的镜像仓库。
# 1. 获取凭据
请注意
集成 SDK 需要先在 FinClip 平台中创建应用并绑定小程序,获得每个应用专属的SDK KEY
及SDK SECRET
后,随后就可以在集成 SDK 时填写对应的参数。打开小程序时 SDK 会自动初始化,并校验SDK KEY
,SDK SECRET
与BundleID(Application ID)
是否正确。
您可以 【点击这里】 查看如何获取所需要的SDK KEY
及SDK SECRET
。请务必确认集成 SDK 时填写的参数正确,否则会导致小程序无法打开。
# 2. 获取与导入 SDK
桌面版 SDK 目录结构如下:
Finclip.zip
│ FinclipWrapper.(dll | so | dylib) # 动态链接库
│ finclip_api.h # 公共接口头文件
│ finclip_const.h # 常量定义文件
└───finclip/ # 主程序
# 2.1 导入 SDK
# 2.1.1 加载动态链接库
FinClip SDK 提供了头文件和动态链接库.
如果您使用 C/C++ 开发, 请直接使用我们提供的文件.
如果您使用的语言不能直接使用头文件编译, 请使用 LoadLibrary / dlopen 的方式读取动态链接库
# 以cmake为例, 在CMakeLists.txt加入以下两行
target_include_directories(TARGET PRIVATE ${path/to/include})
target_link_libraries(TARGET PRIVATE FinClipSDKWrapper)
[DllImport("FinClipSDKWrapper.dll", SetLastError = true)]
var
adll: Thandle;
begin
adll := LoadLibrary('path\to\FinClipSDKWrapper.dll');
...
end.
from ctypes import *
cdll.LoadLibrary("C:/Users/gyt/code/finclipsdk-desktop/build/wrapper/Debug/FinClipSDKWrapper.dll")
libc = CDLL("FinClipSDKWrapper.dll")
# 2.1.2 读取动态链接库中的函数
FinClip SDK Wrapper 是纯C符号的动态链接库.
C/C++ 使用过我们提供的头文件编译链接即可.
非 C/C++ 语言要使用 FinClip SDK 提供的 API , 通常有以下步骤:
- 打开 finclip_api.h 文件找到要使用 API 的符号名
- 根据函数声明, 定义目标语言的函数
下面以 finclip_start_applet_params
为例
它的函数签名为:
int FINSTDMETHODCALLTYPE finclip_start_applet_params(const char* appstore, const char* appid, void* params);
// 直接include头文件即可
#include "finclip_api.h"
finclip_start_applet_params(appstore, appid, params)
[DllImport("FinClipSDKWrapper.dll", SetLastError = true)]
public static extern Int32 finclip_start_applet_params([MarshalAs(UnmanagedType.LPUTF8Str)] string app_store, [MarshalAs(UnmanagedType.LPUTF8Str)] string appid, IntPtr start_params);
type
finclip_start_applet_params_type = function(appstore: PANSIChar;appid: PANSIChar;p: Pointer): Pointer; Cdel;
var
adll: Thandle;
finclip_start_applet_params: finclip_start_applet_params_type;
begin
adll := LoadLibrary('path\to\FinClipSDKWrapper.dll');
@finclip_start_applet_params := GetProcAddress(adll, 'finclip_start_applet_params');
end.
# 3. SDK 初始化
加载好动态链接库后, 接下来的示例均使用 C 语言展示, 根据上面的提示转换为您所使用的语言即可. 也可以 【点击这里】 (opens new window) 查看对应语言的完整demo.
# 3.1 配置 SDK
FinclipParams *config = finclip_create_params();
finclip_params_set(config, FINCLIP_CONFIG_APPKEY, appkey);
finclip_params_set(config, FINCLIP_CONFIG_SECRET, secret);
finclip_params_set(config, FINCLIP_CONFIG_DOMAIN, domain);
finclip_params_set(config, FINCLIP_CONFIG_EXE_PATH, exe_path, callback);
finclip_init_with_config(appstore, config);
appstore
appstore是服务器配置的唯一标识
可以创建多个服务器配置,搭配不同的appstore值使用
# 4. 小程序管理
# 4.1 打开小程序
配置完成后, 即可启动小程序
finclip_start_applet(app_store, appid); // 使用app_store中的配置打开对应环境的小程序
# 4.2 关闭小程序
您可以关闭指定小程序, 也可以关闭所有小程序
finclip_close_applet(appid); // 关闭指定小程序
finclip_close_all_applet(); // 关闭所有小程序
# 4.3 注册自定义api
您可以注册自定义api, 供小程序和 h5 直接使用
在小程序的FinClipConf.js
里定义api名称
module.exports = {
extApi:[
{
name: 'test', //扩展api名
sync: false, //是否为同步api
params: { //扩展api 的参数格式
}
}
]
}
实现自定义api
// 定义自定义API
void WebApiExample(const char* event, const char* param, void* input,
int callbackid) {
FinClipParams* res = finclip_create_params();
finclip_params_set(res, "result", "ok");
finclip_callback_success(appid, callbackid, res);
finclip_destory_params(res);
}
void AppApiExample(const char* event, const char* param, void* input,
int callbackid) {
FinClipParams* res = finclip_create_params();
finclip_params_set(res, "result", "ok");
finclip_callback_success(appid, callbackid, res);
finclip_destory_params(res);
}
// 注册自定义API
finclip_register_api(kWebView, "test", WebApiExample, this);
finclip_register_api(kApplet, "test", AppApiExample, this);
在小程序里调用自定义api
// 异步api
wx.test({ success: console.log, error: console.error })
// 同步api
const result = wx.test()
# 4.4 监听小程序的生命周期事件
现在小程序定义了5个生命周期事件, 您可以根据需要监听对应的事件
// 支持的回调类型
enum LifecycleType {
kLifecycleStarted = 1, // 小程序启动
kLifecycleClosed = 2, // 小程序关闭
kLifecycleHide = 3, // 小程序窗口隐藏
kLifecycleShow = 4, // 小程序窗口显示
kLifecycleDomReady = 5, // 小程序首屏渲染完毕
};
// 定义自定义API处理函数
void LifecycleHandle(LifecycleType type, const char* appid, void* input) {
// 注意,这里需要处理线程问题,如:
// 1. 全局变量加锁
// 2. 如果此handler需要处理ui界面,根据ui框架可能需要指派dispath到ui线程
// ...
}
// 注册自定义API
finclip_register_lifecycle(appid, kLifecycleClosed, LifecycleHandle, window)
# 5. 嵌入模式
目前嵌入模式仅支持 Windows , Mac 和 Linux 正在开发中.
# 5.1 嵌入窗口
如果要将小程序嵌入到您的窗口中, 首先需要获取窗口句柄, 记为 hwnd 我们提供了两个api完成窗口的嵌入.
finclip_start_applet_embed(appstore, appid, params, hwnd); // 启动小程序时嵌入到指定窗口
finclip_embed_applet(appid, hwnd); // 将已启动的小程序嵌入到指定窗口
# 5.2 处理缩放事件
当您的窗口发生变化时, 您需要监听窗口变化事件, 将高和宽通知小程序进程
finclip_set_position(appid, 0, 0, width, height); // left和top暂不支持
# 5.3 关闭处理
退出分两种情况:
- 宿主窗口先关闭, 此时需要调用该finclip_close_applet通知FinClip进程退出, 或者使用其他方式杀掉进程
- FinClip进程先关闭, 此时需要接受FinClip发过来的消息
// 场景一, 宿主窗口先关闭, 您需要在窗口关闭事件中通知小程序退出
finclip_close_applet(appid); // 通知小程序关闭
// 场景二, 小程序先关闭, 您需要在小程序关闭的生命周期事件中关闭宿主窗口
void LifecycleHandle(LifecycleType type, const char* appid, void* input) {
if (type == kLifecycleClosed) {
window.close();
}
}