Sign-In or Enroll via Face Recognition

### Full HTML Page with fio.js and Basic Interaction Functions Source: https://faceio.net/integration-guide/integration-guide A comprehensive HTML example showing the integration of fio.js, including buttons to trigger enrollment and authentication processes, and placeholder JavaScript functions for handling these actions and errors. This serves as a starting point for interactive facial recognition applications. ```HTML Sign-In or Enroll via Face Recognition ``` -------------------------------- ### Basic HTML Page Structure with fio.js Integration Source: https://faceio.net/integration-guide/integration-guide A complete, minimal HTML page demonstrating the correct placement of the fio.js import snippet within the `` section for basic integration. This serves as a typical example for a lambda HTML page. ```HTML Sign-In via Face Recognition ``` -------------------------------- ### FACEIO `enroll()` API Reference Source: https://faceio.net/integration-guide/integration-guide Comprehensive documentation for the `enroll()` method, detailing its optional `parameters` object properties and the structure of the `userInfo` object returned on successful enrollment. This method initiates the user enrollment process. ```APIDOC enroll(parameters?: object) -> Promise Parameters: parameters: object (optional) An optional object containing properties to configure the enrollment process. Properties: payload: Any Serializable JSON (Default: NULL) An arbitrary set of data to associate with the user being enrolled. Max 16KB. Base64 encode non-ASCII/binary data. permissionTimeout: Number (Default: 27 Seconds) Total seconds to wait for camera access permission. Rejects with `fioErrCode.PERMISSION_REFUSED` if timed out. termsTimeout: Number (Default: 10 Minutes) Total minutes to wait for user to accept FACEIO/Host Application Terms of Service. Rejects with `fioErrCode.TERMS_NOT_ACCEPTED` if timed out. idleTimeout: Number (Default: 27 Seconds) Total seconds to wait if no faces are detected during enrollment. Rejects with `fioErrCode.NO_FACES_DETECTED` if timed out. replyTimeout: Number (Default: 40 Seconds) Total seconds to wait for a response from the remote FACEIO processing node. Rejects with `fioErrCode.TIMEOUT` if timed out. enrollIntroTimeout: Number (Default: 12 Seconds) Enrollment Widget introduction/instruction screen display delay. locale: String (Default: auto) Default interaction language for the Widget display (BCP 47, two-letter code, e.g., 'en', 'es'). Falls back to 'en-us' if unsupported. userConsent: Boolean (Default: false) Set to true if user consent has already been granted, skipping the Terms of Use consent screen. Return Value: Promise A Promise that resolves with a `userInfo` object upon successful enrollment, or rejects with an error code on failure. userInfo: object An object containing information about the successfully enrolled user. Properties: facialId: UUID An identifier assigned anonymously by the underlying facial recognition engine to this particular user. timestamp: Timestamp (String) ISO 8601 formatted enrollment completion date & time. details: Object An object containing approximate demographic information. Properties: gender: String Approximate gender of the enrolled user. age: Number Approximate age of the enrolled user. ``` -------------------------------- ### FACEIO `enroll()` Method API Documentation Source: https://faceio.net/integration-guide/integration-guide Comprehensive API documentation for the `enroll()` method, detailing its purpose, behavior, parameters, return values, and error handling. ```APIDOC enroll(options?: object): Promise Description: Transactionally enrolls new users via face recognition (on-boarding). This method is equivalent to a register/sign-up function in traditional authentication systems. It triggers the FACEIO Widget, handles user consent, requests camera access, and extracts/indexes facial features for future authentication. Facial vectors are stored as an array of floating point numbers, acting as a meaningless hash that cannot be reverse-engineered. Only your application with its encryption key can access the index. The operation is two-step: collecting user consent (if not yet granted) and then indexing facial features (requires only two frames, bandwidth efficient). Users are prompted to input a 4-16 digit PIN code. This PIN is used for future authentication in cases of collision (similar faces), confidence score slightly lower than 99% threshold, or when your application enforces PIN code confirmation. Parameters: options (object, optional): An object containing optional parameters. locale (string): The language for the interaction. permissionTimeout (number): The number of seconds to wait for the user to grant camera access. payload (any): An arbitrary set of data that can be linked to this particular user (e.g., Email Address, Name, ID). This payload will be forwarded back to your application upon successful future authentication of this user. Returns: Promise: A Promise whose fulfillment handler receives a `userInfo` object when the user has successfully been enrolled. userInfo (object): facialId (string): A Unique Identifier assigned to the enrolled user. This Facial ID can serve as a lookup key on your backend for example to fetch data linked to this particular user on future authentication. // Other members of userInfo are detailed in the Return Value section of the full documentation. Errors: The Promise is rejected with a corresponding error code if the user denies camera access or rejects terms of use, etc. fioErrCode.PERMISSION_REFUSED: If the user denies camera access permission. fioErrCode.TERMS_NOT_ACCEPTED: If the user rejects the Terms of Use. // Refer to the Error Codes section for the full list of all possible error codes. Webhooks: If a Webhook handler is registered for your application on the FACEIO Console, `enroll()` will make a POST request to the configured URL after each successful enrollment. Webhooks allow your system to receive data and get notified in real-time about ongoing events during the interaction of the FACEIO Widget with your users, keeping your application backend up-to-date and synchronized. ``` -------------------------------- ### JavaScript Example for FACEIO authenticate() Method Source: https://faceio.net/integration-guide/integration-guide Demonstrates how to integrate the `faceio.authenticate()` method into a client-side JavaScript application. It shows initialization, calling the method with locale options, handling successful authentication to access `userData` (including `facialId` and `payload`), and catching potential errors. ```JavaScript const faceio = new faceIO("app-public-id"); function authenticateUser(){ faceio.authenticate({ "locale": "auto" }).then(userData => { console.log("Success, user identified") // Grab the facial ID linked to this particular user which will be same // for each of his successful future authentication. FACEIO recommend // that your rely on this Facial ID if you plan to uniquely identify // all enrolled users on your backend for example. console.log("Linked facial Id: " + userData.facialId) // Grab the arbitrary data you have already linked (if any) to this particular user // during his enrollment via the payload parameter of the enroll() method. console.log("Payload: " + JSON.stringify(userData.payload)) // {"whoami": 123456, "email": "[email protected]"} from the enroll() example above }).catch(errCode => { handleError(errCode) }) } ``` -------------------------------- ### Enroll New User with faceIO JavaScript SDK Source: https://faceio.net/integration-guide/integration-guide Demonstrates how to use the faceIO JavaScript SDK's `enroll()` method to register a new user. It includes instantiating the faceIO object, passing a custom payload, handling successful enrollment with user information, and catching potential errors during the process. ```javascript // 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": "[email protected]" } }).then(userInfo => { // User Successfully Enrolled! alert( `User Successfully Enrolled! Details: Unique Facial ID: ${userInfo.facialId} Enrollment Date: ${userInfo.timestamp} Gender: ${userInfo.details.gender} Age Approximation: ${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); }) } ``` -------------------------------- ### faceio.enroll() Method API Reference Source: https://faceio.net/integration-guide/integration-guide Documentation for the `enroll()` method of the `faceIO` object, used for on-boarding new users. It returns a Promise that resolves with `userInfo` on successful enrollment or catches an `errCode` on failure, allowing for asynchronous handling of the facial recognition process. ```APIDOC promise = faceio.enroll({parameters}) promise .then(userInfo => { /* User successfully enrolled */ }) .catch(errCode => { /* handle the error */ }) ``` -------------------------------- ### Import fio.js Library into HTML Source: https://faceio.net/integration-guide/integration-guide This snippet demonstrates how to include the fio.js library into an HTML page by linking to its CDN. It should be placed before the closing `` tag for asynchronous loading, ensuring it doesn't affect page load speed. ```HTML ``` -------------------------------- ### FACEIO API Error Codes Reference Source: https://faceio.net/integration-guide/integration-guide This section details the various error codes that can be returned by the FACEIO `enroll()` and `authenticate()` methods when their promises are rejected. Each entry provides a description of the error and its effect on the ongoing operation. ```APIDOC fioErrCode.PERMISSION_REFUSED: Description: Access to the camera stream was denied by the end user. Effect on enroll() or authenticate(): Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.TERMS_NOT_ACCEPTED: Description: Terms & Conditions set out by FACEIO/host application rejected by the end user. Effect on enroll() or authenticate(): Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.SESSION_IN_PROGRESS: Description: Another authentication or enrollment operation is processing. This can happen when your application logic calls more than once enroll() or authenticate() due to poor UI implementation on your side (eg. User taps twice the same button triggering the facial authentication process). Starting with fio.js 1.9, it is possible now to restart the current user session without reloading the entire HTML page via simple call to the restartSession() method. Effect on enroll() or authenticate(): Ongoing operation is still processing and the FACEIO Widget continue running. Your error handler routine should probably ignore this error code as the operation is still ongoing. fioErrCode.FACE_DUPLICATION: Description: Introduced in version 1.9. This error code is raised when the same user tries to enroll a second time on your application. That is, his facial features are already recorded due to previous enrollment, and can no longer enroll again due to the security setting: "Prevent Same User from Enrolling Twice or More" being activated. Effect on enroll() or authenticate(): Ongoing enroll() operation is immediately aborted and control is transferred to the host application. fioErrCode.MINORS_NOT_ALLOWED: Description: Introduced in version 2.19. This error code is raised when a minor less than 18 years old try to onboard on your application following activation of the: "Forbid Minors From Enrolling On This Application" security setting. You may want to activate this feature if your application is offering sensitive services, and you need to comply with jurisdiction (eg: UK & Some US states) that forbid minors from accessing such services. PixLab software including Insight, the default facial recognition engine for FACEIO are ready to meet the PAS 1296:2018 code of practice for online age verification accredited by UK’s Age Check Certification Scheme (ACCS). Effect on enroll() or authenticate(): Ongoing enroll() operation is immediately aborted and control is transferred to the host application. fioErrCode.TIMEOUT: Description: Ongoing operation timed out (eg, camera Access Permission, ToS Accept, Face not yet detected, Server Reply, etc.). Effect on enroll() or authenticate(): Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.NO_FACES_DETECTED: Description: No faces were detected during the enroll or authentication process. Effect on enroll() or authenticate(): Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.UNRECOGNIZED_FACE: Description: Unrecognized/unknown face on this application Facial Index. Effect on enroll() or authenticate(): Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.MANY_FACES: Description: Two or more faces were detected during the enroll or authentication process. Effect on enroll() or authenticate(): Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.PAD_ATTACK: Description: The face anti-spoofing system reported a Presentation attack (PAD) using a smartphone or printed picture for example during the authentication or enrollment process. For more information about Deep-Fakes & Face Anti-Spoofing prevention, and the technology behind it, please refer to our dedicated blog post here. Effect on enroll() or authenticate(): Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.UNIQUE_PIN_REQUIRED: Description: Supplied PIN Code must be unique among other PIN's on this application. This warning code is raised only from the enroll() method, and only if you have enabled the "Enforce PIN Code Uniqueness" Security Option. Effect on enroll() or authenticate(): Ongoing enroll() operation is still processing until the user being enrolled input a unique PIN code. fioErrCode.FACE_MISMATCH: Description: Calculated Facial Vectors of the user being enrolled do not matches. This error code is raised only from the enroll() method. Effect on enroll() or authenticate(): Ongoing enroll() operation is immediately aborted and control is transferred to the host application. ``` -------------------------------- ### FACEIO restartSession() Method API Reference Source: https://faceio.net/integration-guide/integration-guide Provides comprehensive API documentation for the `faceio.restartSession()` method. It outlines its syntax, purpose (purging current session and requesting a new one for subsequent enroll/authenticate calls without page reload), parameters (none), and return value. ```APIDOC faceio.restartSession() method: Syntax: boolean = faceio.restartSession({}) Description: Purges the current session and requests a new one, enabling subsequent calls to enroll() or authenticate() for the same user without page reload. This feature is available only for Premium Plans. Parameters: None Return Value: Type: boolean Description: true if a new session was granted and is ready for further enroll() or authenticate() calls; false otherwise. ``` -------------------------------- ### FACEIO authenticate() Method userData Object Structure Source: https://faceio.net/integration-guide/integration-guide Documents the structure of the `userData` object returned upon successful fulfillment of the `authenticate()` method's Promise. It details the `payload` and `facialId` properties, their types, and descriptions. ```APIDOC userData object: payload: Type: Any Description: Arbitrary data linked to the user during enrollment via the enroll() method's payload parameter. facialId: Type: UUID (String) Description: Unique Identifier assigned to the user, automatically generated. Recommended for uniquely identifying enrolled users on your backend. ``` -------------------------------- ### Instantiate faceIO Object with Public ID Source: https://faceio.net/integration-guide/integration-guide JavaScript snippet to initialize the faceIO library by creating a new `faceIO()` object, passing the application's unique Public ID as a parameter. This is a crucial step before using facial recognition features and can be placed just below the fio.js import. ```JavaScript ``` -------------------------------- ### faceIO authenticate() Method Syntax Source: https://faceio.net/integration-guide/integration-guide Provides the syntax for invoking the `authenticate()` method of the faceIO JavaScript SDK. This method is used to identify or recognize enrolled users and returns a promise that resolves with user data upon successful authentication or rejects with an error code. ```APIDOC promise = faceio.authenticate({parameters}) promise .then(userData => { /* User successfully authenticated/identified */ }) .catch(errCode => { /* handle the error */ }) ``` -------------------------------- ### FACEIO authenticate() Method API Reference Source: https://faceio.net/integration-guide/integration-guide Detailed API documentation for the FACEIO `authenticate()` method, including its purpose, parameters, and return values. This method securely authenticates previously enrolled users using facial recognition, triggering the FACEIO Widget and handling camera access. ```APIDOC authenticate() Method: Description: The `authenticate()` method securely authenticates (recognizes) previously enrolled users on your application. It functions as a login/sign-in. Calling it triggers the FACEIO Widget, requests camera access, and starts facial recognition. It requires only a single frame, executes in less than 100ms, and is bandwidth efficient. Depending on security configuration, a PIN code confirmation might be required for success. It takes optional parameters like `permissionTimeout` and `locale`. It returns a Promise that resolves with a `userData` object on successful identification. Key fields in `userData` include `payload` (arbitrary data from enrollment) and `Facial ID` (unique identifier). This data can be used as a lookup key on your backend. The Promise is rejected with error codes (e.g., `fioErrCode.PERMISSION_REFUSED`, `fioErrCode.TERMS_NOT_ACCEPTED`) if issues like camera access denial occur. Parameters: parameters: object (optional) permissionTimeout: Number Default: 27 Seconds Description: Total seconds to wait for camera access permission. If exceeded, `fioErrCode.PERMISSION_REFUSED` error is returned. idleTimeout: Number Default: 27 Seconds Description: Total seconds to wait if no faces are detected during authentication. If exceeded, `fioErrCode.NO_FACES_DETECTED` error is returned. replyTimeout: Number Default: 40 Seconds Description: Total seconds to wait for a response from the remote FACEIO processing node. If exceeded, `fioErrCode.TIMEOUT` error is returned. locale: String Default: auto Description: Default interaction language of the FACEIO Widget. If 'auto' or missing, language is deduced from Accept-Language header. Otherwise, provide a BCP 47, two-letter language code (e.g., 'en', 'ar'). If unsupported, falls back to 'en-us'. ``` -------------------------------- ### FACEIO API Error Codes Reference (fioErrCode) Source: https://faceio.net/integration-guide/integration-guide This section details various error codes returned by the FACEIO API, specifically from the `fio.js` library. Each error code includes a description of the issue, the method(s) it applies to, and the consequence of the error on the ongoing operation, providing insights into troubleshooting and handling API responses. ```APIDOC fioErrCode.WRONG_PIN_CODE: Description: Wrong PIN Code supplied by the user being authenticated. This error code is raised only from the authenticate() method. Consequence: Ongoing authenticate() operation is immediately aborted after three trials and control is transferred to the host application. fioErrCode.NETWORK_IO: Description: Error while establishing network connection with the FACEIO processing node. Consequence: Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.PROCESSING_ERR: Description: Server side error. Consequence: Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.UNAUTHORIZED: Description: Your application is not allowed to perform the requested operation (eg. Invalid ID, Blocked, Paused, etc.). Refer to the FACEIO Console for additional information. Consequence: Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.UI_NOT_READY: Description: The FACEIO fio.js library could not be injected onto the client DOM. Consequence: Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.TOO_MANY_REQUESTS: Description: Widget instantiation requests exceeded for freemium applications. Does not apply for premium applications as fio.js instantiation is unmetered. Consequence: Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.EMPTY_ORIGIN: Description: Origin or Referer HTTP request header is empty or missing while instantiating fio.js. Consequence: Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.FORBIDDDEN_ORIGIN: Description: Domain origin is forbidden from instantiating fio.js. Consequence: Ongoing operation is immediately aborted and control is transferred to the host application. fioErrCode.FORBIDDDEN_COUNTRY: Description: Country ISO-3166-1 Code is forbidden from instantiating fio.js. Consequence: Ongoing operation is immediately aborted and control is transferred to the host application. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.