1. 扫码启动小程序

int finclip_start_applet_qrcode(const char *appstore, const char *qrcode, const char *qruserid);

扫码启动包括：临时版、体验版、审核版、线上版

1.1 参数

appstore

        服务器配置的appstore

qrcode

        二维码链接

qruserid

        体验用户(体验版二维码传体验用户，其他二维码传"")

1.2 临时版二维码使用

点击"预览"，ide会生成临时版二维码，点击"复制二维码内容"得到二维码链接参数：qrcode

1.3 体验版二维码使用

点击"配置体验成员"，得到体验用户参数：qruserid，点击"体验版二维码"图标，在弹出对话框中点击"复制二维码内容"得到二维码链接参数：qrcode

1.4 审核版二维码使用

点击"新增"创建一个新的审核版，得到二维码链接

1.5 线上版二维码使用

点击"线上版二维码"图标，在弹出对话框中点击"复制二维码内容"得到二维码链接参数：qrcode

2. 启动小程序

int finclip_start_applet(const char *appstore, const char *appid);
int finclip_start_applet_params(const char *appstore, const char *appid, FinclipParams *params);
int finclip_start_applet_embed(const char *appstore, const char *appid, FinclipParams *params, HWND container);

根据appstore指定对应的全局配置, 您也可以增加ui参数

2.1 参数

appstore

        服务器配置的appstore

appid

        小程序对应的appid

params

        使用finclip_create_params创建的参数

container

        嵌入的目标窗口句柄 (仅windows支持)

2.2 可选参数

