Usage

How to use the Smile ID Web Integration

Steps

1. Fetch the web token from your server, when ready

2. Configure the web integration

3. Test the Integration

Fetch the Web Token from your server

Using the Web Token endpoint set up on your server, fetch a web token for the client

This can take the form of a click event on your web site or application.

const baseAPIURL = `${your - API - server - URL}`;

const getWebToken = async (baseAPIURL) => {
  const fetchConfig = {};

  fetchConfig.cache = "no-cache";
  fetchConfig.mode = "cors";
  fetchConfig.headers = {
    Accept: "application/json",
    "Content-Type": "application/json",
  };
  fetchConfig.method = "POST";

  const URL = `${baseAPIURL}/token/`;
  try {
    const response = await fetch(URL, fetchConfig);

    if (response.status === 200 || response.statusCode === 200) {
      const json = await response.json();

      if (json.error) {
        throw new Error(json.error);
      }

      return json;
    }
  } catch (e) {
    console.log(`API: ${e.name}, ${e.message}`);
    throw e;
  }
};

const verifyWithSmileIdentityButton = document.querySelector(
  "#verify-with-smile-id",
);

verifyWithSmileIdentityButton.addEventListener(
  "click",
  async (e) => {
    e.preventDefault();

    verifyWithSmileIdentityButton.textContent = "Initializing session...";
    verifyWithSmileIdentityButton.disabled = true;

    const { token } = await getWebToken(baseAPIURL);
  },
  false,
);

Configure the Web Integration

With the web token, we can now configure our integration

const configureSmileIdentityWebIntegration = (token) => {
  SmileIdentity({
    token,
    product: "biometric_kyc",
    callback_url: `${your - API - server - URL}/callback`,
    environment: "sandbox",
    partner_details: {
      partner_id: `${your - smile - identity - partner - id}`,
      name: `${your - app - name}`,
      logo_url: `${your - app - logo - url}`,
      policy_url: `${your - data - privacy - policy - url}`,
      theme_color: "#000",
    },
    partner_params:{
        "sample_meta_data": "meta-data-value", //include meta data
        "sandbox_result" : "0" //mock sandbox result
    }, 
    onSuccess: () => {},
    onClose: () => {},
    onError: () => {},
  });
};

// ACTION: call the initialization function in the event handler
verifyWithSmileIdentityButton.addEventListener(
  "click",
  async (e) => {
    e.preventDefault();

    verifyWithSmileIdentityButton.textContent = "Initializing session...";
    verifyWithSmileIdentityButton.disabled = true;

    try {
      const { token } = await getWebToken(baseAPIURL);
      configureSmileIdentityWebIntegration(token);
    } catch (e) {
      throw e;
    }
  },
  false,
);

The API for configuring the integration is as follows

Key	Type	Required	Description
token	string	Yes	token generated on the server side using the get_web_token method in one of our server-to-server libraries
product	string	Yes	one of the Smile ID products. "biometric_kyc" "doc_verification "authentication" "basic_kyc" "smartselfie" "enhanced_kyc" "enhanced_document_verification" "e_signature"
document_ids	array	Yes (for e_signature)	a list of previously uploaded document IDs
callback_url	string	Yes	a callback URL on your API server or wherever you prefer.
environment	string	Yes	one of "sandbox" or "live"
partner_details	object	Yes	customizations for your organization. details here
partner_params	object	No	a collection of partner additional information. All its contents are sent back to the partner but in a slightly different format. The objects key name is changed to PartnerParams. It can be used to hold meta data related to the user or the job. Additionally, if you intend to mock the sandbox results, you should include the include the sandbox_result key as string value "0", "1" or "2"
onSuccess	function	No	function to handle successful completion of the verification.
onError*	function	No	function to handle errors with verification, called when end-user consent is denied
onClose	function	No	function to handle closing of the verification process
id_selection**	object	No	a mapping of country code to a selection of supported id types e.g. { "NG": ["BVN_MFA", "V_NIN"] }
consent_required ***	object	Yes, for ID Types where user consent is required.	a mapping of country code to a selection of supported id types e.g. { "NG": ["BVN", "NIN"] }
document_capture_modes	array	No	list containing camera or upload or both defaults to camera
allow_agent_mode	boolean	No	Whether to allow Agent Mode or not. If allowed, a button will be displayed allowing toggling between the back camera and front camera. If not allowed, only the front camera will be used. To use agent mode, the new design should be opted for by setting use_new_component: true

* - onError function can take one argument of the shape { message: <message>, data: <object with details> }

** - id_selection list is checked against those enabled for your partner account. this is limited in cases of basic_kyc, enhanced_kyc, enhanced_document_verification, and biometric_kyc.

If you pass only one country and id type in theid_selection object, the id type selection screen will not be displayed in the web integration instance

*** - consent_required list is subject to the ID Authority configuration. Some ID Authorities require end-user consent, and that requirement overrides this setting.

partner_details configuration reference

Key	Type	Required	Description
name	string	Yes	Application Name
partner_id	string	Yes	Smile ID Partner ID
policy_url	string	Yes	URL to data privacy policy
logo_url	string	Yes	URL to App Logo (best in 1:1 aspect ratio)
theme_color	string	No	a valid CSS Color Code for accent colors. When specified with the use_new_component: true, the color will be applied to header texts and buttons. Refer to theme color

Test the Integration

After configuring the integration, you can walk through an example.

Theme Color

Color theming

Camera not loading

Please see the trouble shooting guide here for situations where the camera is not loading.