SDK Integration

You can add MetaMap products by adding the MetaMap web button to your website, or by adding a link.

Watch our video to better understand how to configure your dashboard, use our button, and how to interpret our Webhook callbacks. This process is broadly applicable to all our SDKs.

Adding the MetaMap Web Button

The MetaMap Web SDK is a pre-built UX that can be integrated within seconds into any website, optimized for desktop and mobile, with just a few lines of code:

📘
MetaMap Parameter Names
metamap-button and mati-button can be used interchangeably in source.
There are no plans to deprecate mati-button or mati parameters.

<script src="https://web-button.mati.io/button.js"></script>
 <metamap-button
  clientId="YOUR_CLIENT_ID" // from your Metamap dashboard
  flowId="YOUR_FLOW_ID" // from your Metamap dashboard
  color="#505DED" // to setup main color of buttons in your metamap
  textcolor="#FFFFFF" // to setup text color of buttons in your metamap
  metadata='{"user_id":"1234778", "fixedLanguage":"es"}' // custom data 
 />

📘
Custom Color
The color parameter supports the following options:

blue

green

red

pink

orange

yellow

Specific color in HEX format (for example #505DED,
)

Metadata

Note that you should pass a metadata string as previously shown so you know which user is being verified. This metadata string is a JSON object that will be sent in all our Webhook callbacks for that specific verification. As it is a custom JSON object you can define the tags and values that you need.

In your metadata strings you can pass:

email
fixedLanguage: You can fix the selected language and hide user language selection: use the locale code for the language value (for example, es for Spanish)

For any other information you want to send as metadata, feel free to use any characters 0-9, A-Z, a-z.

Callback events

The following javascript events can be used to take control (show a message, hide the button, redirect the user, etc) when the user has left or completed the metamap.

const button = document.getElementById("metamap-button");

// setup callbacks
button.addEventListener('mati:loaded', ({ detail }) => {
  console.log('loaded payload', detail)
});
button.addEventListener('mati:userStartedSdk', ({ detail }) => {
  console.log('started payload', detail)
});
button.addEventListener('mati:userFinishedSdk', ({ detail }) => {
  console.log('finished payload', detail)
});
button.addEventListener('mati:exitedSdk', ({ detail }) => {
  console.log('exited payload', detail)
});

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Test MetaMap button</title>
  <script src="https://web-button.getmati.com/button.js"></script>
</head>
<body>
  <h1>Demo:</h1>
  <div>
    <h2>Latest</h2>
    <metamap-button></metamap-button>
  </div>
  <div>
    <h2>Legacy</h2>
    <mati-button></mati-button>
  </div>
  <script type="text/javascript">
    const query = new URLSearchParams(location.search);
    const latest = document.querySelector('metamap-button');
    const legacy = document.querySelector('mati-button');

    // setup attributes
    latest.setAttribute("clientid", query.get("merchantToken"));
    latest.setAttribute("flowid", query.get("flowId"));
    latest.setAttribute("identityid", query.get("identityId"));
    latest.setAttribute("configurationId", query.get("configurationId"));
    latest.setAttribute("metadata", query.get("metadata"));

    // setup callbacks
    latest.addEventListener('metamap:loaded', ({ detail }) => {
      console.log('loaded payload', detail)
    })
    latest.addEventListener('metamap:userStartedSdk', ({ detail }) => {
      console.log('started payload', detail)
    })
    latest.addEventListener('metamap:userFinishedSdk', ({ detail }) => {
      console.log('finished payload', detail)
    })
    latest.addEventListener('metamap:exitedSdk', ({ detail }) => {
      console.log('exited payload', detail)
    })


    // setup attributes
    legacy.setAttribute("clientid", query.get("merchantToken"));
    legacy.setAttribute("flowid", query.get("flowId"));
    legacy.setAttribute("identityid", query.get("identityId"));
    legacy.setAttribute("configurationId", query.get("configurationId"));
    legacy.setAttribute("metadata", query.get("metadata"));

    // setup callbacks
    legacy.addEventListener('mati:loaded', ({ detail }) => {
      console.log('loaded payload', detail)
    })
    legacy.addEventListener('mati:userStartedSdk', ({ detail }) => {
      console.log('started payload', detail)
    })
    legacy.addEventListener('mati:userFinishedSdk', ({ detail }) => {
      console.log('finished payload', detail)
    })
    legacy.addEventListener('mati:exitedSdk', ({ detail }) => {
      console.log('exited payload', detail)
    })

  </script>
</body>
</html>

Direct Link

You can also send a verification direct link to your users through email or the messaging app you prefer, no website needed!

For example:

https://signup.getmati.com/?merchantToken=<YOUR_CLIENT_ID>&flowId=<YOUR_FLOW_ID>&metadata={"fixedLanguage":"es","email":"[email protected]","Client":"id3452"}

There are also a couple of parameters that you can add to the Direct Link to redirect the final user once they're finished with their verification process.

