Introduction

This reference documents every object and method available in Perse's browser-side Javascript library, Perse.js.

You can use Perse's APIs to detect faces, gather feedback on image quality and compare the similarity between two faces. This SDK provides methods that help you authenticate users identity and directly communicate with Perse's API endpoints. The SDK also abstracts away the usage of common cases.

Check our project on npm (opens new window)

If you only want an easier way to connect to API, without extra logics and tiny size check perse web sdk lite (opens new window).

Token

In order to use PerseJs, it's necessary to create a session token using your private key.

The session token can be created by using your Perse's private key (opens new window) on server side and making a POST request to https://api.getperse.com/v0/login. Some frontend SSR frameworks and applications, as nuxt and next.js, provides a way to safely request and refresh session token. If it fits your use case, consult your framework documentation to don't expose any sensitive data to client.

Your private key should be on body, inside privateKey.

{
	"privateKey": "YOUR_PRIVATE_KEY"
}

Pay Attention: It's important to notice that the session token returned by /login expires in 15 minutes, so it's necessary to set JWT token again.

try {
  Perse.face.detect(myImage)
} catch (e) {
  if (e.code === 'unauthorized') {
    fetchJWTTokenFromMyBackend()
  }
}

Errors

Perse.js encapsulates and manages API responses to return structures that are easier process.

It provides a message that can be used to give feedback to the user and also appears as a warning on browser console.

In order to know if the operation succeed, you can verify the status flag and the failure reason can be treated by using code.

The structure and codes are grouped on the following types:

Returned Data Attributes

Whenever there is an error, the server will return a JSON encoded response with the following structure.

messag string
A human-readable message providing more details about the error.

cod string
A simple string with the code message for programmatic error handling.

status boolean
Boolean flag that indicates if operation succeed or not.

Error Codes

content_type_header_missin
The request header is missing the content-type key with the value of multipart/form-data.

no_face_detecte
The model could not find a face in at least one of the images. Please check the property image_metrics for insight on the image quality.

empty_fil
The source file is empty or not sent.

invalid_file_typ
The image file type is not accepted by API.

form_key_missing
The request is missing: image file(s) or token

file_too_larg
The source file byte size is too large. Please send image files with less than 1 MB.

not_simila
Person on sent images has low similarity value.

bad_image_qualit
Image has a bad quality. It is overexposed, underexposed or not sharpened.

image_underexposed - Enrollment onl
The image file received is too underexposed and could not be used for enrollment.

image_overexposed - Enrollment onl
The image file received is too overexposed and could not be used for enrollment.

user_token_not_foun
User token does not exist on backend.

image_id_invali
User token was not found on update.

no_face_biometric_dat
User token was not found when comparing image with userToken.

unauthorized
JWT token expired or not valid.

{
  "message": "The source file is empty or wasn't sent.",
  "code": "empty_file",
  "status": false
}

Image Requirements

File formats: JPG, PNG

File size: no files larger than 1 MB.

Image dimensions: For best performance we recommend images where faces are at least 200x200 pixels.

End user Consentment

In order to use Perse SDK, it's necessary to ask end user for consent and inform it inside enduserConsent parameter. Informing end user consent is required for every endpoints that uses biometric data. If consent is false, the request will not be processed.

Including Perse

First you need to include the Perse javascript library into your project. Second, initialize the library in order to access Perse global variable.

NPM

NPM is the recommended installation method when building large scale applications with Perse. It pairs nicely with module bundlers such as Webpack or Browserify.

npm install @cyberlabsai/perse-sdk-js

CDN

You may also simply download and include Perse.js using a script tag. Perse will be registered as a global variable.

<script src="http://unpkg.com/@cyberlabsai/[email protected]">
</script>

Initializing Perse

To get started you should use Perse.setToken(JWT_TOKEN) on Perse object. The Perse object gives you access to all Perse.js SDK methods. As explained on token it's necessary to update the JWT token every 15 minutes. When JWT expires, Perse's methods return an 'anauthorized' error code. So it's necessary to fetch a new token from backend

import * as Perse from '@cyberlabsai/perse-sdk-js'

Perse.setToken(JWT_TOKEN)

try {
  Perse.face.detect(myImage)
} catch (e) {
  if (e.code === 'unauthorized') {
    const newToken = await fetchJWTTokenFromMyBackend()
    Perse.setToken(newToken)
  }
}