Serving Assets And CORS

Target SDK Version: 3.1+

Some customers require requests to be routed through a particular domain, or self-host assets for their own reasons.

From version 3.1 we default to serving from cdn.iproov.app and JSDelivr, but now we ship all external assets inside the npm package.

This gives the following options:

Service Method	Hostnames	Benefits
Service from cdn.iproov.app	cdn.iproov.app	Configuration-free with no further infrastructure setup required.
Self-hosting with a custom assets_url	Your app's hostname? Any domain you control!	You maintain full control of asset service, DNS, and CDN configuration. Serve from your app's own hostname.

This supports quick script tag proof-of-concepts with a highly available set of CDNs, but also gives the option to self-host for your production configuration should you want to.

See below for the functionality versus support:

Integration Method	Asset Service Method	Supported
Script Tag	cdn.iproov.app	✔️
Script Tag	Self-hosting	❌
NPM	cdn.iproov.app	✔️
NPM	Self-hosting	✔️

Hosting iProov Web SDK Assets

All assets are contained inside the iproov-assets/ directory. Below is an example webroot directory structure for the domain web.demo.iproov.com. For the purpose of illustration this doesn't assume any specific web server software.

web.demo.iproov.com/         <- an example domain
  iproov-assets/             <- root directory iproov-assets will always be the same
    3.1.0.alpha.0/           <- directory name always be the published version
      bin/                   <- binary and WASM files
      css/
      fonts/
      workers/               <- JS worker files
        blazeface.worker.js
        webm.worker.js

All assets are namespaced by their package, meaning you can host multiple versions of iProov Web without naming or content clashes between versions. Internally, the SDK will request all external assets with a prefix of iproov-assets/<RELEASE>/<FILE>.

To finish illustrating the above example for the given hostname web.demo.iproov.com, self-hosting iProov Web resources would mean the above directory structure was in place, and the assets_url configuration would be as below:

<iproov-me assets_url="https://web.demo.iproov.com/" />

All requests made would be relative to https://web.demo.iproov.com/, and the SDK would automatically know which directory to search in as it always prepends iproov-assets/<VERSION> to the dependency.

Content Types

The Web SDK needs to load WebAssembly files, JavaScript worker files, various Tensorflow support resources, CSS styles and various fonts to function correctly.

As a consumer of the Web SDK, if you choose to serve these assets via your own web server or reverse proxy, you must ensure the correct Content-Type and CORS headers are set.

File Type	Extension	Required Content-Type	Compressable?
Binary	.bin	application/octet-stream	✔️
WASM (Binary)	.wasm	application/wasm	✔️
Stylesheet	.css	text/css	✔️
OpenType Fonts	.eot	application/vnd.ms-fontobject	✔️
Web Open Fonts	.woff	application/font-woff	✔️
TrueType Fonts	.ttf	application/x-font-truetype	✔️
Fonts	.svg	image/svg+xml	✔️
JavaScript workers	.worker.js	application/javascript	✔️

CORS

With the exception of the transaction metadata endpoint, the static Web SDK assets do not interact with CORS, because only "simple" requests are made, i.e. GET, no credentials, no request payload.

Our recommendation is that you do not set, add, update or remove any CORS headers for any endpoint that the Web SDK directly interacts with, including the metadata endpoint. Any headers from the iProov API, CDN, or your own service location that serves up assets should be transparently passed through. The metadata endpoint that is called before a transaction requires a preflight check, and the platform responds with specific CORS headers to avoid insecure blanket configurations, such as setting the ACAO header to * for all requests.

If your server configuration deviates from this, it may result in misconfiguration that prevents the Web SDK from working properly. It may be the case that there is an overly permissive configuration that applies to both your application's assets as well as any reverse proxy configuration. If you suspect this is the case, please get in touch with us at support@iproov.com and we can help - we love talking about CORS!

Read more about CORS here: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

Compression

If you serve these files yourself, it's possible and highly recommended to switch on GZip compression.

Common errors

Below are some common errors you'd expect to see in the console as a result of misconfiguration:

• WebAssembly headers are incorrect or content is corrupt: WebAssembly.instantiate(): expected magic word
• WebAssembly headers are incorrect: Failed to execute 'compile' on 'WebAssembly': Incorrect response MIME type. Expected 'application/wasm'., falling back to ArrayBuffer instantiation.

If everything is correctly configured, no such errors should occur in the console and you will be able to run an iProov transaction end to end.