CaptureSDK Documentation

Platforms / languages supported

The Socket Mobile CaptureSDK supports the following platforms and languages:

C# - Windows / Xamarin

Swift and Objective C - iOS

Java - Android and Windows

JavaScript - Android, Windows and iOS (using Rumba/Maraca)

React Native - Android and iOS

Flutter (Dart) - Android and iOS

Current device types supported based on development language and frameworks (B: barcode scanners, N: NFC readers, C: Camera-based scanning)

Language	iOS	Android	Windows	web
C# (Xamarin)	B, N, C	B, N, C	B
Flutter	B, N, C	B, N, C
Java		B, N, C	B, N
Javascript				B, N (*)
React Native	B, N, C	B, N, C	B, N
Swift and Objective C	B, N, C

* the device type availability on web is dependent on what platform the webpage is running on.

Also note that on iOS, only SocketCam C820 is supported for C#, Flutter, and React Native.

How it works - basic concepts

Readers must be paired to mobile devices in App mode

CaptureSDK uses App mode (also known as SPP mode) to communicate with the hardware devices. In this mode, data is transferred in chunks, which is more efficient and faster than normal HID mode, where data is transferred (from scanner/reader to hosting device) one character at a time.

To work with CaptureSDK, your reader must be into App mode. This applies to both Bluetooth scanners and Bluetooth LE NFC reader/writers. Once turned into App mode, the reader should be paired to the hosting mobile device. Note that this process cannot be completely automated. The exact detailed process varies by reader types. We recommend using the Socket Mobile Companion app for this.

Managing Socket Mobile reader connection in an app

Your app will not need to go through a discovery process to connect to a reader. Once the reader is paired to the mobile device in App mode, the SDK will manage the connection or the connection status. Specifically, when initiated (opened), the Capture Service will connect to the paired reader and send a device arrival event to the app. The app is now ready to receive data from the reader.

For native iOS apps

On iOS, when the app goes to the background or is inactive, the scanner will disconnect from the app. The app receives a device removal event. Note that even though the Bluetooth Classic devices and Bluetooth Low Energy devices are managed differently by iOS, overall, the device connection is governed by the OS. An app’s access to a device is strictly confined in its sandbox. Apps do not have access to Socket Mobile readers while in the background. When the app returns to the foreground, the OS will hand over the scanner connection, and the app will receive the device arrival event again.

A subtle difference with Bluetooth LE readers

Bluetooth LE readers are not managed by the External Accessory Framework. Developers with experience in dealing with other Bluetooth LE products, such as Bluetooth speakers, may expect to handle the device discovery and pairing themselves. Even though this is possible with Socket Mobile’s Bluetooth LE devices, such as the S550 and D600, it is not recommended. We suggest using the Capture Helper (see the section below). When a Bluetooth LE device is connected, even when the app goes to the background, the reader remains connected to the app and cannot be discovered by other iOS devices, nor can it be used by other apps on the same device. If you want to make the reader available for another app, you need to close the device manager provided by CaptureSDK.

For native Android and Windows apps

On Android and Windows, the reader connection is managed by the Companion Service (Capture Service), which is installed by the Socket Mobile Companion app and is a shared service. Once connected, the reader technically remains connected to the hosting device as long as the service is running. When the app comes to the foreground, Companion Service will hand over the reader connection, and the app receives the device arrival event.

For web applications

Because of the differences between iOS and Android/Windows (noted above), the SDK footprints required to run on iOS and Android/Windows are also different.

On iOS, your web app will need to run on Socket Mobile’s Rumba app, which handles the reader connection for the web app. On Android/Windows, Socket Mobile Companion is required. However, you can use the web browser of your choice since the device connection is handled by the shared Companion service.

SocketCam as a device type

To ensure a consistent experience and a unified implementation for all data capture means, we treat camaera-based barcode scanning (SocketCam) as another type of data reader device. There is no difference for an app to support SocketCam or other physical devices such as Bluetooth barcode scanners. You can still use the Capture Helper to manage the connection. And as a result, your app will receive a device arrival event with device type information.

