> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Biometrics Module

> The Biometrics Module enables selfie/video capture and comparison against previously captured ID documents. It automatically integrates with your configured Biometrics provider (Onfido or Incode).

## Quick Implementation

<Steps>
  <Step title="Add HTML Element">
    First, add a container element to your HTML:

    ```html theme={null}
    <div id="biometrics"></div>
    ```

    <Callout icon="star" color="#3DD892" iconType="regular">
      You may need to adjust your Content Security Policy (CSP) settings to allow the IDV module to function correctly. Refer to <a href="/docs/v1/onesdk/oneSDK/implementation-guide#content-security-policy-csp-settings">this page</a> for more details.
    </Callout>
  </Step>

  <Step title="Initialize Module">
    Create and mount the biometrics component:

    ```javascript theme={null}
    const biometrics = oneSdk.component("biometrics");
    biometrics.mount("#biometrics");
    ```
  </Step>

  <Step title="Handle Events">
    Set up event listeners for biometric operations:

    ```javascript theme={null}
    biometrics.on("detection_complete", (event) => {
      console.log("Biometric capture completed");
    });

    biometrics.on("results", (results) => {
      console.log("Verification results:", results);
    });
    ```
  </Step>
</Steps>

## Provider-Specific Implementation

<Tabs>
  <Tab title="Onfido">
    <CardGroup cols={2}>
      <Card title="Implementation Flow" icon="circle-play">
        1. Mount component
        2. User clicks "Upload Recording"
        3. Receive `detection_complete` event
        4. Background processing begins
        5. Receive `results` event
      </Card>

      <Card title="Example Usage" icon="code">
        ```javascript theme={null}
        const biometrics = oneSdk.component('biometrics');

        // Mount component
        biometrics.mount("#biometrics");

        // Handle recording upload
        biometrics.on('detection_complete', (event) => {
          console.log('Recording uploaded');
        });
        ```
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Incode">
    <CardGroup cols={2}>
      <Card title="Implementation Flow" icon="circle-play">
        1. Mount component
        2. Follow on-screen instructions
        3. Receive `detection_complete` event
        4. Background processing begins
        5. Receive `results` event
      </Card>

      <Card title="Example Usage" icon="code">
        ```javascript theme={null}
        const biometrics = oneSdk.component('biometrics');

        // Mount component
        biometrics.mount("#biometrics");

        // Handle verification completion
        biometrics.on('detection_complete', (event) => {
          console.log('Verification completed');
        });
        ```
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Biometrics Events

<AccordionGroup>
  <Accordion title="ready">
    When the Biometrics component is successfully mounted, it will emit a `ready` event.

    To listen to this event, use:

    ```typescript theme={null}
      biometrics.on('ready', () => {
        console.log('idv component is ready')
      }); 
    ```
  </Accordion>

  <Accordion title="detection_complete">
    When the Biometrics component successfully detects your information, it will emit a `detection_complete` event. This event will be emitted immediately before `results`. To listen to this event, use:

    ```typescript theme={null}
      biometrics.on('detection_complete', () => {
        // programatically unmount your component
        setMounted(false);
      })
    ```
  </Accordion>

  <Accordion title="results">
    The end-user data is being submitted during this event. To listen to this event, use:

    ```typescript theme={null}
    biometrics.on('success', 
      (checkStatus, document, entityId) => {
        // you can extract information emitted from success event
        // and use it to your own use
      }
    )
    ```

    where the data types for the parameters are:

    ```json theme={null}
      checkStatus: 'COMPLETE' | 'FAILED',
      document: Object
      entityId: string
    ```

    `checkStatus` will consist of either COMPLETE or FAILED, where

    <>
      <ul>
        <li>“COMPLETE”: The process and the check results are ready.</li>

        <li>
          “FAILED”: The process is done but there was a genuine failure validating
          the captured ID and face.
        </li>
      </ul>
    </>

    `document`: the document object generated after the OCR extract

    `entityId`: FrankieOne’s internal reference for the individual
  </Accordion>

  <Accordion title="detection_failed">
    The component has run unsuccessfully. You can handle this event using a custom loading spinner or additional styles. To listen to this event, use:

    ```typescript theme={null}
    biometrics.on("detection_failed", () => {
      // programatically unmount your component
      setMounted(false);
    });
    ```
  </Accordion>

  <Accordion title="input_required">
    To listen to this event, use:

    ```typescript theme={null}
    biometrics.on("input_required", (information, checkStatus) => {
      if (checkStatus === "WAITING_SELFIE_UPLOAD") {
        console.log("waiting for selfie capture");
      }
    });
    ```

    `input_required` will emit entityId and current status of the process, such as:

    <>
      <ul>
        <li>waiting for Document upload `WAITING_DOC_UPLOAD`</li>
        <li>waiting for selfie upload `WAITING_SELFIE_UPLOAD`</li>

        <li>
          uploaded document has invalid type `AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE`
        </li>

        <li>
          or the process is either incomplete or interrupted `INCOMPLETE` /
          `INTERRUPTED`.
        </li>
      </ul>
    </>

    <Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
      For **Incode**, a lack of camera access permissions triggers the `INTERRUPTED`
      event.
    </Callout>
  </Accordion>

  <Accordion title="error">
    On error events, we throw all events from vendor back to you. To listen to this event, use:

    ```typescript theme={null}
    biometrics.on('error', (e) => {
    console.log(e.message, e.payload)
    })
    ```

    <Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
      If you’re using Incode, the possible messages are: `InternalServerError`, `OSVersionNotSupported`, and `browserNotSupported`
    </Callout>
  </Accordion>
</AccordionGroup>

## Implementation Best Practices

<CardGroup cols={2}>
  <Card title="Mobile Optimization" icon="mobile">
    ```html theme={null}
    <meta 
      name="viewport" 
      content="width=device-width, initial-scale=1.0" 
      charset="UTF-8" 
    />
    ```

    Ensure proper viewport settings for mobile devices.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    ```javascript theme={null}
    biometrics.on('error', (error) => {
      console.error('Biometrics error:', error);
      // Implement user-friendly error handling
    });
    ```
  </Card>
</CardGroup>

<Callout icon="star" color="#3DD892" iconType="regular">
  During development, test with both providers (if applicable) to ensure
  consistent behavior across different biometric implementations.
</Callout>

<Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
  For detailed event documentation and advanced configurations, refer to the
  complete [Biometrics Event
  Reference <Icon icon="arrow-up-right-from-square" size={12} />](https://frankieone.atlassian.net/wiki/spaces/TEC/pages/1343160385/OneSDK+Biometrics#Events).
</Callout>