Technical Support | Suprema

1. Intro

Welcome to this monthly article, where we'll delve into the Server Matching of the BoStar 2 Device SDK!

Q: What is the monthly article?
A: We publish a monthly article as a guide at the end of each month. It's designed to help our customers with specific SDK features they might have questions about or need further explanation about.

This guide will provide a comprehensive overview of how to effectively use this feature, from its fundamental workflow to practical code examples. By the end of this article, you'll be well-equipped to integrate Server Matching into your projects with confidence.

[Note] - Updated on August, 2025
Unfortunately, Server Matching is currently only available for cards. For fingerprint Server Matching, support can be obtained through Xperix. Face Server Matching is planned for future support but is not currently available.

2. Overall Workflow

The process of utilizing the Server Matching can be broken down into a few key steps. Understanding this workflow is crucial for a smooth and successful implementation.

[Step 1]: Connect to the device

Use Server Matching, you must first be connected to a device. We will omit the device connection methods in this article, as they are easily verifiable through the demo code.

[Step 2]: Enable server matching mode

To enable server matching, you need to configure the settings using BS2_SetAuthConfig. Please set useServerMatching to True within the BS2AuthConfig structure.

[Step 3]: Start a matching listener in your service

Registers callback functions that can distinguish whether the card, fingerprint, and user ID correspond. When the device reads specific data, the client service must be able to detect it. Use the  BS2_SetServerMatchingHandler API to register a listener. 

Callback Function:

To use the BS2_SetServerMatchingHandler API, you must register the VerifyUser callback function. This callback function is called when the client application needs to distinguish whether the card or user ID matches.

[Step 4]: Do the match on the server 

Server Matching is now ready for use. When a card is recognized on the device, the callback function is triggered. Inside the pre-registered callback function, card and user information are matched.

( ** Additional development is required to match the server data with the information read from the device.)

[Step 5]: Send the decision back to the device

After the server authentication is complete, the result must be sent to the device. Use the BS2_VerifyUser API to send the result to the device. Based on the handleResult, the device will determine whether authentication was successful or not and react accordingly. 

Tip!

If you want the device to perform additional actions after displaying the authentication result (e.g., relay, LED), the SDK provides the RunAction API to control the device further. This allows for more diverse device control.

Here is a diagram of the entire process.

3. Demo Code

In our Device SDK Demo code, a practical demonstration of how to implement the Device SDK server matching. 

The complete example code for Server Matching can be found by following the path below:

[The installation path for the SDK]\Example\cli\csharp\windows\BSDemo\ServerMatchingControl\ServerMatchingControl.cs

The following code snippet illustrates the full workflow, from initialization to execution.

public void serverMatching(IntPtr sdkContext, UInt32 deviceID, bool isMasterDevice)
{
    // 1. Get auth config and activate server matching if not already active.
    BS2ErrorCode result = (BS2ErrorCode)API.BS2_GetAuthConfig(sdkContext, deviceID, out authConfig);

    if (authConfig.useServerMatching == 0)
    {
        authConfig.useServerMatching = 1;
        result = (BS2ErrorCode)API.BS2_SetAuthConfig(sdkContext, deviceID, ref authConfig);
    }

    // 2. Register callback handlers for server matching events.
    cbOnVerifyUser = new API.OnVerifyUser(VerifyUser);
    cbOnIdentifyUser = new API.OnIdentifyUser(IdentifyUser);
    result = (BS2ErrorCode)API.BS2_SetServerMatchingHandler(sdkContext, cbOnVerifyUser, cbOnIdentifyUser);

    // 3. Start the server matching logic.
    matchingTask = new ServerMatchingTask();
    matchingTask.start();

    // ...
}

BS2UserBlob userBlob = Util.AllocateStructure<BS2UserBlob>();
BS2ErrorCode handleResult = find(ref userBlob);
Console.WriteLine("[Server] responded with a status of {0} : device[{1}] seq[{2}].", handleResult, deviceID, seq);
BS2ErrorCode result = (BS2ErrorCode)API.BS2_VerifyUser(sdkContext, deviceID, seq, (int)handleResult, ref userBlob);

4. FAQ (Frequently Asked Questions)

Here's a list of frequently asked questions about Server Matching to address common issues and clarify potential misunderstandings.

• Q1: What happens if the server doesn't send a result back to the device after a card is scanned? 
• A2: If the Server Matching option is enabled on the device, it will send data to the server.  If a response is not received from the server within the timeout period, the device will process the event as Access Denied without waiting further for the server’s response. In this case, the timeout follows the configuration shown below: BS2AuthConfig.matchTimeout (BS2AuthConfig)

• Q2: The device doesn't react after successful authentication. 
• A2: The server calls the BS2_VerifyUser API to send the authentication result. Confirm that you passed the correct value for successful authentication in the handleResult parameter of the BS2_VerifyUser API call. After a user has been found on the server, be sure to call the BS2_VerifyUser API to send the result!