Run address

Whenever you use device-to-device or verification links, you are directing your users to a URL which holds a web app where they will go through the workflow that you have set up.

We call this URL a "run address", since a user will run the workflow there, and not on the primary device.

For device-to-device flows, you can choose to:

• host this secondary web app yourself, or
• use our managed web app (https://platform.microblink.com/run).

There are benefits and drawbacks to both deployments, and we go through some of the trade-offs below.

Overall, we recommend that you self-host.

For verification links, you must not use our managed app in production. The reason for this is that our managed app overwrites your users' consent.

In short, your deployment options are:

Use case	Self-hosted app	Managed app
D2D	✅	✅ (but not recommended)
Verification links	✅	❌

Trade-offs

Versioning

If you use the managed app, the first and probably the most important issue that you may encounter is a version mismatch.

Our managed secondary app is kept up-to-date with the latest SDK releases. If you are running, for example, version 1.4 on your primary web app, and we are running version 1.6 on the secondary web app, then you have a situation where a user is being transferred from version 1.4 to version 1.6 within the same workflow.

Our SDKs are designed to be backwards-compatible with workflows preceding their versions. So, a web SDK v1.6 will be able to run a workflow designed with v1.4 in mind. However, changing the version by definition introduces complexity, which is something that you may not want.

Moreover, this complexity isn't just theoretical. From version to version, we update our own dependencies. One such dependency is BlinkID, which powers the Scan ID capability. This means that you can experience different results depending on whether you use your own self-hosted app, or our managed app, while the workflow is the same.

This could, for example, cause issues with debugging in device-to-device (D2D) mode. If you have a cluster of users A, who use only their primary device (no device-to-device handoff), and you also have a cluster of users B, who use our managed app as the secondary device, these two clusters could see different results while scanning the same document class.

Normally, this shouldn't be an issue, as the latest BlinkID versions (as well as other dependencies) bring in more capability (more documents supported, better recognition mechanisms, etc.). So in many cases, you might expect that users have a better experience using our managed app. However, if there are any issues, debugging is much more difficult, as you only have visibility in cluster A, while cluster B uses a completely different dependency version that you don't control.

So, the trade-off here is: with self-hosting, you control exactly which versions your users are running, even in a device-to-device or verification link scenario. But, you lose out on the latest update; that is, you yourself must make sure that your "run address" app is kept up-to-date.

Control

The second point is around control.

Since the "run address" app isn't managed by you, you cannot control how and when it is deployed, with which dependencies, and more.

We take great care not to break anything whenever we perform our updates, but this is also a risk that you should assess and factor in your decision.

The trade-off here is that by self-hosting, you have more predictable environments, but you also do more work.

Location

Location is another consideration.

Our managed app runs in a US data center. If your user base is elsewhere, and you're trying to reduce network hops for latency reasons, or you have strict policy related to where your users' data resides, then self-hosting may be a better option.

Customization

Any customizations around what happens during the scan are completely outside of your control if you use our managed app.

However, if you have no customizations (no custom events, for example), and only need to use the default setup, you can reduce the complexity of your deployment if you use our managed app.

How to self-host?

The general steps are:

1. Set up a JavaScript project.
2. Install the Microblink Platform web SDK (npm i @microblink/platform-sdk).
3. Create logic to handle incoming requests.
4. Create logic that parses the incoming requests and dynamically configures your web app based on the incoming request.
5. Create logic to run the verification flows.
6. Deploy this app somewhere.

In device-to-device flows

We provide a complete example D2D server implementation here.

A minimal example in JavaScript:

import { createIdvFlow } from "@microblink/platform-sdk/vanilla";

const urlSearchParams = new URLSearchParams(window.location.search);
const data = urlSearchParams.get("sdk");
const jsonString = atob(data);
const result = JSON.parse(jsonString);

createIdvFlow({
  mode: "d2d",
  apiConfig: {
    apiUrl: result.apiAddress,
    transactionId: result.transactionId,
    ephemeralKey: result.ephemeralKey,
    d2d: { joinKey: result.deviceJoinKey },
  },
});

You should parse incoming requests, and read their sdk query parameter. That parameter will contain base64-encoded data. This data is a JSON object that contains data about the transaction.

Your main app should take in the data from this object, and pass it to the configuration object for the creation (or continuation) of the identity verification flow.

For the secondary (D2D) web app, the mode should be set to "d2d". We explain the full configuration in D2D SDK documentation.

In verification links

import { createIdvFlow } from "@microblink/platform-sdk/vanilla";

const urlSearchParams = new URLSearchParams(window.location.search);
const data = urlSearchParams.get("sdk");
const jsonString = atob(data);
const result = JSON.parse(jsonString);

createIdvFlow({
  mode: "classic",
  apiConfig: {
    apiUrl: result.apiAddress,
    transactionId: result.transactionId,
    ephemeralKey: result.ephemeralKey,
    d2d: { joinKey: result.deviceJoinKey },
  },
  consentData: {
    userId: 'unique-user-id',
    note: '',
    givenOn: new Date().toISOString(),
    isTrainingAllowed: true,
    isProcessingStoringAllowed: true,
  }
});

Note that you need to implement your own logic how user IDs are provided to the consentData object.

User IDs should be unique per user, and their consent (isProcessingStoringAllowed) needs to reflect the preferences of the end user (true means that they accept their personal data being scanned).

As with D2D, you need to parse incoming requests, and read their sdk query parameter. That parameter will contain the same type of base64-encoded data as in D2D flows; a JSON object that contains data about the transaction.

For the verification link app, the mode should be set to "classic".

How to use the managed app?

If you've decided to use our managed app, the runAddress is https://platform.microblink.com/run.

In device-to-device flows

Configure your primary web app like so:

{
  enableD2D: true,
  mode: "classic",
  apiConfig: {
    d2d: { runAddress: 'https://platform.microblink.com/run' }, 
  // rest of the configuration...

A better practice is to hold the run address in an environment variable, and then pass that as the value to the runAddress parameter, for example:

runAddress: import.meta.env.D2D_RUN_ADDRESS

In verification links

Not supported.

Our managed app creates a consent object which overwrites the consent you may have provided previously.