Opens new tab with url set in redirect parameter of the link:

https://signup.getmati.com/?merchantToken=<YOUR_CLIENT_ID>&flowId=<YOUR_FLOW_ID>&redirect=<YOUR_URL>

Opens url set in redirect parameter of the link with appropriate target set in target parameter of url (_self → same tab, _blank → new tab):

https://signup.getmati.com/?merchantToken=<YOUR_CLIENT_ID>&flowId=<YOUR_FLOW_ID>&redirect=<YOUR_URL>&target=<YOUR_TARGET>

Acceptable values for target: _blank, _self, _top, _parent

Overall, these are the accepted additional GET parameters for the Direct Link:

&metadata={"fixedLanguage":"es","user_id":"001"} - Any key-value pair in a JSON format, up to 14 kb of information. With the direct link, the key "fixedLanguage" in the metadata, will set the experience default language to the one you set in the value following the ISO 639-1 abbreviation standard.
&color=000000 - Any hexadecimal value for the color of the buttons inside MetaMap's UI.
&textColor=FFFFFF - Any hexadecimal value for the color of the text inside MetaMap's UI.
&redirect=<YOUR_URL>&target=<YOUR_TARGET> - A URL and a target value to redirect the user once they're finished with their process.

Examples

The MetaMap Web SDK is compatible with different frameworks.

JavaScript
Angular
React
Vue

You can download and run the examples as per our Web Application Examples page, or you can test the examples we have available in CodeSandbox.

Web SDK Compatibility

The MetaMap Web SDK is compatible with most browsers with TLS version 1.2+, whether on desktop or mobile platforms. Further compatibility issues stem from differences in Java versions.

To integrate our SDK into your mobile app, we highly recommend using our native Mobile SDKs for a seamless experience, since we can't assure the same experience when implementing the WebSDK via WebView, as it depends on how it is implemented on your platform.

The following table lists known browser compatibility. Compatibility is divided across 4 subjects:

Desktop (Liveness+Document Upload) — Can the Web SDK access the camera and microphone and can upload documents from the desktop browser
Desktop (Document Upload) — Can the Web SDK upload documents from the desktop browser
Desktop (Dashboard, MetaMap Builder) — Can the Web SDK access the MetaMap Dashboard and use the MetaMap Builder
Mobile — Can the Web SDK be used on the mobile browser

The compatibility is given one of the following classifications:

Supported
— The SDK functions as intended
Unsupported
— The SDK may work only in a limited capacity, such as only some checks work, not access to camera, or the layout formatting is incorrect
Failed
— The SDK fails to load or crashes
NA — Not applicable; the browser cannot be installed

Browser	Version	Desktop (Liveness+Document Upload)	Desktop (Document Upload)	Desktop (Dashboard, Metamap Builder)	Mobile Platform
Microsoft Internet Explorer	≤10	Unsupported	Failed	Failed	NA
Microsoft Internet Explorer	≥11	Unsupported	Unsupported : formatting is incorrect	Failed	Supported
Microsoft Edge	Any	Supported	Supported	Supported	Supported
Mozilla Firefox	21	Failed	Failed	Failed	NA
	22-28	Unsupported	Unsupported : formatting is incorrect	Failed	NA
	90	Supported	Supported	Supported	Supported
Google Chrome	≤22	Failed	Failed	Failed	Failed
	23	Unsupported	Unsupported : formatting is incorrect	Failed	NA
	37-39	Unsupported	Unsupported : formatting is incorrect	Unsupported : Metamap builder crashes	NA
	92	Supported	Supported	Supported	Supported
Android, Default Browser	≤4.4.4 (Jellybean)	NA	NA	NA	Unsupported : No access to camera for biometric verification
Android, Default Browser	≥5.5 (Lollipop)	NA	NA	NA	Supported
iOS	iOS version: ≤4 Safari version: any	NA	NA	NA	Failed
	iOS version: ≥5 Safari version: ≥5	NA	NA	NA	Supported
	iOS version: ≥6 Safari version: ≥6 Chrome version ≥92	NA	NA	NA	Supported
MacOS Safari Browser	OS X version: ≤10.8 Safari version ≤6	Failed	Failed	Failed	NA
	OS X version: ≥10.9 Safari version 7.1	Unsupported	Unsupported : formatting is incorrect	Failed	NA
	OS X version: ≥10.9 Safari version 10.1	Unsupported	Supported	Unsupported : Metamap Builder crashes	NA
	OS X version: ≥10.9 Safari version ≥13.1	Unsupported	Supported	Supported	NA
Windows Phone	Windows Phone version: ≤8.1 IE version ≤11 Chrome version: ≥92	NA	NA	NA	Supported
Windows Phone	Windows Phone version: ≤11 v1151, v1607, v1703, v1709 IE version ≤11 Chrome version: ≥92	NA	NA	NA	Supported