属性	类型	参数值	说明
show_loading	string	(默认值) 展示: 1 不展示: 0	是否展示loading动画
title_bar_back_button	string	(默认值) 隐藏: hidden 显示: normal	是否展示返回按钮
title_bar_close_button	string	(默认值) 显示: normal 隐藏: hidden	是否展示关闭按钮
title_bar_minimize_button	string	(默认值) 显示: normal 隐藏: hidden	是否展示最小化按钮
title_bar_maximize_button	string	(默认值) 显示: normal 隐藏: hidden	是否展示最大化按钮
title_bar_more_button	string	(默认值) 显示: normal 隐藏: hidden	是否展示更多按钮
title_bar.style	string	(默认值) 完整显示: default 自定义导航栏，只保留右上角胶囊按钮。: custom 隐藏。: hide	顶栏样式
title_bar.height	string		顶栏高度，默认值44
title_bar.back.url	string		顶栏返回按钮图片
title_bar.home.url	string		顶栏首页按钮图片
title_bar.home.width	string		返回首页按钮的宽度
title_bar.home.height	string		返回首页按钮的高度
title_bar.home.left_margin	string		返回首页按钮的左边距，默认值为10
title_bar.home.corner_radius	string		返回首页按钮的圆角半径，默认值为5
title_bar.home.dark_image	string		返回首页按钮的图片对象，如果不传，会使用默认图标（暗黑模式）
title_bar.home.light_image	string		返回首页按钮的图片对象，如果不传，会使用默认图标（明亮模式）
title_bar.home.border_light_color	string		返回首页按钮的边框浅色颜色（明亮模式）
title_bar.home.border_dark_color	string		返回首页按钮的边框浅色颜色（暗黑模式）
title_bar.home.bg_light_color	string		返回首页按钮的背景浅色颜色（明亮模式）
title_bar.home.bg_dark_color	string		返回首页按钮的背景浅色颜色（暗黑模式）
title_bar.font.families	string		顶栏标题文字
title_bar.font.height	string		顶栏标题文字大小
title_bar.font.align	string		顶栏标题文字对其
more_menu.forward.visiable	string	(默认值) 显示: normal 隐藏: hidden	更多菜单是否展示转发按钮
more_menu.setting.visiable	string	(默认值) 显示: normal 隐藏: hidden	更多菜单是否展示设置按钮
more_menu.feedback.visiable	string	(默认值) 显示: normal 隐藏: hidden	更多菜单是否展示回到反馈按钮
more_menu.refresh.visiable	string	(默认值) 显示: normal 隐藏: hidden	更多菜单是否展示新进入按钮
more_menu.maximize.visiable	string	(默认值) 显示: normal 隐藏: hidden	更多菜单是否展示最大化按钮
more_menu.minimize.visiable	string	(默认值) 显示: normal 隐藏: hidden	更多菜单是否展示最小化按钮
capsule.width	string		右上角胶囊视图的宽度，默认值为176
capsule.height	string		右上角胶囊视图的高度，默认值为32
capsule.right_margin	string		右上角胶囊视图的右边距，默认值为10
capsule.radius	string		右上角胶囊视图的圆角半径，默认值为4
capsule.border.width	string		右上角胶囊视图的边框宽度，默认值为1
capsule.border.light_color	string		右上角胶囊视图的边框浅色颜色
capsule.border.dark_color	string		右上角胶囊视图的边框深色颜色
capsule.background.light_color	string		右上角胶囊视图的背景浅色颜色
capsule.background.dark_color	string		右上角胶囊视图的背景深色颜色
capsule.more.light_image	string		胶囊里的浅色更多按钮的图片路径
capsule.more.dark_image	string		胶囊里的深色更多按钮的图片路径
capsule.more.width	string		胶囊里的更多按钮的宽度，高度与宽度相等
capsule.more.left_margin	string		胶囊里的更多按钮的左边距
capsule.close.light_image	string		胶囊里的浅色关闭按钮的图片路径
capsule.close.dark_image	string		胶囊里的深色色关闭按钮的图片路径
capsule.close.width	string		胶囊里的关闭按钮的宽度，高度与宽度相等
capsule.close.left_margin	string		胶囊里的关闭按钮的左边距
capsule.minimize.light_image	string		胶囊里的浅色最小化按钮的图片路径
capsule.minimize.dark_image	string		胶囊里的深色色最小化按钮的图片路径
capsule.maximize.light_image	string		胶囊里的浅色最大化按钮的图片路径
capsule.maximize.dark_image	string		胶囊里的深色色最大化按钮的图片路径
capsule.normalize.light_image	string		胶囊里的浅色还原按钮的图片路径
capsule.normalize.dark_image	string		胶囊里的深色色还原按钮的图片路径
capsule.hide_before_open	string		打开动画时，隐藏关闭胶囊
route_loading_timeout	string		路由事件超时显示Loading UI，0表示不会显示。单位毫秒，默认0
window_left	string		初始窗口左边位置
window_top	string		初始窗口顶部位置
window_height	string		初始窗口高度
window_width	string		初始窗口宽度
window_scale_factor	string		初始缩放倍率，默认1，合法值介于1-5
window_min_height	string		最小窗口高度
window_min_width	string		最小窗口宽度
title_bar.back_button.url	string	(默认值) 显示: normal 隐藏: hidden	顶栏返回按钮图片
page_path	string		小程序首屏路径
start_params	string		传给小程序的启动参数
proxy_methods	string	h5注入cookie: proxy_h5_cookie	注册的代理方法，在启动后不可新增
host.window.hwnd	string		宿主的顶层窗口句柄, 仅windows有效
webview.user_agent	string		h5自定义USER AGENT
authorize_reject_button_radius_light	string		权限弹框拒绝按钮圆角半径（浅色模式）
authorize_reject_button_background_light	string		权限弹框拒绝按钮背景色（浅色模式）
authorize_reject_button_background_pressed_light	string		权限弹框拒绝按钮按下背景色（浅色模式）
authorize_reject_button_background_hover_light	string		权限弹框拒绝按钮悬停背景色（浅色模式）
authorize_reject_button_border_light	string		权限弹框拒绝按钮边框色（浅色模式）
authorize_reject_button_border_pressed_light	string		权限弹框拒绝按钮按下边框色（浅色模式）
authorize_reject_button_text_light	string		权限弹框拒绝按钮文字颜色（浅色模式）
authorize_reject_button_text_pressed_light	string		权限弹框拒绝按钮按下文字颜色（浅色模式）
authorize_allow_button_radius_light	string		权限弹框允许按钮圆角半径（浅色模式）
authorize_allow_button_background_light	string		权限弹框允许按钮背景色（浅色模式）
authorize_allow_button_background_pressed_light	string		权限弹框允许按钮按下背景色（浅色模式）
authorize_allow_button_background_hover_light	string		权限弹框允许按钮悬停背景色（浅色模式）
authorize_allow_button_border_light	string		权限弹框允许按钮边框色（浅色模式）
authorize_allow_button_border_pressed_light	string		权限弹框允许按钮按下边框色（浅色模式）
authorize_allow_button_text_light	string		权限弹框允许按钮文字色（浅色模式）
authorize_allow_button_text_pressed_light	string		权限弹框允许按钮按下文字色（浅色模式）
authorize_applet_name_size	string		权限弹框小程序名称字号
authorize_applet_name_color_light	string		权限弹框小程序名称颜色（浅色模式）
authorize_title_size	string		权限弹框标题字号
authorize_title_color_light	string		权限弹框标题文字颜色（浅色模式）
authorize_description_size	string		权限弹框描述字号
authorize_description_color_light	string		权限弹框描述文字颜色（浅色模式）
authorize_agreement_title_size	string		权限弹框协议标题字号
authorize_agreement_title_color_light	string		权限弹框协议标题文字颜色（浅色模式）
authorize_agreement_description_size	string		权限弹框协议描述字号
authorize_agreement_description_color_light	string		权限弹框协议描述文字颜色（浅色模式）
authorize_agreement_link_color_light	string		权限弹框协议链接文字颜色（浅色模式）
authorize_agreement_icon_light	string		权限弹框协议图标（浅色模式）
custom_about_page	string		自定义关于页面地址
preload_process_number	string	(默认值): 1	是否开启预加载 允许的取值, 0 或 1
enable_sandbox	string		是否开启sandbox 参考:
workers	string		[object Object]
qr_code	string		二维码链接
qr_user_id	string		二维码体验版用户id
qr_type	string		二维码类型

