Get Started with FACEIO

Create and configure the application:

1

Connect to the FACEIO Console ↗.

2

On the Console main view, click New Application. This will launch the Application Wizard.

3

In the Application Wizard, follow the on-screen instructions as shown below. This involves entering an application name, privacy policy URL, selecting a Facial Recognition Engine, choosing cloud storage region or on-premise deployment, configuring security options, and customizing the widget.

Click to explore the Application Wizard

4

Finally, review your configuration and submit. Once your application is successfully created, you'll be redirected to the Application Manager ↗, where you can manage your new application with a step-by-step integration guide.

1 Import fio.js to Your Site

Paste the following snippet before the closing </body> tag of the HTML page(s) where you want to use fio.js:

<div id="faceio-modal"></div>
<script src="https://cdn.faceio.net/fio.js"></script>

The snippet above loads fio.js asynchronously. A basic HTML page can initialize the library as follows:

<html>
  <head>
    <title>Sign-In via Face Recognition</title>
  </head>
  <body>
    <div id="faceio-modal"></div>
    <script src="https://cdn.faceio.net/fio.js"></script>
  </body>
</html>

2 Instantiate a faceIO Object

To initialize fio.js, simply instantiate a new faceIO() object and pass your application Public ID as shown below. You can also insert this snippet right after the import code from Step 1. For a complete example, refer to the HTML Boilerplate.

<script type="text/javascript">
   /* Instantiate fio.js with your application Public ID */
    const faceio = new faceIO("app-public-id");
</script>

The enroll() Method

• Call enroll() on the initialized faceIO object to register a new user. It opens the FACEIO Widget and starts the facial enrollment flow from your existing sign-up or onboarding page.

• When you call enroll(), the FACEIO Widget opens, requests user consent and camera access when needed, and captures the face data required for enrollment. The selected facial recognition engine generates and indexes the biometric hash used for future authentication.

• enroll() accepts several optional parameters, such as locale for the interaction language, permissionTimeout for the camera access wait time, and most importantly payload, which is arbitrary data you can associate with the user like an email, name, or ID. This payload is returned after a successful future authentication.

• enroll() returns a Promise that resolves to a userInfo object when enrollment succeeds. It includes the user's Facial ID, enrollment timestamp, and the details.age and details.gender estimates. Use the Facial ID as a lookup key for the corresponding backend account during future authentication.

• If the user denies camera access or rejects Terms of Service, the promise is rejected with the corresponding error code (e.g., fioErrCode.PERMISSION_REFUSED or fioErrCode.TERMS_NOT_ACCEPTED). Refer to the Error Codes section for a complete list.

• The enroll() method, parameters, return values, and error handling are documented in the Integration Guide.

The authenticate() Method

• Call authenticate() on the initialized faceIO object to recognize a previously enrolled user. Use it from the website or web app's sign-in flow.

• When you call authenticate(), the FACEIO Widget opens, requests camera access when needed, performs the configured liveness and facial recognition checks, and returns the authentication result.

• Depending on your app's security configuration, once the user is successfully identified by the facial recognition engine, they may need to confirm their PIN code (chosen during enrollment) for the authenticate() method to succeed.

• authenticate() accepts several optional parameters, including permissionTimeout for camera access wait time, locale for the interaction language, and other options, all documented here.

• authenticate() returns a Promise that resolves with a userData object upon successful identification. Key properties include: payload (the data you linked during enrollment) and facialId (the user's unique identifier). Together, these can serve as lookup keys in your backend to fetch user-specific data.

• The authenticate() method, parameters, return values, and error handling are documented in the Integration Guide.

Enrolling a New User

Onboarding a new user (extracting and indexing their facial features after obtaining consent) is accomplished with a simple call to enroll():

// Instantiate a new faceIO object with your application's Public ID
const faceio = new faceIO("app-public-id");
function enrollNewUser(){
  faceio.enroll({
    "locale": "auto", // Default user locale
    "payload": {
        /* The payload we want to associate with this particular user which is forwarded back to us upon future authentication of this user.*/
        "whoami": 123456, // Dummy ID linked to this particular user
        "email": "john.doe@example.com"
        }
    }).then(userInfo => {
        // User Successfully Enrolled! 
        alert(
            `User Successfully Enrolled! Details:
           Unique Facial ID: ${userInfo.facialId}
           Enrollment Date: ${userInfo.timestamp}
           Estimated Gender: ${userInfo.details.gender}
           Approximate Age: ${userInfo.details.age}`
        );
       console.log(userInfo);
       // handle success, save the facial ID (userInfo.facialId), redirect to the dashboard...
    }).catch(errCode => {
       // Something went wrong during enrollment, log the failure
       handleError(errCode);
    })
}

• Initialization: Instantiate the faceIO object with your application's Public ID. Replace "app-public-id" with your actual Public ID from the FACEIO Console ↗.

• Enrollment call: The enroll() call starts registration, requests user consent and camera access when required, and initiates facial feature extraction. The payload parameter lets you associate data with the user, such as a user ID (whoami) and email address. This payload will be returned upon successful future authentication.

• Enrollment result: On successful enrollment, the promise resolves with a userInfo object containing the unique Facial ID, enrollment timestamp, and the details.gender and details.age estimates. Store the Facial ID in your database to identify this user during future authentication.

• Error handling: Catch enrollment failures and implement a handleError() function to handle the returned error codes. Review the error codes documentation for all possible error codes.

Authenticating an Existing User

Similarly, authenticating (recognizing) a previously enrolled user is accomplished with a simple call to authenticate():

const faceio = new faceIO("app-public-id"); // Initialize with your application's Public ID
function authenticateUser(){
    faceio.authenticate({
        "locale": "auto" // Default user locale
    }).then(userData => {
        console.log("Success, user identified")
        // Read the Facial ID returned for this user. It remains the same
        // after each successful authentication in this application.
        // Store it as the lookup key for the corresponding backend account.
        console.log("Linked facial Id: " + userData.facialId)
        // Grab the arbitrary data you have already linked (if any) to this particular user
        // during enrollment via the payload parameter of the enroll() method.
        console.log("Payload: " + JSON.stringify(userData.payload)) // {"whoami": 123456, "email": "john.doe@example.com"} from the enroll() example above
    }).catch(errCode => {
        handleError(errCode)
    })
}

• Initialization: Initialize the faceIO object with your application's Public ID, just like in the enrollment example.

• Authentication call: The authenticate() call starts authentication, requests camera access when required, and initiates facial recognition. The locale parameter sets the widget's interaction language.

• Authentication result: On successful authentication, the promise resolves with a userData object. The userData.facialId is the stable identifier for this user across authentications. Use it as the primary key for looking up the user in your backend. The userData.payload contains the data linked during enrollment, such as {"whoami": 123456, "email": "john.doe@example.com"}.

• Error handling: Catch authentication failures and implement a handleError() function to handle each returned error code. See the error codes documentation for all possible error codes.