# 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 `@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
Genius Scan SDK example
Genius Scan SDK: web example
```
```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
```
**Note:** For production use, we recommend using a fixed version number instead of `@latest` to ensure consistent behavior and avoid unexpected breaking changes. For example: `@thegrizzlylabs/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"`