2.3 返回值

1. 0 成功
2. <0 失败

3. 关闭所有小程序

int finclip_close_all_applet();

3.1 返回值

1. 0 成功
2. <0 失败

4. 关闭指定小程序

int finclip_close_applet(const char *appid);

4.1 参数

appid

        小程序id

4.2 返回值

1. 0 成功
2. <0 失败

5. 异步关闭指定小程序

int finclip_close_applet_async(const char *appid, void(*callback)(const char *appid, void *input, int err), void *input);

5.1 参数

appid

        小程序id

callback

        回调函数

input

        自定义参数, 透传给回调函数

5.2 返回值

1. 0 成功
2. <0 失败

6. 隐藏指定小程序

int finclip_hide_applet(const char *appid);

6.1 参数

appid

        小程序id

6.2 返回值

1. 0 成功
2. <0 失败

7. 显示指定小程序

int finclip_show_applet(const char *appid);

7.1 参数

appid

        小程序id

7.2 返回值

1. 0 成功
2. <0 失败

8. 注册小程序状态事件回调

int finclip_register_lifecycle(const char *appid, LifecycleType lifecycle, void(*handle)(enum LifecycleType type, const char *appid, void *input), void *input);

如果同时注册了 ALL 和具体的回调类型, 会触发回调2次

为了内存的安全性, 已注册的 lifecycle 在小程序退出时会被清理

在下次启动时需视情况重新注册 lifecycle

同一类型的回调注册多次, 只有最后一次生效

8.1 参数

appid

        小程序id

lifecycle

        需要监听的事件

handle

        回调函数

input

        透传给回调函数

8.2 生命周期类型

名称	值	说明
kLifecycleAll	0	所有事件
kLifecycleStarted	1	小程序启动
kLifecycleClosed	2	小程序关闭
kLifecycleHide	3	小程序窗口隐藏
kLifecycleShow	4	小程序窗口显示
kLifecycleDomReady	5	小程序首屏渲染完毕
kLifecycleCrashed	6	小程序崩溃
kLifecycleError	7	小程序启动错误

8.3 返回值

1. 0 成功
2. <0 失败

9. 设置小程序窗口位置

int finclip_set_position(const char *appid, int left, int top, int width, int height);

9.1 参数

appid

        小程序appid

left

        left

top

        top

width

        width

height

        height

9.2 返回值

1. 0 成功
2. <0 失败

10. 注册自定义api

int finclip_register_api(FinClipApiType type, const char *apis, void(*handle)(const char *event, const char *param, void *input, int callbackid), void *input);

供小程序或h5调用

自定api对所有小程序都生效

重复注册api会覆盖

小程序启动后才注册的api将不会生效

10.1 参数

type

        自定义api类型

apis

        api名称, 以,分割的字符串

handle

        处理函数

input

        自定义参数, 透传给handle

10.2 自定义api类型

名称	值	说明
kApplet	0	供小程序调用的api
kWebView	1	供h5调用的api

10.3 返回值

1. 0 成功
2. <0 失败

11. 设置自定义api或代理方法的返回值

int finclip_callback_res(int callback_id, void *result);

小程序和宿主的api或代理方法调用是异步, 通过此函数将返回值传回

