# Desktop Usage Guide

# 1. API Description

# 1. API Style

The SDK's APIs are designed in C language style, providing external DLL/SO files for invocation. Therefore, when using higher-level programming languages to call these APIs, attention must be paid to the differences and details inherent in the idiomatic practices of different languages.

# 2. Basic Concepts

The SDK has two important objects: the Server Object and the Mini-Program Object. The Server Object is distinguished by appstore, while the Mini-Program Object is distinguished by appid. Typically, when an API needs to use/modify the corresponding object, these two values are used as parameters. For example:

// Operate the Mini-Program Object: close the specified Mini-Program
finclip_close_applet(const char* appid);

// Read the content of the Server Object: start the Mini-Program with the specified appid
finclip_start_applet(const char* appstore, const char* appid);

# 3. Callback Functions

Some API parameters include callback functions. For example:

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

void* input

Note that APIs containing callback functions usually have a void* input parameter. This parameter will be passed back as-is when the callback is triggered and is unrelated to specific business logic. A common practice is to pass this/self or similar context into this parameter to ensure it can be used within the callback function.

# 4. Return Values

APIs typically have two types of return values: integer error codes or pointers.

  • For functions returning error codes, refer to finclip_api_error.h for corresponding error information.
  • For functions returning pointers, please note the destruction method; manual control over destruction is required.

# 5. Other Considerations

When calling APIs with callback functions, be cautious of garbage collection issues in higher-level languages. If the callback is triggered after being garbage collected, it may cause the SDK to crash.

# 2. Custom APIs

Custom APIs are used for communication between the Host-App and Mini-Programs/embedded WebView pages. Common scenarios include:

  1. The Host-App provides interfaces for Mini-Programs/embedded WebViews to call.
  2. The embedded WebView provides interfaces for the Host-App to call.

# 1. Host-App Provides Interfaces for Mini-Programs/Embedded WebViews

Use finclip_register_api to implement custom APIs:

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(callbackid, res);
    finclip_destory_params(res);
}

finclip_register_api(kWebView, "test", WebApiExample, this);

Call the API within the Mini-Program to get the result returned by the Host-App:

wx.test({});

# 2. Embedded WebView Provides Interfaces for Host-App

The WebView page registers the corresponding event:

window.ft.onNativeAPIHandler('test', cb)

The Host-App calls the API to get the result:

finclip_invoke_api(0, appid, "test", params, callback, input);

# 3. Lifecycle Callbacks

Mini-Programs define 7 lifecycle events. You can listen to the corresponding events as needed.

// Supported callback types
enum LifecycleType {
  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
};

// Define the lifecycle handler function
void LifecycleHandle(LifecycleType type, const char* appid, void* input) {
    // Note: Threading issues need to be handled here, such as:
    // 1. Locking global variables
    // 2. If this handler needs to handle the UI, it may need to be dispatched to the UI thread depending on the UI framework
    // ...
}

// Register the lifecycle callback
finclip_register_lifecycle(appid, kLifecycleClosed, LifecycleHandle, window)

# 4. custom_event

The custom_event is used for the Host-App to send messages to the Mini-Program.

First, listen to the onCustomEvent event within the Mini-Program:

const callback = (res) => {
    console.log(res)
}
wx.onCustomEvent(callback)

The Host-App calls finclip_send_custom_event to send the event:

finclip_send_custom_event(app_id, params);

# 5. Embedding Mode

Currently, embedding mode is only supported on Windows. Support for Mac and Linux is under development.

# 5.1 Embedding a Window

To embed a Mini-Program into your window, first obtain the window handle, denoted as hwnd. We provide two APIs to complete window embedding.

  finclip_start_applet_embed(appstore, appid, params, hwnd); // Embed the Mini-Program into the specified window upon startup
  finclip_embed_applet(appid, hwnd); // Embed an already started Mini-Program into the specified window

# 5.2 Handling Scaling Events

