桌面端集成

集成样例代码

可以在这里获取集成样例代码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 , 通常有以下步骤:

1. 打开 finclip_api.h 文件找到要使用 API 的符号名
2. 根据函数声明, 定义目标语言的函数

下面以 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 关闭处理

退出分两种情况:

1. 宿主窗口先关闭, 此时需要调用该finclip_close_applet通知FinClip进程退出, 或者使用其他方式杀掉进程
2. FinClip进程先关闭, 此时需要接受FinClip发过来的消息

  // 场景一, 宿主窗口先关闭, 您需要在窗口关闭事件中通知小程序退出
  finclip_close_applet(appid); // 通知小程序关闭

  // 场景二, 小程序先关闭, 您需要在小程序关闭的生命周期事件中关闭宿主窗口
  void LifecycleHandle(LifecycleType type, const char* appid, void* input) {
    if (type == kLifecycleClosed) {
      window.close();
    }
}