此api只为做兼容性处理，请使用finclip_callback_success替代

12. 设置自定义api或代理方法的成功返回值

int finclip_callback_success(int callback_id, void *result);

小程序和宿主的api或代理方法调用是异步, 通过此函数将返回值传回

12.1 参数

callback_id

        回调id

result

        调用finclip_create_params获取的参数对象

type

        区分callback类型是自定义api或代理方法

12.2 返回值

1. 0 成功
2. <0 失败

13. 设置自定义api或代理方法的失败返回值

int finclip_callback_failure(int callback_id, void *result);

小程序和宿主的api或代理方法调用是异步, 通过此函数将返回值传回

13.1 参数

callback_id

        回调id

result

        调用finclip_create_params获取的参数对象

type

        区分callback类型是自定义api或代理方法

13.2 返回值

1. 0 成功
2. <0 失败

14. 设置指定appstore的参数配置

int finclip_init_with_config(const char *appstore, const FinclipParams *config);

appstore表示一套配置, 多次调用会覆盖之前的参数, 但domain, appkey, secret不允许被覆盖, 请检查函数的返回值. 如果需要使用不同的domain, appkey, secret, 请使用不同的appstore

14.1 参数

appstore

        服务器对象的key

json_str

        json字符串

config

        FinclipParams对象

14.2 可选参数

