USB Barcode Scanner Component

UI Component

Changed on:

29 July 2024

Overview

An invisible component that accepts input from a USB scanner in HID mode (keyboard simulation) and performs an action on a scan. This component activates when nothing on the screen is currently selected and enables efficient scanning of parcel labels to perform various functions, like marking a customer order as collected.

Most commonly, the Barcode Scanner component is included in Fluent Store manifests centered around collections.

Plugin Name	Core

The standard library of mystique components.

0000-00-00

v1.0.0

Initial changelog entry.

Alias

fc.barcode.scanner

Detailed technical description

Limitations

This method only allows you to use GraphQLQueries where the variable is at the topmost level. Using it to filter a list of objects by referring to a nested object property may not work as expected.

For example, the below GraphQL query uses barcode input on the nested items query. However, the

`articlesByLocation`

will not be filtered and will instead return all articles, with only the items filtered by the barcode. Since the barcode component requires a single object to be returned, this will not work.

1query ($barcodeInput: [String!]){
2  articlesByLocation {
3    edges {
4      node {
5        items(barcode:$barcodeInput) { ❌
6          edges {
7            node {
8              id
9            }
10          }
11        }
12      }
13    }
14  }
15}

Language: graphqlschema

Name: articleByLocation

Description:

[Warning: empty required content area]

Error Messages

When an error occurs, a toast message will pop up displaying a short message for the user. These messages are aimed at store assistants scanning many items and are short without describing the issue in detail.

Detailed error messages on the other hand are available in the browser console, which can be accessed through a browser’s developer tools.

Worked Example

Example of using the barcode scanner to

`navigate`

from the Customer Collections page, to the articles collection page. In this example, the barcode scanned is the Article ID.

1{
2  "component": "fc.scanner.barcode",
3  "props": {
4      "enableCameraScanner": true,
5      "action": {
6          "type": "navigate",
7          "link": "#/collections/customer/{{id}}"
8      },
9      "query": "query ($barcodeInput: ID!) { articleById(id:$barcodeInput) { id } }"
10  }
11}

Language: plain_text

Name: Sample manifest

Description:

[Warning: empty required content area]

Sample Usage

Put the sample manifest into the Customer Collections Store fragment
Within Fluent Store, navigate to the collections page
Scan an Article ID for an article waiting to be collected
The Article ID is put into the GraphQL query via the
```
`$barcodeInput`
```
variable
Then the GraphQL query is executed
If a result is found the navigation to the relevant Article page is performed

Note

To test the barcode scanner component, you can type onto the page when no element is selected or in focus. This is possible because Barcode scanners emulate a virtual keyboard.

Properties

Name	Type	Required	Default	Description
Query	Graphql String	No	Page level query	It takes a GraphQL query to execute on a scan. This query has a special function. If the query has `$barcodeInput ` variable then this will be populated with the barcode that was scanned. This is done on each scan, and the query is immediately executed afterward.
Variables	Object	No		A list of entries that maps each GraphQL variable to its value.
Action	`BarcodeNavigateAction` , `BarcodeUserAction` , `BarcodeTestAction`	Yes		The config containing the action to perform on a scan.
enableCameraScanner	boolean	No	false	Enables the Mobile Barcode Scanner
camera	camera object	No	N/A	The parent object that captures all of the properties that can be configured in the camera scanner. See below config table "Mobile Barcode Scanner Configuration" for details

Actions

Upon a successful scan, the component currently supports three types of actions.

User Action

With the user action type, the name of the user action is provided in the manifest, and this action will be performed on the scanned item.

If the user action requires additional information, a window will pop up allowing user input before the action is performed.

Name	Type	Required	Default	Description
Type	“userAction”	Yes		The type of action to perform. Specify “userAction” to perform a user action.
Name	String	Yes		The name of the user action to perform.

Navigation

With the navigate action type, a link is provided in the manifest, and the barcode scanner component will navigate to this URL after scanning a barcode. The link may be templated to include information from the data to allow the URL to be dynamically generated based on the barcode.

Name	Type	Required	Default	Description
Type	“Navigate”	Yes		The type of action to perform. Specify “Navigate” to perform a navigate action.
Link	URL	Yes		The link to navigate to.

Barcode Test Action

Name	Type	Required	Default	Description
Type	“Test”	Yes		The type of action to perform. Specify “Test” to test the component. With this action, the message “Successfully scanned ” will be displayed when a - barcode is scanned on the page.

Mobile Camera Scanner Configuration

Name	Type	Required	Default	Description
`frequency`	`number`	No	10	Frequency is the number of scan attempts per second. The frequency is an integer ranging from 1 to 10, and its default setting is 10. Opting for a higher frequency enhances scanning accuracy but also leads to greater utilization of the phone battery. To preserve the phone's battery life, it is advisable to choose a lower value.
`decoders`	`array`	No	`[code_128_reader,ean_reader]`	The decoder in the barcode scanner specifies what kind of barcode it's searching for. It has a list (array) of possible barcode types that it checks one by one, in the order given. The decoding process stops at the first successful result. The array can include multiple barcode types, but performance decreases with each additional type. The scanner reads the entire barcode, including leading and ending zeros, without trimming it. Possible values are: `"code_128_reader", "ean_reader", "ean_5_reader", "ean_2_reader", "ean_8_reader", "code_39_reader", "code_39_vin_reader", "codabar_reader", "upc_reader", "upc_e_reader", "i2of5_reader", "2of5_reader", "code_93_reader", "code_32_reader", "qr_reader"`
`disableFeedback`	boolean OR `{ success: boolean, fail: boolean }`	No	true	Disable the audio and haptic feedback on scan. You can configure the success and failure haptic feedback responses individually, or you can configure them together. The value is either true OR { success: boolean; fail: boolean}. This way, you can globally disable feedback by passing true or selectively disable feedback by passing { success: true }, { failure: true }, or { success: true; fail: true}. Note: Haptic feedback isn't available on iOS because of Safari constraints. On Android, a successful scan produces a single vibration, while an unsuccessful one results in two vibrations.
`confidence`	`float`	No	0.9	The confidence value ranges between 0 and 1, with precision up to two decimal points. Confidence serves as a trade-off between accuracy and error margin. A higher confidence level corresponds to a reduced margin for error, especially in scenarios where the camera quality may not be excellent.

Configuration example

1{
2  "component": "fc.scanner.barcode",
3  "props": {
4      "action": {
5          "type": "navigate",
6          "link": "#/collections/customer/{{id}}"
7      },
8      "query": "query ($barcodeInput: ID!) { articleById(id:$barcodeInput) { id } }"
9  }
10}

Language: json

Version History

2023-08-01

v23.8.1

Recommended Placement

None