WebSocket Registation

As mentioned on our introduction page. We don't use webhook to trigger face recognitation status. So you don't need to create a dedicated webhook to use our service.

You must implement websocket client pointing to our websocket server, register & listening to our dedicated websocket channel and get a face recognitation response status from us.

Websocket Client to select

You can choose any websocket client as you want, while we recommended this client for you:

• Pusher
• Socket.IO

Our websocket server work great with pusher client SDK, and will serve better with only minimal adjustment. On this page, we only provide pusher tutorial

Pusher Variable

On Pusher client SDK, init the sdk variable with following :

• cluster = main
• wsHost = socket.beoverflow.com
• forceTLS = true
• encrypted = true
• disableStats = true
• enabledTransports = ['ws', 'wss']

This is example of pusher client SDK with pusher web SDK :

related-page.html

let liveness_app_key = "truncated-liveness_app_key";
let socket_app_key = "truncated-socket_app_key";

let socketClient = new Pusher(socket_app_key, {
    cluster: "main",
    wsHost: 'socket.beoverflow.com',
    forceTLS: true,
    encrypted: true,
    disableStats: true,
    enabledTransports: ['ws', 'wss'],
});

Channel & Event

After initializationing pusher websocket client, you must subscribe to our websocket channel. The channel name are unique each clients, constructed with your dedicated liveness_app_key

Channel Rule

The channel to subscribe has following structure :

beoty.liveness.${liveness_app_key}

And this is example of subscribe code with pusher SDK Client :

related-page.html

socketClient.subscribe(`beoty.liveness.${liveness_app_key}`);

Event Rule

The event to listen has following structure :

${function_type}.${the_subject_id}

While function_type is one of the following :

• enroll
• verify

And this is example of event listener code with pusher SDK Client :

related-page.html

// FOR ENROLL EVENT
socketClient.bind(`enroll.${the_subject_id}`, (response) => {
    // YOUR OWN LOGIC
});

// FOR VERIFY EVENT
socketClient.bind(`enroll.${the_subject_id}`, (response) => {
    // YOUR OWN LOGIC
});

While the_subject_id is unique name or identifier defined by your end.

Event Response

The websocket event that you listened will give a response of json with the following structure :

websocket_event_structure.json

{
  "channel_name": string,
  "event_name": string,
  "data": {
    "status": boolean,
    "code": 200 | 400 | 403,
    "message": string,
    "data": {
        "unique_id" : "the unique id from our end, you can use it to check is liveness data are valid from us"
        "image": "base64 string"
    }
  }
}

with short description for each key as follow :

• channel_name is the name of channel you subscribe, it will same with your websocket client init config
• event_name is the name of event you bind / listen for
• data is advance response correspond the real value of face recognition status
  • status : the value will be "true" or "false",
    • true : means the enrolling or verifying complete & success
    • false : means the enrolling or verifyng complete but not success (can be caused by any error)
  • code : only a return signal code, 200 mean normal, 400 mean something wrong, 403 mean fatal error
  • message : string value for a short description, ideally you don't need this value
  • data : see example below

This is sample for enroll event response :

websocket_enroll_event_response_sample.json

{
  "channel_name": "beoty.liveness.{liveness_app_key}",
  "event_name": "enroll.{subject_id}",
  "data": {
    "status": true,
    "code": 200,
    "message": "All OK, face with subject_id {subject_id} enrolled",
    "data": {
        "unique_id": "35|15509|61385fb7-e13d-4960-99f3-2ec9562aeea3"
        "image": "base64 truncated"
    }
  }
}

This is sample for verify event response :

websocket_verify_event_response_sample.json

{
  "channel_name": "beoty.liveness.{liveness_app_key}",
  "event_name": "verify.{subject_id}",
  "data": {
    "status": true,
    "code": 200,
    "message": "All OK, face with subject_id {subject_id} verified",
    "data": {
        "unique_id": "35|15509|61385fb7-e13d-4960-99f3-2ec9562aeea3"
    }
  }
}

With this response, is up to you to handle the response and procced it with your own business logic or needs.

caution

On enrolling step, make sure to save "base64" image by your end. As a security maner, we will not provide any further enrolling image other than sended by our websocket face recognition event response.