@thegrizzlylabs/web-geniusscan-sdk
Version:
Add a custom document scanner to your web apps by using and customizing our proven imaging technology. The Document Scanner SDK is the same software that we use at the core of Genius Scan: it's tried and trusted every day by millions of people on iOS and
100 lines (77 loc) • 4.48 kB
Markdown
# Genius Scan Web SDK
## Prerequisite
### Content Security Policy
If your page uses Content Security Policy (CSP), you will need the following exceptions so that the Genius Scan SDK can install itself on the page:
- `connect-src 'self' data:;`
- `worker-src 'self' blob:;`
- `script-src 'self' 'unsafe-eval';`
- `style-src 'self' 'unsafe-inline';`
### License
This plugin is based on the Genius Scan SDK for which you need to set up a license. You can already try the "demo" version for free by not setting a license key, the only limitation being that the app will exit after 60 seconds.
To buy a license:
1. [Sign up](https://sdk.geniusscan.com/apps) to our developer console.
2. Submit a quote request for each application, using your application hostname as an App ID. For example, if you are hosting your application on "https://app.mydomain.com", you will need to register a license for `app.mydomain.com`
3. Initialize the SDK with your _license key_, see example below.
You can learn more about licensing on our website and contact us at sdk@geniusscan.com for further questions.
## Getting started
This short guide will walk you through the steps to add a scan workflow to your existing web application.
1. Add `@thegrizzlylabs/web-geniusscan-sdk` to your project:
```sh
npm install --save @thegrizzlylabs/web-geniusscan-sdk
```
2. Import the library, set the license key and run the scan workflow. This is a simple vanilla JS example:
```html
<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Genius Scan SDK example</title>
<script src="index.js" type="module"></script>
</head>
<body>
<h1>Genius Scan SDK: web example</h1>
<div id="container">
<button id="scan">Scan a document</button>
</div>
</body>
</html>
```
```javascript
// index.js
import { setLicenseKey, scanDocument } from "@thegrizzlylabs/web-geniusscan-sdk";
const LICENSE_KEY_FOR_YOUR_DOMAIN = "xxxxxx";
setLicenseKey(LICENSE_KEY_FOR_YOUR_DOMAIN).catch((e) => {
console.error(`Error setting Genius Scan SDK license key`, e);
});
const scanButton = document.getElementById("scan");
const container = document.getElementById("container");
scanButton.addEventListener("click", async () => {
try {
const jpegImages = await scanDocument({ highlightColor: "orange" });
for (const jpeg of jpegImages) {
const img = document.createElement("img");
const url = URL.createObjectURL(jpeg);
img.src = url;
img.onload = () => {
URL.revokeObjectURL(url);
};
container.appendChild(img);
}
} catch (error) {
console.error(error);
alert(`Error scanning document: ${error.message}`);
}
});
```
## Scan Configuration
The method `scanDocument()` accepts an optional `configuration` object as parameter which can take the following attributes:
- `multiPage`: boolean (defaults to true). If true, after a page is scanned, a prompt to scan another page will be displayed. If false, a single page will be scanned.
- `defaultFilter`: the filter that will be applied by default to enhance scans, or `"none"` if no enhancement should be performed by default. Possible values are listed in `availableFilters`. Default value is `"automatic"`.
- `availableFilters`: an array of filters that the user can select when they tap on the edit filter button. Defaults to `["automatic", "strong_monochrome", "soft_grayscale", "soft_color", "strong_grayscale", "strong_color", "photo", "dark_background", "none"]`.
- `jpegQuality`: JPEG quality used to compress captured images. Between 0 and 100, 100 being the best quality. Default is 60.
- `postProcessingActions`: an array with the desired actions to display during the post-processing screen (defaults to all actions). Possible actions are `rotate`, `editFilter`, and `correctDistortion`.
- `foregroundColor`: string representing a color, must start with a `#`. The color of the icons and text (defaults to '#ffffff').
- `backgroundColor`: string representing a color, must start with a `#`. The color of the toolbar and screen background (defaults to black).
- `highlightColor`: string representing a color, must start with a `#`. The color of the image overlays (defaults to blue).
- `language`: change the scan flow localization. Possible values are `"en", "ar", "da", "de", "es", "fr", "hu", "in", "it", "iw", "ja", "ko", "nl", "pl", "pt", "ru", "sv", "tr", "vi", "zh-rCN", "zh-rTW"`. Default value is `"en"`