When your window changes size, you need to listen for window change events and notify the Mini-Program process of the new width and height.

  finclip_set_position(appid, left, top, width, height);

# 5.3 Closing Handling

There are two scenarios for exit:

  1. The Host-App window closes first. In this case, you need to call finclip_close_applet to notify the FinClip process to exit, or use other methods to terminate the process.
  2. The FinClip process closes first. In this case, you need to handle the message sent by FinClip.
  // Scenario 1: Host-App window closes first. You need to notify the Mini-Program to exit in the window close event.
  finclip_close_applet(appid); // Notify the Mini-Program to close

  // Scenario 2: Mini-Program closes first. You need to close the Host-App window in the Mini-Program's closed lifecycle event.
  void LifecycleHandle(LifecycleType type, const char* appid, void* input) {
    if (type == kLifecycleClosed) {
      window.close();
    }
}

# 6. Debug Mode

# 6.1 Debugger Introduction

Debug mode is primarily intended for Mini-Program developers. Through the debugger interface, developers can perform operations such as calling Mini-Program APIs and observing Mini-Program logs, making it easier to locate issues.

When entering the debugger window, you can see a list of pages for the currently running Mini-Program. The service.html page is similar to the vConsole interface, where you can execute Mini-Program APIs. The other pages correspond to the pages already opened by the Mini-Program.

console.log Output Location

When you call console.log in your Mini-Program code to print variables, the output may appear in the service.html page or in the corresponding Mini-Program page.

image.png

image.png

# 6.2 How to Enable Debug Mode

Debug mode can be enabled in two ways: configuring startup parameters or setting environment variables. Supported starting from SDK version 1.6.5.

  • Configuring Startup Parameters

By configuring the startup parameter remote_debug when starting the Mini-Program, you can control whether debug mode is enabled for each Mini-Program individually. This step needs to be handled during SDK integration.

Before starting the Mini-Program using the API:

finclip_start_applet_params(const char* appstore, const char* appid, FinclipParams* params);

Add the startup parameter to the params:

finclip_params_set(params, "remote_debug", "1");

This will enable debug mode for that Mini-Program.

  • Setting Environment Variables

By setting the environment variable FINCLIP_DEBUG to 1, you can enable debug mode for all Mini-Programs (supports Windows/Linux).

How to Set Environment Variables

Windows

  1. Open the Run dialog with the shortcut Win + R.
    image.png
  2. Enter sysdm.cpl in the Run dialog to open the System Properties window.
  3. In the System Properties window, switch to the "Advanced" tab and click the "Environment Variables" button at the bottom.
    image.png
  4. Click "New", enter the variable name FINCLIP_DEBUG and value 1 to add it successfully.
    image.png

Linux Enter export FINCLIP_DEBUG=1 in the terminal to configure the environment variable. Note that this configuration is only effective for the current terminal session.

# 6.3 Differences After Enabling Debug Mode

  • After enabling debug mode, the SDK's log files will output Debug-level logs, which are more detailed than the normal Info-level logs.
  • After enabling debug mode, you can access the Mini-Program's debug interface via the more menu in the upper right corner (as shown in the image).
    image.png

# 6.4 Usage Scenarios

Recommended practices for enabling debug mode in different usage scenarios:

  • SDK Integrators

SDK integrators can conveniently enable debug mode during the development phase by adding the remote_debug parameter when starting the Mini-Program. This method can also be exposed to Mini-Program developers or testers for their use.

  • Mini-Program Developers or Testers

For personnel developing or testing Mini-Programs within an already integrated application:

  • If the SDK integrator provides a way to set the remote_debug startup parameter, it is recommended to use that method.
  • If the remote_debug parameter cannot be configured, then use the environment variable method to enable debug mode.
  • End Users

If end users report issues that are difficult to reproduce and need to be troubleshooted in the user's environment, enable debug mode by setting the environment variable.

© FinClip with ❤ , Since 2017