属性	类型	参数值	说明
appstore	string		这组参数的唯一标识
appkey	string		从凡泰小程序开放平台获取的appkey
secret	string		从凡泰小程序开放平台获取的secret
domain	string		服务器地址
exe_path	string		可执行文件位置
cef_path	string		浏览器内核地址
current_user_id	string		用户表示, 用于分离不同用户的userdata
net_proxy	string	（默认值）无代理: NoProxy 默认代理: DefaultProxy SOCKS5代理: Socks5Proxy HTTP代理: HttpProxy	网络代理类型
net_proxy_settings	string	"testing.com", "port": 1080, "user": "admin", "password": "admin"} 参数示例，仅SOCK5代理和HTTP代理需要设置: {"host_name"	网络代理设置

14.3 返回值

1. 0 成功
2. <0 失败

15. 创建参数容器

FinclipParams *finclip_create_params(void);

FinclipParams是一个json对象的简单封装

目的为了方便各种语言有统一的参数容器

使用完毕后, 请调用finclip_destory_params销毁 FinclipParams

16. 从json字符串创建启动参数

FinclipParams *finclip_build_params(const char *json_str);

FinclipParams是一个json对象的简单封装

目的为了方便各种语言有统一的参数容器

使用完毕后, 请调用finclip_destory_params销毁 FinclipParams

16.1 参数

json_str

        json格式的启动参数

17. 销毁启动参数

int finclip_destory_params(FinclipParams *params);

方便不同语言统一使用 对nlohmann/json做的封装

17.1 参数

params

        调用finclip_create_params获取的参数对象

17.2 返回值

1. 0 成功
2. <0 失败

18. 设置参数

int finclip_params_set(FinclipParams *params, const char *key, const char *value);

设置一个配置项, 具体配置项参见相应的api

18.1 参数

params

        调用finclip_create_params获取的参数对象

key

        配置项的key

value

        配置项的value

18.2 返回值

1. 0 成功
2. <0 失败

19. 删除指定参数

int finclip_params_del(FinclipParams *params, const char *key);

19.1 参数

params

        调用finclip_create_params获取的参数对象

key

        需要删除的配置项

19.2 返回值

1. 0 成功
2. <0 失败

20. 调用自定义api

int finclip_invoke_api(FinClipApiType type, const char *app_id, const char *api_name, const char *params, void(*callback)(const char *res, void *input), void *input);

调用h5中的自定义api, 小程序不支持自定义api

20.1 参数

type

        调用finclip_create_params获取的参数对象

app_id

        小程序id

api_name

        自定义api名称

params

        参数, json字符串

callback

        回调函数

input

        自定义参数, 透传给回调函数

20.2 返回值

1. 0 成功
2. <0 失败

21. 并发启动间隔 单位毫秒(ms)

int finclip_set_start_interval(int interval);

开启后, finclip_start_applet等启动小程序的api将会控制并发

注意: finclip_start_applet会阻塞线程, 开启后请勿在ui线程中启动

22. 小程序是否打开

bool finclip_is_applet_open(const char *app_id);

22.1 参数

app_id

        小程序id

22.2 返回值

1. true 已打开
2. false 未打开

23. 注册系统协议

int finclip_register_protocol(const char *protocol, const char *exe);

仅支持windows, 供调试用. 注册后可以使用自定义协议打开程序

23.1 参数

protocol

        协议名

exe

        可执行程序位置

23.2 返回值

1. 0 成功
2. <0 失败

24. 注册右上角更多菜单回调

int finclip_register_more_btn_handler(const char *appid, const char *menu_id, const char *title, const char *icon, FinClipMoreMenuBtnType type, void(*handle)(const char *appid, const char *id, const char *params, void *input), void *input);

24.1 参数

appid

        小程序对应的appid

menu_id

        菜单id，如果是右上角的更多按钮，填nullptr

title

        菜单item标题，如果是右上角的更多按钮，填nullptr

icon

        菜单item图标路径，如果是右上角的更多按钮，填nullptr

type

        按钮类型，如果是右上角的更多按钮，填kMoreBtnCommon

handle

        回调handler

input

        透传给回调函数

24.2 返回值

1. 0 成功
2. <0 失败

25. 原生给小程序发送消息

int finclip_send_custom_event(const char *app_id, const char *params);

25.1 参数

app_id

        小程序id

params

        事件参数

25.2 返回值

1. 0 成功
2. <0 失败

26. 触发标题栏返回按钮

int finclip_invoke_back(const char *appid, void(*handle)(const char *appid, const char *params, void *input), void *input);

26.1 参数

appid

        小程序id

handle

        回调函数

input

        透传的参数

26.2 返回值

1. 0 成功
2. <0 失败

27. 注册代理方法

int finclip_register_proxy(const char *proxy, void(*handle)(const char *appid, const char *res, void *input, int callback_id, const char *params), void *input);

27.1 参数

appid

        小程序appid

proxy

        代理方法名称

handle

        回调函数

input

        透传的参数

27.2 返回值

1. 0 成功
2. <0 失败

28. 获取小程序数据文件夹地址所需要的内存大小

int finclip_applet_path_size(const char *appid);

29. 获取小程序数据文件夹地址

int finclip_applet_path(const char *str, char *data);

注意, 小程序关闭后将api将失效

使用方法:

首先使用 finclip_applet_path_size 获取所需要的内存大小

分配好内存后, 再使用 finclip_applet_path 获取字符串

用途1: 将 finfile:// 开头的文件路径转为绝对路径

将 finfile:// 替换为返回值, 并拼接文件路径分隔符

用途2: 获取临时文件夹路径, 在返回值的基础上拼接上 /tmp

30. 使用离线包打开小程序

由于首次打开小程序时，要下载小程序包和基础库包，所以首次启动较慢。针对这种情况，我们可以将小程序包、基础库包下载好放置再工程中打包；也可以在打开app后，合适的时机下载好小程序和基础库包。

30.1 导出离线包到本地文件夹

点击"导出离线包"，在弹出对话框中下载：小程序离线包和基础库离线包到本地文件夹如： 小程序离线包位置：/desktop/offline/applet.zip 基础库离线包位置：/desktop/offline/framework.zip

30.2 通过代理方法注册离线包位置

注册小程序代理方法：offline_applet，在回调函数中设置小程序离线包位置：

@CFUNCTYPE(None, c_char_p, c_char_p, py_object, c_int)
   def offline_applet_proxy_callback(appid, res, input, callback_id):
       print("offline_applet_proxy_callback", appid, callback_id)
       result = libc.finclip_create_params()
       libc.finclip_params_set(result, b"path", b"/desktop/offline/applet.zip")
       libc.finclip_callback_success(callback_id, result)
       libc.finclip_destory_params(result) 

   def offline_applet_proxy():
       libc.finclip_register_proxy(b"offline_applet", offline_applet_proxy_callback, "")  

注册基础库代理方法：offline_basic，在回调函数中设置基础库离线包位置：

@CFUNCTYPE(None, c_char_p, c_char_p, py_object, c_int)
   def offline_basic_proxy_callback(appid, res, input, callback_id):
       print("offline_basic_proxy_callback", appid, callback_id)
       result = libc.finclip_create_params()
       libc.finclip_params_set(result, b"path", b"/desktop/offline/framework.zip")
       libc.finclip_callback_success(callback_id, result)
       libc.finclip_destory_params(result)    

   def offline_basic_proxy():
       libc.finclip_register_proxy(b"offline_basic", offline_basic_proxy_callback, "")