Skip to main content

Face Match Verification via IFrame Integration

This documentation outlines how to integrate the Face Match process into your website using an embedded IFrame. It covers the session initialization, IFrame embedding with query parameters, and handling the verification result via postMessage.

1. Initialize a Face Match Session​

Your client application must start a Face Match session by making a POST request to the API endpoint:

POST https://authenticalls.com/kyc/client/api/face-match/start
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>

Request Payload (JSON):

Refer to the Start Face Match Session documentation for the complete payload schema. The payload must include a referenceImage field containing a base64‑encoded image against which subsequent images will be compared.

Response (JSON):

{
  "sessionId": "<SESSION_ID>"
}

2. Embed the IFrame​

Once you receive the sessionId, display the IFrame and set its src to the Face Match application URL:

<iframe
  id="faceMatchFrame"
  allow="camera; microphone"
  style="max-width: 639px; min-height: 600px;"
></iframe>

The iframe's maximum suggested width is 639px and minimum height 600px.

Responsive styling for mobile

To ensure the IFrame occupies the full screen on mobile devices, add the following CSS:

/* Desktop default */
#iframe {
  max-width: 639px;
  min-height: 600px;
}

/* Mobile full‑screen */
@media (max-width: 768px) {
  #faceMatchFrame {
    width: 100vw !important;
    height: 100svh !important;
    max-width: none;
    border: none;
    position: fixed;
    top: 0;
    left: 0;
    z-index: 9999;
  }
}
// After obtaining sessionId:
const integratorOrigin = location.origin;
document.getElementById("faceMatchFrame").src =
  `https://authenticalls.com/kyc/client/app/intro` +
  `?sessionId=${sessionId}` +
  `&iframe` +
  `&integrator=${integratorOrigin}`;

Query Parameters

  • sessionId (required): The unique session identifier returned by the API.
  • iframe (flag): When present, instructs the Face Match app to render in IFrame mode.
  • integrator (required, if iframe is also present): The URL origin of your website (URL‑encoded). Used to instruct the iframe to send the final result message.

3. Handling the Face Match Result with postMessage​

When the Face Match process completes, the IFrame will send a message to the parent window.

Note: The IFrame will take approximately 1 extra second to finish internal processing after the result is ready. You may use this time to hide the iframe and handle the response yourself. (Otherwise, the Iframe will display the result).

window.addEventListener("message", (event) => {
  // 1. Validate the message origin
  if (event.origin !== "https://authenticalls.com") return;

  // 2. Process only face‑match finished events
  if (event.data.type === "face_match_finished") {
    const resultPayload = event.data.payload;
    console.log("Face Match finished:", resultPayload);

    // Immediately hide the iframe to avoid flicker
    document.getElementById("faceMatchFrame").style.display = "none";

    // Your custom logic (e.g., navigate, display results)
    alert("Face Match result ready!");
  }
});

The type of event.data.payload is the same as the return type of Process Face Match Session Data.

Important Notes

  • Origin Check: Always verify event.origin to ensure messages come from https://authenticalls.com.
  • type Field: Only messages with type === 'face_match_finished' indicate completion.
  • Flicker Prevention: Hide the IFrame as soon as the message is received; the IFrame will continue internal cleanup for about 1 second after sending the result.

Full Integration Flow​

  1. User initiates the Face Match process on your site.
  2. Your client code calls /face-match/start with a referenceImage and retrieves sessionId.
  3. Show the IFrame container and set its src with sessionId, iframe, and integrator parameters.
  4. The user completes the Face Match steps in the embedded IFrame.
  5. The IFrame posts a face_match_finished message back to your page.
  6. Your page listens for this message, validates it, hides the IFrame immediately, and handles the result accordingly.

With this setup, you can seamlessly embed the Face Match workflow into your website, leveraging camera and microphone permissions directly within an IFrame, and safely receive the results via postMessage.