1. Launch Mini-Program via QR Code
# 1. Launch Mini-Program via QR Code
int finclip_start_applet_qrcode(const char *appstore, const char *qrcode, const char *qruserid);
# 2. Launch Mini-Program
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);
Based on the appstore to specify the corresponding global configuration, you can also add UI parameters
# 2.1 Parameters
appstore
Server-configured appstore
appid
The appid corresponding to the Mini-Program
params
Parameters created using finclip_create_params
container
Target window handle for embedding (Windows only)
# 2.2 Optional Parameters
| Property | Type | Parameter Value | Description |
|---|---|---|---|
| show_loading | string | (Default) Show: 1 Do not show: 0 | Whether to display loading animation |
| title_bar_back_button | string | (Default) Hide: hidden Show: normal | Whether to display back button |
| title_bar_close_button | string | (Default) Show: normal Hide: hidden | Whether to display close button |
| title_bar_minimize_button | string | (Default) Show: normal Hide: hidden | Whether to display minimize button |
| title_bar_maximize_button | string | (Default) Show: normal Hide: hidden | Whether to display maximize button |
| title_bar_more_button | string | (Default) Show: normal Hide: hidden | Whether to display more button |
| title_bar.style | string | (Default) Fully displayed: default Custom navigation bar, only keep the top-right capsule button.: custom Hidden.: hide | Title bar style |
| title_bar.height | string | Title bar height, default value is 44 | |
| title_bar.back.url | string | Title bar back button image | |
| title_bar.home.url | string | Title bar home button image | |
| title_bar.home.width | string | Home button width | |
| title_bar.home.height | string | Home button height | |
| title_bar.home.left_margin | string | Left margin of the home button, default value is 10 | |
| title_bar.home.corner_radius | string | Corner radius of the home button, default value is 5 | |
| title_bar.home.dark_image | string | Image object for the home button, if not provided, the default icon will be used (Dark Mode) | |
| title_bar.home.light_image | string | Image object for the home button, if not provided, the default icon will be used (Light Mode) | |
| title_bar.home.border_light_color | string | Light border color for the home button (Light Mode) | |
| title_bar.home.border_dark_color | string | Dark border color for the home button (Dark Mode) | |
| title_bar.home.bg_light_color | string | Light background color for the home button (Light Mode) | |
| title_bar.home.bg_dark_color | string | Dark background color for the home button (Dark Mode) | |
| title_bar.font.families | string | Title bar text font families | |
| title_bar.font.height | string | Title bar text size | |
| title_bar.font.align | string | Title bar text alignment | |
| more_menu.forward.visiable | string | (Default) Show: normal Hide: hidden | Whether to display forward button in more menu |
| more_menu.setting.visiable | string | (Default) Show: normal Hide: hidden | Whether to display settings button in more menu |
| more_menu.feedback.visiable | string | (Default) Show: normal Hide: hidden | Whether to display feedback button in more menu |
| more_menu.refresh.visiable | string | (Default) Show: normal Hide: hidden | Whether to display refresh button in more menu |
| more_menu.maximize.visiable | string | (Default) Show: normal Hide: hidden | Whether to display maximize button in more menu |
| more_menu.minimize.visiable | string | (Default) Show: normal Hide: hidden | Whether to display minimize button in more menu |
| more_menu.clear_cache.visiable | string | (Default) Show: normal Hide: hidden | Whether to display clear cache option in more menu |
| capsule.width | string | Width of the top-right capsule view, default value is 176 | |
| capsule.height | string | Height of the top-right capsule view, default value is 32 | |
| capsule.right_margin | string | Right margin of the top-right capsule view, default value is 10 | |
| capsule.radius | string | Corner radius of the top-right capsule view, default value is 4 | |
| capsule.border.width | string | Border width of the top-right capsule view, default value is 1 | |
| capsule.border.light_color | string | Light border color of the top-right capsule view | |
| capsule.border.dark_color | string | Dark border color of the top-right capsule view | |
| capsule.background.light_color | string | Light background color of the top-right capsule view | |
| capsule.background.dark_color | string | Dark background color of the top-right capsule view | |
| capsule.more.light_image | string | Image path for the light more button inside the capsule | |
| capsule.more.dark_image | string | Image path for the dark more button inside the capsule | |
| capsule.more.width | string | Width of the more button inside the capsule, height equals width | |
| capsule.more.left_margin | string | Left margin of the more button inside the capsule | |
| capsule.close.light_image | string | Image path for the light close button inside the capsule | |
| capsule.close.dark_image | string | Image path for the dark close button inside the capsule | |
| capsule.close.width | string | Width of the close button inside the capsule, height equals width | |
| capsule.close.left_margin | string | Left margin of the close button inside the capsule | |
| capsule.minimize.light_image | string | Image path for the light minimize button inside the capsule | |
| capsule.minimize.dark_image | string | Image path for the dark minimize button inside the capsule | |
| capsule.maximize.light_image | string | Image path for the light maximize button inside the capsule | |
| capsule.maximize.dark_image | string | Image path for the dark maximize button inside the capsule | |
| capsule.normalize.light_image | string | Image path for the light restore button inside the capsule | |
| capsule.normalize.dark_image | string | Image path for the dark restore button inside the capsule | |
| capsule.hide_before_open | string | Hide the close capsule during opening animation | |
| route_loading_timeout | string | Timeout for displaying Loading UI during routing events, 0 means it won't be displayed. Unit: milliseconds, default 0 | |
| window_left | string | Initial window left position | |
| window_top | string | Initial window top position | |
| window_height | string | Initial window height | |
| window_width | string | Initial window width | |
| window_scale_factor | string | Initial scaling factor, default 1, valid values between 1-5 | |
| window_min_height | string | Minimum window height | |
| window_min_width | string | Minimum window width | |
| title_bar.back_button.url | string | (Default) Show: normal Hide: hidden | Title bar back button image |
| page_path | string | Initial screen path of the Mini-Program | |
| start_params | string | Startup parameters passed to the Mini-Program | |
| proxy_methods | string | Inject H5 cookies: proxy_h5_cookie | Registered proxy methods, cannot be added after startup |
| host.window.hwnd | string | Host's top-level window handle, Windows only | |
| webview.user_agent | string | Custom USER AGENT for H5 | |
| authorize_reject_button_radius_light | string | Radius of the reject button's corners in the permission popup (Light Mode) | |
| authorize_reject_button_background_light | string | Background color of the reject button in the permission popup (Light Mode) | |
| authorize_reject_button_background_pressed_light | string | Background color of the reject button when pressed in the permission popup (Light Mode) | |
| authorize_reject_button_background_hover_light | string | Background color of the reject button when hovered in the permission popup (Light Mode) | |
| authorize_reject_button_border_light | string | Border color of the reject button in the permission popup (Light Mode) | |
| authorize_reject_button_border_pressed_light | string | Border color of the reject button when pressed in the permission popup (Light Mode) | |
| authorize_reject_button_text_light | string | Text color of the reject button in the permission popup (Light Mode) | |
| authorize_reject_button_text_pressed_light | string | Text color of the reject button when pressed in the permission popup (Light Mode) | |
| authorize_allow_button_radius_light | string | Radius of the allow button's corners in the permission popup (Light Mode) | |
| authorize_allow_button_background_light | string | Background color of the allow button in the permission popup (Light Mode) | |
| authorize_allow_button_background_pressed_light | string | Background color of the allow button when pressed in the permission popup (Light Mode) | |
| authorize_allow_button_background_hover_light | string | Background color of the allow button when hovered in the permission popup (Light Mode) | |
| authorize_allow_button_border_light | string | Border color of the allow button in the permission popup (Light Mode) | |
| authorize_allow_button_border_pressed_light | string | Border color of the allow button when pressed in the permission popup (Light Mode) | |
| authorize_allow_button_text_light | string | Text color of the allow button in the permission popup (Light Mode) | |
| authorize_allow_button_text_pressed_light | string | Text color of the allow button when pressed in the permission popup (Light Mode) | |
| authorize_applet_name_size | string | Font size of the Mini-Program name in the permission popup | |
| authorize_applet_name_color_light | string | Color of the Mini-Program name in the permission popup (Light Mode) | |
| authorize_title_size | string | Font size of the title in the permission popup | |
| authorize_title_color_light | string | Text color of the title in the permission popup (Light Mode) | |
| authorize_description_size | string | Font size of the description in the permission popup | |
| authorize_description_color_light | string | Text color of the description in the permission popup (Light Mode) | |
| authorize_agreement_title_size | string | Font size of the agreement title in the permission popup | |
| authorize_agreement_title_color_light | string | Text color of the agreement title in the permission popup (Light Mode) | |
| authorize_agreement_description_size | string | Font size of the agreement description in the permission popup | |
| authorize_agreement_description_color_light | string | Text color of the agreement description in the permission popup (Light Mode) | |
| authorize_agreement_link_color_light | string | Link text color in the permission popup (Light Mode) | |
| authorize_agreement_icon_light | string | Agreement icon in the permission popup (Light Mode) | |
| custom_about_page | string | Custom about page URL | |
| preload_process_number | string | (Default): 1 | Whether to enable preloading, allowed values: 0 or 1 |
| enable_sandbox | string | Whether to enable sandbox Reference: | |
| workers | string | [object Object] | |
| qr_code | string | QR code link | |
| qr_user_id | string | QR code trial version user ID | |
| qr_type | string | QR code type | |
| language | string | Set language | |
| h5_origin_url | string | H5 application domain |
# 2.3 Return Values
- 0 Success
- <0 Failure
# 3. Close All Mini-Programs
int finclip_close_all_applet();
# 3.1 Return Values
- 0 Success
- <0 Failure
# 4. Close Specified Mini-Program
int finclip_close_applet(const char *appid);
# 4.1 Parameters
appid
Mini-Program ID
# 4.2 Return Values
- 0 Success
- <0 Failure
# 5. Asynchronously Close Specified Mini-Program
int finclip_close_applet_async(const char *appid, void(*callback)(const char *appid, void *input, int err), void *input);
# 5.1 Parameters
appid
Mini-Program ID
callback
Callback function
input
Custom parameter, passed through to the callback function
# 5.2 Return Values
- 0 Success
- <0 Failure
# 6. Hide Specified Mini-Program
int finclip_hide_applet(const char *appid);
# 6.1 Parameters
appid
Mini-Program ID
# 6.2 Return Values
- 0 Success
- <0 Failure
# 7. Show Specified Mini-Program
int finclip_show_applet(const char *appid);
# 7.1 Parameters
appid
Mini-Program ID
# 7.2 Return Values
1. 0 Success
2. <0 Failure
## 8. Register Mini-Program Status Event Callback
```c
int finclip_register_lifecycle(const char *appid, LifecycleType lifecycle, void(*handle)(enum LifecycleType type, const char *appid, void *input), void *input);
If both ALL and specific callback types are registered simultaneously, the callback will be triggered twice
For memory safety, the registered lifecycle will be cleared when the Mini-Program exits
When restarting, the lifecycle needs to be re-registered as appropriate
Multiple registrations of the same type of callback will only take effect for the last registration
# 8.1 Parameters
appid
Mini-Program ID
lifecycle
Event to be listened for
handle
Callback function
input
Pass-through parameter to the callback function
# 8.2 Lifecycle Types
| Name | Value | Description |
|---|---|---|
| kLifecycleAll | 0 | All events |
| kLifecycleStarted | 1 | Mini-Program started |
| kLifecycleClosed | 2 | Mini-Program closed |
| kLifecycleHide | 3 | Mini-Program window hidden |
| kLifecycleShow | 4 | Mini-Program window shown |
| kLifecycleDomReady | 5 | Mini-Program first screen rendering completed |
| kLifecycleCrashed | 6 | Mini-Program crashed |
| kLifecycleError | 7 | Mini-Program startup error |
# 8.3 Return Values
- 0 Success
- <0 Failure
# 9. Set Mini-Program Window Position
int finclip_set_position(const char *appid, int left, int top, int width, int height);
# 9.1 Parameters
appid
Mini-Program appid
left
left
top
top
width
width
height
height
# 9.2 Return Values
- 0 Success
- <0 Failure
# 10. Register Custom API
int finclip_register_api(FinClipApiType type, const char *apis, void(*handle)(const char *event, const char *param, void *input, int callbackid), void *input);
Available for Mini-Programs or H5 to call
Custom APIs are effective for all Mini-Programs
Repeated registration of an API will overwrite the previous one
APIs registered after the Mini-Program starts will not take effect
# 10.1 Parameters
type
Custom API type
apis
API name, a string separated by commas
handle
Handler function
input
Custom parameters, passed through to handle
# 10.2 Custom API Types
| Name | Value | Description |
|---|---|---|
| kApplet | 0 | APIs for Mini-Program calls |
| kWebView | 1 | APIs for H5 calls |
# 10.3 Return Values
- 0 Success
- <0 Failure
# 11. Set Return Value for Custom API or Proxy Method
int finclip_callback_res(int callback_id, void *result);
The API or proxy method calls between the Mini-Program and Host-App are asynchronous, use this function to return the result
This API is only for compatibility purposes, please use finclip_callback_success instead
# 12. Set Successful Return Value for Custom API or Proxy Method
int finclip_callback_success(int callback_id, void *result);
The API or proxy method calls between the Mini-Program and Host-App are asynchronous, use this function to return the result
# 12.1 Parameters
callback_id
Callback ID
result
Parameter object obtained by calling finclip_create_params
type
Distinguish whether the callback type is a custom API or proxy method
# 12.2 Return Values
- 0 Success
- <0 Failure
# 13. Set Failure Return Value for Custom API or Proxy Method
int finclip_callback_failure(int callback_id, void *result);
The API or proxy method calls between the Mini-Program and Host-App are asynchronous, use this function to return the result
# 13.1 Parameters
callback_id
Callback ID
result
Parameter object obtained by calling finclip_create_params
type
Distinguish whether the callback type is a custom API or proxy method
# 13.2 Return Values
- 0 Success
- <0 Failure
# 14. Set Parameter Configuration for Specified App Store
int finclip_init_with_config(const char *appstore, const FinclipParams *config);
appstore represents a set of configurations. Multiple calls will override previous parameters, but domain, appkey, and secret cannot be overridden. Please check the return value of the function. If you need to use different domain, appkey, or secret, please use a different appstore.
### 14.1 Parameters
`appstore`
The key of the server object
`json_str`
JSON string
`config`
FinclipParams object
### 14.2 Optional Parameters
| Property | Type | Parameter Value | Description |
| --- | --- | --- | --- |
| appstore | string | | Unique identifier for this set of parameters <br/> |
| appkey | string | | The appkey obtained from the FinClip Mini-Program Open Platform <br/> |
| secret | string | | The secret obtained from the FinClip Mini-Program Open Platform <br/> |
| domain | string | | Server address <br/> |
| exe_path | string | | Executable file location <br/> |
| cef_path | string | | Browser engine address <br/> |
| current_phone_number | string | | User's phone number, used for unified login interface <br/> |
| current_user_id | string | | User identifier, used to separate userdata for different users <br/> |
| encrypt_user_id | string | Encrypt: 1<br/>(Default) No encryption: 0<br/> | Whether to encrypt user_id, used for backend request interface <br/> |
| net_proxy | string | (Default) No proxy: NoProxy<br/>Default proxy: DefaultProxy<br/>SOCKS5 proxy: Socks5Proxy<br/>HTTP proxy: HttpProxy<br/> | Network proxy type <br/> |
| net_proxy_settings | string | "testing.com", "port": 1080, "user": "admin", "password": "admin"} Example parameter, required only for SOCKS5 and HTTP proxies: {"host_name"<br/> | Network proxy settings <br/> |
### 14.3 Return Values
1. 0 Success
2. <0 Failure
## 15. Create Parameter Container
```c
FinclipParams *finclip_create_params(void);
FinclipParams is a simple encapsulation of a JSON object
The purpose is to provide a unified parameter container for various languages
After use, please call finclip_destory_params to destroy FinclipParams
# 16. Create Startup Parameters from JSON String
FinclipParams *finclip_build_params(const char *json_str);
FinclipParams is a simple encapsulation of a JSON object
The purpose is to provide a unified parameter container for various languages
After use, please call finclip_destory_params to destroy FinclipParams
# 16.1 Parameters
json_str
Startup parameters in JSON format
# 17. Destroy Startup Parameters
int finclip_destory_params(FinclipParams *params);
A wrapper around nlohmann/json for ease of use across different languages
# 17.1 Parameters
params
Parameter object obtained by calling finclip_create_params
# 17.2 Return Values
- 0 Success
- <0 Failure
# 18. Set Parameters
int finclip_params_set(FinclipParams *params, const char *key, const char *value);
Set a configuration item. For specific configuration items, refer to the corresponding API
# 18.1 Parameters
params
Parameter object obtained by calling finclip_create_params
key
Key of the configuration item
value
Value of the configuration item
# 18.2 Return Values
- 0 Success
- <0 Failure
# 19. Delete Specified Parameter
int finclip_params_del(FinclipParams *params, const char *key);
# 19.1 Parameters
params
Parameter object obtained by calling finclip_create_params
key
Configuration item to be deleted
# 19.2 Return Values
- 0 Success
- <0 Failure
# 20. Invoke Custom 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);
Invoke custom APIs in H5. Mini-Programs do not support custom APIs
# 20.1 Parameters
type
Parameter object obtained by calling finclip_create_params
app_id
Mini-Program ID
api_name
Custom API name
params
Parameters, JSON string
callback
Callback function
input
Custom parameter, passed through to the callback function
# 20.2 Return Values
- 0 Success
- <0 Failure
# 21. Concurrent Launch Interval in Milliseconds (ms)
int finclip_set_start_interval(int interval);
When enabled, APIs such as finclip_start_applet that launch Mini-Programs will control concurrency
Note: finclip_start_applet will block the thread. After enabling, do not start it in the UI thread.
# 22. Check if Mini-Program is Open
bool finclip_is_applet_open(const char *app_id);
# 22.1 Parameters
app_id
Mini-Program ID
# 22.2 Return Values
- true Opened
- false Not opened
# 23. Register System Protocol
int finclip_register_protocol(const char *protocol, const char *exe);
Only supported on Windows, for debugging purposes. After registration, the program can be opened using a custom protocol.
# 23.1 Parameters
protocol
Protocol name
exe
Executable file location
# 23.2 Return Value
- 0 Success
- <0 Failure
# 24. Send Messages from Native to Mini-Program
int finclip_send_custom_event(const char *app_id, const char *params);
# 24.1 Parameters
app_id
Mini-Program ID
params
Event parameters
# 24.2 Return Value
- 0 Success
- <0 Failure
# 25. Trigger Title Bar Back Button
int finclip_invoke_back(const char *appid, void(*handle)(const char *appid, const char *params, void *input), void *input);
# 25.1 Parameters
appid
Mini-Program ID
handle
Callback function
input
Pass-through parameter
# 25.2 Return Value
- 0 Success
- <0 Failure
# 26. Register Proxy Method
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);
# 26.1 Parameters
appid
Mini-Program appid
proxy
Proxy method name
handle
Callback function
input
Pass-through parameter
# 26.2 Return Value
- 0 Success
- <0 Failure
# 27. Get Required Memory Size for Mini-Program Data Folder Path
int finclip_applet_path_size(const char *appid);
# 28. Get Mini-Program Data Folder Path
int finclip_applet_path(const char *str, char *data);
Note: This API will become invalid after the Mini-Program is closed.
Usage:
First, use finclip_applet_path_size to get the required memory size.
After allocating the memory, use finclip_applet_path to get the string.
Use Case 1: Convert file paths starting with finfile:// to absolute paths.
Replace finfile:// with the return value and concatenate the file path separator.
Use Case 2: Get the temporary folder path by appending /tmp to the return value.
# 29. Get Bound Mini-Program List
int finclip_applet_bind_list(const char *appstore, const char *app_class, int app_status, bool contain_forbidden, int page_no, int page_size, void(*handle)(const char *res, void *input), void *input);
# 29.1 Parameters
appstore
Server-configured App Store
app_class
Mini-Program category
app_status
Mini-Program status type: 0: All; 1: Published; 2: Unpublished; 3: Removed
contain_forbidden
Whether the query result includes disabled Mini-Programs
page_no
Page number for paginated queries
page_size
Page size for pagination
handle
Callback function
input
Pass-through parameter
# 29.2 Return Value
- 0 Success
- <0 Failure
# 30. Set Log Level
int finclip_set_log_level(const char *level);
# 30.1 Parameters
level
Allowed values: debug/info/warn/error
# 30.2 Return Value
- 0 Success
- <0 Failure
# 31. Get Mini-Program Performance Statistics
int finclip_performance_record(const char *appid, void(*handle)(const char *res, void *input), void *input);
# 31.1 Parameters
appid
Mini-Program appid
handle
Callback function
input
Pass-through parameter
# 31.2 Return Value
- 0 Success
- <0 Failure
# 32. Register SDK Status Event Callback
int finclip_sdk_lifecycle(void(*handle)(void *input), void *input);
# 32.1 Parameters
handle
Callback function
input
Pass-through parameter for the callback function
# 32.2 Return Value
- 0 Success
- <0 Failure