You can implement server matching features with Server API. With server matching enabled, the device will defer the authentication process to the device gateway. Whenever a user places a card or fingerprint on the device, it will send a request to the gateway. Then, you have to handle these requests using one of the APIs.

To implement server matching, you have to do the following steps.

  1. Enable the related options.

    Function Option Handler
    Verify AuthConfig.useServerMatching HandleVerify
    Identify AuthConfig.useServerMatching HandleIdentify
    Global APB AuthConfig.useGlobalAPB HandleGlobalAPB
    User Phrase DisplayConfig.useUserPhrase/queryUserPhrase HandleUserPhrase
  2. Subscribe to the request channel using Subscribe.
  3. Implement your own logic using the corresponding handler.
  4. Unsubscribe from the channel using Unsubscribe

Server API is not supported by the master gateway.

Subscribe

If subscription is successful, devices will send the following requests to the device gateway.

message ServerRequest {
  RequestType reqType;
  uint32 deviceID;
  uint32 seqNO;
  VerifyRequest verifyReq; 
  IdentifyRequest identifyReq;
  GlobalAPBRequest globalAPBReq;
  UserPhraseRequest userPhraseReq;
}
reqType
The type of the request.
deviceID
The ID of the device, which sent the request.
seqNO
The sequence number of the request. You have to use this number when returning a response to the device.
verifyReq
Valid only if the reqType is VERIFY_REQUEST.
identifyReq
Valid only if the reqType is IDENTIFY_REQUEST.
globalAPBReq
Valid only if the reqType is GLOBAL_APB_REQUEST.
userPhraseRequest
Valid only if the reqType is USER_PHRASE_REQUEST.
enum RequestType {
  NO_REQUEST = 0x00;
  VERIFY_REQUEST = 0x01;
  IDENTIFY_REQUEST = 0x02;
  GLOBAL_APB_REQUEST = 0x03;
  USER_PHRASE_REQUEST = 0x04;
}

message VerifyRequest {
  bool isCard;
  card.Type cardType;
  bytes cardData;
  string userID;
}
isCard
If true, you have to look up cardType and cardData for the verification. If false, you have to look up userID.
message IdentifyRequest {
  finger.TemplateFormat templateFormat;
  bytes templateData;
}

message GlobalAPBRequest {
  repeated string userIDs;
}

message UserPhraseRequest {
  string userID;
}

Handling of the requests varies according to the programming language. Refer to the server API example in your client SDK.

Subscribe

Request
Parameter Type Description
queueSize int32 If the queue is full, the gateway will discard the requests. It should be large enough for handling concurrent requests

Unsubscribe

There can be only one channel. So, if you want to reuse the channel, you have to unsubscribe from it first.

Matching

HandleVerify

With AuthConfig.useServerMatching true, the device will send a VerifyRequest to the gateway when it reads a card. You have to send a response to the device using this API.

Request
Parameter Type Description
deviceID uint32 The ID of the device. It should be same as deviceID in the request.
seqNO uint32 The sequence number of the response. It should be same as seqNO in the corresponding request.
errCode ServerErrorCode The result of verification. If it is SUCCESS, you have to fill the verified user information in user field.
user user.UserInfo The information of the verified user. 
enum ServerErrorCode {
  SUCCESS = 0;

  VERIFY_FAIL = -301;
  IDENTIFY_FAIL = -302;

  HARD_APB_VIOLATION = -1202;
  SOFT_APB_VIOLATION = -1203;

  CANNOT_FIND_USER =  -714;
}

HandleIdentify

With AuthConfig.useServerMatching true, the device will send an IdentifyRequest to the gateway when it reads a fingerprint. You have to send a response to the device using this API.

Request
Parameter Type Description
deviceID uint32 The ID of the device. It should be same as deviceID in the request.
seqNO uint32 The sequence number of the response. It should be same as seqNO in the corresponding request.
errCode ServerErrorCode The result of identification. If it is SUCCESS, you have to fill the identified user information in user field.
user user.UserInfo The information of the identified user.

HandleGlobalAPB

With AuthConfig.useGlobalAPB true, the device will send a GlobalAPBRequest to the gateway after successful authentication.

Request
Parameter Type Description
deviceID uint32 The ID of the device. It should be same as deviceID in the request.
seqNO uint32 The sequence number of the response. It should be same as seqNO in the corresponding request.
errCode ServerErrorCode The result of anti passback violation. If violated, the result will be either HARD_APB_VIOLATION or SOFT_APB_VIOLATION based on the type of zone.
zoneID uint32 The ID of the anti passback zone.

User interface

Apart from server matching, you can also show a user-specific message after authentication.

HandleUserPhrase

With DisplayConfig.useUserPhrase/queryUserPhrase true, the device will send a UserPhraseRequest after successful authentication. You have to send a response to the device using this API.

Request
Parameter Type Description
deviceID uint32 The ID of the device. It should be same as deviceID in the request.
seqNO uint32 The sequence number of the response. It should be same as seqNO in the corresponding request.
errCode ServerErrorCode If it is SUCCESS, you have to send the user phrase in userPhrase field.
userPhrase string The message to be displayed in the UI of the device.

Updated: