@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
150 lines (107 loc) • 6.7 kB
Markdown
# Genius Scan SDK for the Web
## Description
The Genius Scan SDK for the Web enables you to integrate the document scanning experience that powers the [Genius Scan app](tglapp.com/scan) in your web app.
It offers a component enabling you to implement the [Genius Scan SDK](https://geniusscansdk.com) Scan Flow, an all-in-one configurable scanner module with the following key features:
- Automatic document detection
- Document perspective correction
- Image enhancement filters with 4 different modes (Black & white, Monochrome, Color, Photo)
- Batch scanning of several pages in row
Some of the features of the native SDK, such as OCR and PDF generation, are not available currently in the Web SDK.
## License
You can try the "demo" version for free without a license key, the only limitation being that the app will need reloading after 60 seconds.
You need to [set a license key](#set-the-license-key) for unlimited demo time, or for production.
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`
You can learn more about [licensing](https://geniusscansdk.com/license/licensing) in our website and contact us at sdk@geniusscan.com for further questions.
## Demo application
As an example, you can check the [demo web application](https://demo.geniusscansdk.com)
The demo's source code is available at https://github.com/thegrizzlylabs/geniusscan-sdk-demo/tree/master/web-demo.
## Usage
### 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';`
**Note:** If you're using the script tag approach with a CDN, make sure to include the appropriate CDN domain in your `script-src` directive (e.g., `https://cdn.jsdelivr.net`).
### Set the license key
Initialize the SDK with a valid license key:
```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);
});
```
Note that, for testing purpose, you can also use the plugin without setting a license key, but it will only work for 60 seconds.
### Start the scanner module
This short guide will walk you through the steps to add a scan workflow to your existing web application.
1. Add `/web-geniusscan-sdk` to your project:
```sh
npm install --save /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}`);
}
});
```
### Alternative: loading the library as a script tag
You can also use the Genius Scan SDK directly in the browser without a build step by including it as a script tag:
```html
<script src="https://cdn.jsdelivr.net/npm/@thegrizzlylabs/web-geniusscan-sdk@latest/dist/geniusscan-sdk.iife.js"></script>
```
**Note:** For production use, we recommend using a fixed version number instead of `` to ensure consistent behavior and avoid unexpected breaking changes. For example: `/web-geniusscan-sdk@5.12.0`.
When using the script tag, the SDK is available globally as `GSSDK` and provides the same API as the module version.
## 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-CN", "zh-TW"`. Default value is `"en"`