The following flow diagram describes all the steps needed to complete this integration.

Step 1: Create a new endpoint in your Backend

This endpoint is meant to Create a Session and Generate the onboarding URL, make it available to your Frontend app.

📘

Using Static URL

You might decide to skip creating the session and generating the url in backend if you don't plan to associate any information about your user during /omni/start, in that case take a look at how to Copy Onboarding URL from the Dashboard and completely skip step 1.

Step 1.1: Create the Session

You can see all the details about creating a session using the api in Create Session, but the gist is that you need to call /omni/start, to retrieve interviewIdand token.

const params = {
  configurationId: <<flowId>,
  countryCode: "ALL",
  language: "en-US",
  //externalCustomerId: "someuser0001", //The Id if the user in your system
  //redirectionUrl: "https://example.com/", //The url where the user will be redirected at the end of the onboarding
};

const headers = {
  accept: 'application/json',
  'Content-Type': 'application/json',
  'x-api-key': '<<APIKEY>>',
  'api-version': '1.0'
};

const options = {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(params)
};

const response = await fetch('{user.DEMO_URL}omni/start', options);

const {token, interviewId} = response.json();

/**
/* Save the token and the interviewId to your database, 
/* you will need it later to retrieve the results and poll for status.
**/
saveToken({token, interviewId});

curl --location '{user.DEMO_URL}omni/start' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-version: 1.0' \
--header 'x-api-key: <<APIKEY>>' \
--data '{
	"countryCode": "ALL",
    "configurationId": "65283accd410a1dd7e965479",
    "externalCustomerId": "someuser0001",
    "redirectionUrl": "http://example.com/"
}'

Step 1.2: Save the token and interviewId

Save the session tokenand the interviewIdto your database associated to your user, you will need this information later to review the session in the dashboard and to retrieve the scores, OCR data and images via API.

Step 1.3: Generate Onboarding URL

You can see all the details about generating an onboarding URL using the api in Generate Onboarding URL, but the gist is that you need to call /omni/onboarding-url with the session token, to retrieve theurl.

const headers = {
  accept: 'application/json',
  'Content-Type': 'application/json',
  'api-version': '1.0',
  'X-Incode-Hardware-Id': '<<TOKEN>>'
};

const options = {
  method: 'GET',
  headers: headers,
};

const response = await fetch('{user.DEMO_URL}0/omni/onboarding-url', options);

const {url} = response.json();

/**
/* Return url and interviewId
**/

curl --location '{user.DEMO_URL}0/omni/onboarding-url' \
--header 'Content-Type: application/json' \
--header 'api-version: 1.0' \
--header 'X-Incode-Hardware-Id: <<TOKEN>>' \

📘

Zero configuration endpoints

You will notice that the url in this step has a/0, this endpoints only need the Session Token to work, all endpoints that refer to an specific interviewId support the /0and are able to get all information needed to work out of the Session Token.

You will use more of this endpoints later to retrieve the scores, OCR data and images via API.

Step 1.4: Return the values

Now just return the url and the interviewId to the frontend.

Step 2: Create an Iframe with the URL in the Frontend

Now on your frontend call the endpoint you created before, it should return the url and the interviewId.

To work correctly, the Iframe created needs to comply with several conditions: set it to 100% and allow the usage of geolocation, microphone, and camera. Also, for our onboarding functionality process, a gyroscope and accelerometer are needed for features with motion, orientation, and gesture-based interactions.

Set its URL, and the user can do their onboarding.

const createIframe = (url) => {
  /* Get the container where we are going to insert the iframe */
  const app = document.getElementById('app'); //reference to a element on index.html page
  
  /* Create the iframe */
  const frame = document.createElement('iframe');
  /* Set the URL */
  frame.src = url;
  frame.id = 'app-iframe'
  frame.width = '100%';
  frame.height = '100%';
  /* Allow the iframe to use the camera and other media */
  frame.allowUserMedia = true;
  frame.setAttribute('frameborder', '0');
  /* Allow specific permissions. Notice the wildcard character (*) */
  frame.setAttribute('allow', 'geolocation *; microphone *; camera *; accelerometer *; gyroscope *;');
  /* Insert iframe into container */
  app.appendChild(frame);
}

const response = await fetch(`https://you.backend.app/create-session-and-onboarding-url`, {});
const { interviewId, url } = await response.json();

createIframe(url);

Step 3: Create and endpoint in your backend to retrieve the onboarding status

/** Retrieve the token from your database, implementation details are up to you **/
const token = getToken(interviewId);

const headers = {
  accept: 'application/json',
  'Content-Type': 'application/json',
  'api-version': '1.0',
  'X-Incode-Hardware-Id': '<<TOKEN>>'
};

const options = {
  method: 'GET',
  headers: headers,
};

const response = await fetch('{user.DEMO_URL}0/omni/get/onboarding/status', options);

const {onboardingStatus} = response.json();

/**
/* Return onboardingStatus
**/

Step 4: Call your backend to poll for the onboarding Status

There is no way to directly monitor the progress of an iframe, so instead we will poll the API for the onboarding status.

Full list can be found in Onboarding Statuses, we are waiting for the ONBOARDING_FINISHED one.

async function fetchOnboardingStatus(interviewId) {
  const response = await fetch(
    `https://you.backend.app/onboarding-status?interviewId=${interviewId}`,
  );
  const {onboardingStatus} = await response.json();
  return {onboardingStatus}
}

const interval = setInterval(async () => {
   const onboarding = await fetchOnboardingStatus(interviewId);
   
   if (onboarding.onboardingStatus==='ONBOARDING_FINISHED'){
     clearInterval(interval);
     
	 	 // Remove iframe from the parent node
     //const frame = document.getElementById('app-iframe');
     //frame.parentNode.removeChild(frame);

			// Here You are ready to fetch scores
   }
}, 1000);

Step 5: Close Iframe

Closing an Iframe might be tricky. For it to really stop, you need to do it by referencing its parent node.

// Remove iframe from the parent node
const frame = document.getElementById('app-iframe');
frame.parentNode.removeChild(frame);

Step 6: Fetch the scores

Fetching the scores happens in the backend, so let's close this step by asking the data from it, you can see exactly what the scores mean and what other things you can fetch in the next step.

// Fetch score
const response = await fetch(
	`https://you.backend.app/fetch-score=?interviewId=${interviewId}`
);
/** you control this endpoint, so you could return anything you want **/
const {status} = await response.json();
  
if(status==='OK'){
    console.log('You sucessfully onboarded');
} else {
    console.log('You didn\'t passed');
} 

6. Fetch the scores in the Backend

In your backend you should receive the interviewId, use it to retrieve the token from the database, and then Fetch Results and Data .