@scandit/web-barcode-link/README.md

The Scandit Web Barcode Link package

# @scandit/web-barcode-link

The Barcode Link SDK allows you to scan barcodes on your smartphone and automatically send them to a desktop device.

## Table of contents

- [Installation](#installation)
- [Usage](#usage)
- [API](#api)

## Installation

You can install the package via NPM:

```
$ npm i @scandit/web-barcode-link
```

## Usage

First, import the `BarcodeLink` class:

```ts
import { BarcodeLink } from "@scandit/web-barcode-link";
```

Then create an instance using your Scandit license key:

```ts
import { BarcodeLink } from "@scandit/web-barcode-link";

const barcodeLink = BarcodeLink.forLicenseKey("-- ENTER YOUR SCANDIT LICENSE KEY HERE --");
```

From there you have various methods that you can use to configure your barcode link instance.

For example:

```ts
import { BarcodeLink, BarcodeLinkMode } from "@scandit/web-barcode-link";

const barcodeLink = BarcodeLink.forLicenseKey('-- ENTER YOUR SCANDIT LICENSE KEY HERE --')
 .setBarcodeLinkMode(BarcodeLinkMode.SingleScanning)
 .addListener({
		onCapture(barcodes) {
			console.log('Scanned:' barcodes)
		}
 })
```

Finally you just initialize the barcode link instance with a specific flow.

For example:

```ts
import { BarcodeLink, BarcodeLinkMode, BarcodeLinkUiFlow } from "@scandit/web-barcode-link";

const barcodeLink = BarcodeLink.forLicenseKey('-- ENTER YOUR SCANDIT LICENSE KEY HERE --')
 .setBarcodeLinkMode(BarcodeLinkMode.SingleScanning)
 .addListener({
		onCapture(barcodes) {
			console.log('Scanned:' barcodes)
		}
 })

await barcodeLink.initialize(new BarcodeLinkUiFlow())
```

## API

### BarcodeLink

The main class for configuring and initializing your Barcode Link instance.

#### static forLicenseKey(licenseKey: string): BarcodeLink

```ts
const barcodeLink = BarcodeLink.forLicenseKey("-- ENTER YOUR SCANDIT LICENSE KEY HERE --");
```

Create a new BarcodeLink instance with the given Scandit license key.

#### setBarcodeLinkMode(barcodeLinkMode: BarcodeLinkMode): BarcodeLink

```ts
barcodeLink.setBarcodeLinkMode(BarcodeLinkMode.ContinuousListBuilding);
```

Configure your BarcodeLink instance to use the given BarcodeLinkMode.

**Available values:**

| Value                    | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| `SingleScanning`         | Scan one barcode and close the session                         |
| `ContinuousScanning`     | Send barcodes in realtime and manually close the session       |
| `SingleListBuilding`     | Send a list of barcodes and close the session                  |
| `ContinuousListBuilding` | Send multiple lists of barcodes and manually close the session |

Defaults to `BarcodeLinkMode.SingleScanning`.

#### setListBehavior(listBehavior: BarcodeLinkListBehavior): BarcodeLink

```ts
barcodeLink.setListBehavior(BarcodeLinkListBehavior.Count);
```

Configure your BarcodeLink instance to use the given BarcodeLinkListBehavior.

**Available values:**

| Value    | Description                                        |
| -------- | -------------------------------------------------- |
| `Unique` | Each barcode appears only once per list            |
| `Count`  | Keep track of how many times a barcode was scanned |

Defaults to `BarcodeLinkListBehavior.Unique`.

**NOTE:** The property is taken into consideration only for the following modes:

- `BarcodeLinkMode.SingleListBuilding`
- `BarcodeLinkMode.ContinuousListBuilding`

#### setPlatform(platform: BarcodeLinkPlatform): BarcodeLink

```ts
barcodeLink.setPlatform(BarcodeLinkPlatform.Web);
```

Configure your BarcodeLink instance to use the given BarcodeLinkListPlatform.

**Available values:**

| Value     | Description                                                     |
| --------- | --------------------------------------------------------------- |
| `Express` | Launch the Scandit Express app to start scanning                |
| `Web`     | Launch a browser tab with the Scandit Web SDK to start scanning |

Defaults to `BarcodeLinkPlatform.Express`.

#### setBarcodeRegexValidation(barcodeRegexValidation: RegExp): BarcodeLink

```ts
barcodeLink.setBarcodeRegexValidation(/\d+/);
```

Configure your BarcodeLink instance to use the given regex to validate barcodes.
Only barcodes that pass the validation regex will be scanned.

By default, no validation regex is set.

#### setBarcodeTransformations(barcodeTransformations: unknown): BarcodeLink

```ts
barcodeLink.setBarcodeTransformations({ ... });
```

Configure your BarcodeLink instance to use the given barcode transformations.

By default, no transformation is set.

**NOTE:** The property is taken into consideration only when the platform is `BarcodeLinkPlatform.Express`.

#### setSymbologies(symbologies: BarcodeLinkConfiguration['symbologies']): BarcodeLink

```ts
barcodeLink.setSymbologies({
	ean13upca: {
		enabled: true,
	},
});
```

Enable specific symbologies for scanning.

For a full list of supported symbologies, read here: https://docs.scandit.com/barcode-symbologies/

#### addListener(listener: BarcodeLinkListener): BarcodeLink

```ts
barcodeLink.addListener({
	onCapture(barcodes) {
		console.log("Scanned:", barcodes);
	},
});
```

Add a listener to the Barcode Link instance.

Available Callbacks:

##### onCancel

```ts
barcodeLink.addListener({
	onCancel() {
		console.log("Session closed.");
	},
});
```

Called when the desktop closes the scanning session.

**NOTE**: This callback is only available in a `BarcodeLinkUiFlow`.

##### onCapture

```ts
barcodeLink.addListener({
	onCapture(barcodes: BarcodeLinkBarcode[], finished: boolean) {
		// Do something with the barcodes
	},
});
```

Called when the remote device (ie: smartphone) sends captured barcodes to the main device (ie: desktop).

The second parameter `finished` is used in continuous modes (ie: `ContinuousScanning` and `ContinuousListBuilding`) to indicate whether the remote device has finished scanning or not.

When `finished` is `true`, the session has been closed.

##### onConnectionStateChanged

```ts
barcodeLink.addListener({
	onConnectionStateChanged(connectionState: BarcodeLinkConnectionState) {
		switch (connectionState) {
			...
		}
	},
});
```

Called when the connection state of either the main device or the remote device changes.

**Available values:**

| Value                        | Description                                               |
| ---------------------------- | --------------------------------------------------------- |
| `MainDeviceDisconnected`     | The desktop disconnected from the session                 |
| `MainDeviceReconnected`      | The desktop reconnected to the session                    |
| `MainDeviceConnectionFailed` | The desktop repeatedly failed to reconnect to the session |
| `RemoteDeviceConnected`      | The smartphone connected to the session                   |
| `RemoteDeviceDisconnected`   | The smartphone disconnected from the session              |

**NOTE**: This callback is only available in a `BarcodeLinkHeadlessFlow`.

#### removeListener(listener: BarcodeLinkListener): BarcodeLink

```ts
barcodeLink.removeListener(myListener);
```

Remove a listener from the Barcode Link instance.

#### initialize<T>(flow: BarcodeLinkFlow<T>): Promise<T>

```ts
await barcodeLink.initialize(new BarcodeLinkUiFlow());
```

Initialize Barcode Link with the given `BarcodeLinkFlow`.

**Available values:**

##### BarcodeLinkUiFlow

This flow initializes a pre-built UI, so you can start scanning right away.

This UI will show a QR code that you can use to connect your smartphone to the session.

##### BarcodeLinkHeadlessFlow

This flow initializes a headless barcode link session, so you will have to build your own UI around it.

To do this, you will have access to a special `onConnectionStateChanged` callback when adding a listener:

```ts
barcodeLink.addListener({
	onConnectionState(connectionState) {
		// Handle desktop/smartphone connection state changes
	},
});
```

When using this flow, `BarcodeLink.initialize` will return a `BarcodeLinkQrCode` object that you can use to connect.

For example:

```ts
const qrcode = await barcodeLink.initialize(new BarcodeLinkHeadlessFlow());

const img = document.createElement("img");
img.src = qrcode.src;

const a = document.createElement("a");
a.href = qrcode.href;
a.append(img);

document.body.append(a);
```

#### dispose(): void

```ts
await barcodeLink.dispose();
```

Close the Barcode Link session.
Useful for example if you want to close the session when unmounting a component.