Because SocketCam is architected as an extension, you will need to set the device property to be enabled first before the reader is visible to use. Once enabled, you will receive a device arrival event for SocketCam when you open CaptureSDK. On a side note, you must set up a trigger button to launch the camera view, since this is a virtual device. This trigger button can be software-based, or you could use the volume buttons on your mobile device (requires some additional work in your app).

Combo products (SocketScan S370)

The S370 combo reader has a particularity of having two devices in one:

1. An NFC reader/writer

2. A Barcode scanner

When the reader is connected to CaptureSDK, there will be two device arrivals, one for the NFC device and one for the Barcode device. You are free to handle each device as you wish, even ignore one of them for instance.

The two CaptureSDK properties that are created or updated with this new device type are Themes Selection and Trigger.

1. Themes Selection: you can choose from one of the four color schemes of the sequences of LEDs animations played by each device to play different sequences when the reader is ready, reading, read success or read failure.

   More details for

   • iOS (Swift and Objective C )

   • Android ( Java )

2. Trigger: you can choose to start a trigger continuous scan, continuous scan until something has been read or stop the trigger.

   More details for

   • iOS (Swift and Objective C )

   • Android (Java )

Those 2 properties can be set from both devices.

Sample code:

• S370 sample code - iOS

• S370 sample code - Java - Android

Take advantage of SocketCam for initial testing

SocketCam C820, our free camera-based scanning solution, is included in CaptureSDK and can be used for testing purposes. Testing with a hardware device can be challenging and time- consuming. If you are new to CaptureSDK, you will need to determine if the reader is connected and working properly, in addition to debugging the SDK implementation. Given the iterative nature of programming, these extra steps can add significant time and effort. Using SocketCam as your first reader for testing can eliminate many issues and uncertainty from the process. All you need to do is to enable SocketCam in your app and add a software-based trigger button somewhere in your app. You can start testing your implementation without any hardware setup or configuration. Once it works properly in your app, you can be confident your implementation will also work with other Socket Mobile hardware readers if connected properly to the mobile devices.

Properties and configurations

Each reader has specific properties that can be configured, such as whether it beeps or vibrates when it successfully reads a barcode or a tag, or when certain barcode symbology types are turned on or off.

Capture Helper

Capture Helper is a helper class we use extensively in CaptureSDK to help simplify the code for accessing the readers. The use of Capture Helper is optional, ; however, it not only helps reduce the amount of code to write, but also helps avoid some of the common issues.

Socket Mobile Companion app

Socket Mobile Companion app is available on iOS, Android, and Windows. It helps Socket Mobile device users to connect their devices in the proper mode. Users will also be able to check device warranty, get trouble shooting information, purchase SocketCare, request RMA etc.

iOS and MFi

Please note that the current scanners (Bluetooth Classic based) use Apple External Accessory Framework. This requires you get MFi approval before your app can be approved by the App Store. The free MFi approval process typically takes extra 3-5 business days and will be processed by Socket Mobile on your behalf.

For developers who want to have their users/customers use Socket Mobile Bluetooth barcode scanners, this requirement implies two action items:

1. You will need to add the string com.socketmobile.chs in your app’s info.plist.

2. Before your app is approved by the app store, you will need to use your Socket Mobile Developer account to submit your app for MFi approval.

Planning for product upgrade, expansion, and migration

One benefit worth highlighting is that because CaptureSDK is a unified SDK, upgrading or switching between different data reader models is relatively seamless. In most cases, it doesn’t take any extra work by 3rd party developers.

Note that if you started with the camera-based solution without adding the com.socketmobile.chs string in your info.plist into your app, or go through the MFi process, you will need to do so before your customers can start using the Bluetooth barcode scanners.

Source Samples in Github

You can see the Capture API in action in Socket Mobile Github.