Scanner API
The Scanner API enables a UI extension to access scanner data and available scanning sources supported by the device.
External and embedded scanners
Anchor link to section titled "External and embedded scanners"The API allows developers to integrate the scanning result with custom functionality in the POS app. To achieve this, use the scannerDataSubscribable to receive data and the scannerSourcesSubscribable to render specific UI elements based on available scanning sources.
Hardware scanner example
Anchor link to section titled "Hardware scanner example"In this example, assuming a physical scanner is connected to the POS, any scans performed when ui extensions are in use will automatically add the product to the cart if the data exists on the shop.
Conditional scanner source rendering example
Anchor link to section titled "Conditional scanner source rendering example"There might be situations where a developer needs to conditionally render UI elements based on the available scanning sources of the device on which the extension is installed. For example, an extension could be designed for full-screen camera scanning, but a device like POS GO does not have a camera. In such cases, it would be necessary to avoid rendering the camera scanner component and instead create a UI that supports embedded scanning.
Receiving scan event updates
Anchor link to section titled "Receiving scan event updates"The scannerDataSubscribable will return any scanner data and source that is executed on the extension. This means you can scan with your camera or hardware devices and receive the data in one place.
Receiving updates on available scanner sources for the POS
Anchor link to section titled "Receiving updates on available scanner sources for the POS"
ScannerApiContent
Anchor link to section titled "ScannerApiContent"| Name | Type | Description |
|---|---|---|
| scannerDataSubscribable | RemoteSubscribable<ScannerSubscriptionResult> |
Creates a subscription to scan events. Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription. You can utilize makeStatefulSubscribable on a RemoteSubscribable to implement multiple subscriptions. Using makeStatefulSubscribable or the corresponding hooks counts as a subscription. |
| scannerSourcesSubscribable | RemoteSubscribable<ScannerSource[]> |
Creates a subscription to the scanning sources available on the POS device. Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription. You can utilize makeStatefulSubscribable on a RemoteSubscribable to implement multiple subscriptions. Using makeStatefulSubscribable or the corresponding hooks counts as a subscription. |
RemoteSubscribable
Anchor link to section titled "RemoteSubscribable"| Name | Type | Description |
|---|---|---|
| initial | ScannerSubscriptionResult |
Initial scan event or scanner sources. |
ScannerSubscriptionResult
Anchor link to section titled "ScannerSubscriptionResult"| Name | Type | Description |
|---|---|---|
| data | string? |
The string data from the last scanner event received. |
| source | string? |
The scanning source from which the scan event came. |
ScannerSource
Anchor link to section titled "ScannerSource"| Name | Description |
|---|---|
camera |
Device camera |
external |
Third-party and externally connected scanning devices |
embedded |
Scanner embedded in device |
ScannerDataSubscribable Hooks
Anchor link to section titled "ScannerDataSubscribable Hooks"| Name | Description |
|---|---|
| useScannerDataSubscription() | A hook utilizing useState and the useStatefulSubscribableScannerData function to create a component state. This hook returns the latest scale result state which re-renders on change. |
| useStatefulSubscribableScannerData() | A hook utilizing the makeStatefulSubscribable function to allow multiple scanner subscriptions. This hook returns a StatefulRemoteSubscribable object with the scan result in it. |
| destroyStatefulSubscribableScannerData() | A function destroying the subscriptions useStatefulSubscribableScannerData has. |
ScannerSourcesSubscribable Hooks
Anchor link to section titled "ScannerSourcesSubscribable Hooks"| Name | Description |
|---|---|
| useScannerSourcesSubscription() | A hook utilizing useState and the useStatefulSubscribableScannerSources function to create a component state. This hook returns the latest scanner sources state which re-renders on change. |
| useStatefulSubscribableScannerSources() | A hook utilizing the makeStatefulSubscribable function to allow multiple scanner sources subscriptions. This hook returns a StatefulRemoteSubscribable object with scanner sources in it. |
| destroyStatefulSubscribableScannerSources() | A function destroying the subscriptions useStatefulSubscribableScannerSources has. |
Best practices
Anchor link to section titled "Best practices"Blocking Scenarios
Anchor link to section titled "Blocking Scenarios"In situations where scanning should not be allowed within a specific section of your application, use an error banner to inform merchants that scanning is not permitted on that screen and offer alternative areas where the scanning function can be performed.
Error Scanning
Anchor link to section titled "Error Scanning"Use the error banner at the top of the screen to denote errors while scanning or when encountering an unrecognized barcode.
Successful Scanning
Anchor link to section titled "Successful Scanning"Upon successful scanning of an item, display a ‘Toast’ component with a message such as "Item scanned" to indicate the outcome. Additionally, altering the screen contents can also be used to signal a successful scan.
Content guidelines
Anchor link to section titled "Content guidelines"Blocking or Error Scenarios
Anchor link to section titled "Blocking or Error Scenarios"- Be concise.
- Keep to 1 or 2 short sentences.
- Be dismissible unless it contains critical information or an important step merchants need to take.
Example:
✅Scanning not permitted on this screen. Go to {Section} to scan items.
Dismiss (CTA)
❌Error.
✅Barcode not recognized. Try scanning item again.
Dismiss (CTA)
❌Didn’t work.
Successful Scanning
Anchor link to section titled "Successful Scanning"- Used for short messages to confirm an action.
- Never go over 3 or 4 words.
- Do not use for error messages.
- Should be used for success messages.
- Written in the pattern of noun + verb.
Example:
✅Item scanned.
❌Your item has been scanned and added to your inventory count!