CaptureHelper for The React Native CaptureSDK

Version 2.0 of the React Native CaptureSDK introduces a completely redesigned CaptureHelper class. It is now a full lifecycle manager that handles opening/closing the SDK, device arrival/removal, decoded data, BLE discovery, and more — all through typed callbacks and methods.

Note

CaptureHelper replaces the previous pattern of using CaptureRn directly with a manual onCaptureEvent switch/case. The low-level CaptureRn API is still available for advanced use cases.

CaptureHelper

Creating and Opening

Create a CaptureHelper instance by passing your app credentials and callback functions. Then call open() to start the SDK:

import {
    CaptureHelper,
    type CaptureHelperDevice,
    type AppInfoRn,
    type DecodedData,
    type DiscoveredDeviceInfo,
    SocketCamTypes,
    BluetoothDiscoveryMode,
    Trigger,
} from 'react-native-capture';

const appInfo: AppInfoRn = {
    appIdIos: 'ios:com.mycompany.myapp',
    appKeyIos: 'MC0C...',
    appIdAndroid: 'android:com.mycompany.myapp',
    appKeyAndroid: 'MC0C...',
    developerId: 'your-developer-id',
};

const helper = new CaptureHelper({
    appInfo,

    onDeviceArrival: (device) => {
        console.log(`Device connected: ${device.name}`);
        setDevices(d => [...d, device]);
    },

    onDeviceRemoval: (device) => {
        console.log(`Device disconnected: ${device.name}`);
        setDevices(d => d.filter(dd => dd.guid !== device.guid));
    },

    onDecodedData: (data, device) => {
        console.log(`Scanned: ${data.name}`);
        setDecodedData(data);
    },

    onError: ({ code, message }) => {
        console.error(`CaptureSDK error ${code}: ${message}`);
    },
});

await helper.open();

Closing

Always close the helper when your component unmounts:

useEffect(() => {
    helper.open().catch(console.error);
    return () => { helper.close().catch(() => {}); };
}, []);

Callbacks

All callbacks are optional. Pass them in the constructor options:

interface CaptureHelperCallbacks {
    /** Called when a device (scanner, NFC reader, SocketCam) connects */
    onDeviceArrival?: (device: CaptureHelperDevice) => void;

    /** Called when a device disconnects */
    onDeviceRemoval?: (device: CaptureHelperDevice) => void;

    /** Called when a device produces a barcode scan or NFC read */
    onDecodedData?: (data: DecodedData, device: CaptureHelperDevice) => void;

    /** Called when the user closes the SocketCam native view (result -91 / ESKT_CANCEL) */
    onSocketCamCanceled?: (device: CaptureHelperDevice) => void;

    /** Called during BLE discovery when a device is found */
    onDiscoveredDevice?: (device: DiscoveredDeviceInfo) => void;

    /** Called when a BLE discovery scan ends */
    onDiscoveryEnd?: (result: number) => void;

    /** Called when a device's battery level changes */
    onBatteryLevel?: (level: number, device: CaptureHelperDevice) => void;

    /** Called when a device's power state changes */
    onPowerState?: (state: PowerState, device: CaptureHelperDevice) => void;

    /** Called when the state of a device's buttons changes */
    onButtons?: (state: Notifications, device: CaptureHelperDevice) => void;

    /** Called on SDK errors */
    onError?: (error: { code: number; message: string }) => void;

    /** Called when the SDK emits a log trace */
    onLogTrace?: (trace: string) => void;
}

CaptureHelper Methods

Lifecycle

  • open(): Open the SDK connection and start receiving events.

  • close(): Close the SDK connection and release resources.

Device management

  • getDevices(): Returns the list of currently connected CaptureHelperDevice objects.

  • rootCapture: (property) Returns the underlying CaptureRn instance — needed by SocketCamViewContainer.

SDK information

  • getVersion(): Returns { major, minor, build }.

  • getConfirmationMode(): Returns the current DataConfirmationMode.

  • setConfirmationMode(mode): Sets the data confirmation mode.

SocketCam

  • setSocketCamEnabled(enabled: boolean): Enable or disable SocketCam. Enabling triggers a DeviceArrival for the SocketCam virtual device.

  • getSocketCamEnabled(): Returns the current SocketCam status.

  • setSocketCamSymbologySelectorDisabled(disabled: boolean): Hide or show the symbology selector in the SocketCam overlay.

BLE discovery and connection

  • addBluetoothDevice(mode: BluetoothDiscoveryMode): Start scanning for nearby Bluetooth devices. Each found device fires the onDiscoveredDevice callback. Use BluetoothDiscoveryMode.BluetoothLowEnergy or BluetoothDiscoveryMode.BluetoothClassic.

  • removeBluetoothDevice(uuid: string): Stop a specific Bluetooth device scan.

  • connectDiscoveredDevice(device: DiscoveredDeviceInfo): Connect to a discovered device. Triggers onDeviceArrival on success.

  • removeBleDevice(device: CaptureHelperDevice): Disconnect a connected BLE device. Triggers onDeviceRemoval.

  • disconnectFromDiscoveredDevice(device: DiscoveredDeviceInfo): Disconnect using the discovered device info (by identifierUuid).

  • getDeviceUniqueIdentifier(deviceGuid: string): Get the unique identifier string for a BLE device.

CaptureHelperDevice

Connected devices are wrapped in CaptureHelperDevice objects. These are created automatically by CaptureHelper — you never instantiate them yourself. They are passed to your callbacks (onDeviceArrival, onDecodedData, etc.).

Properties

  • name: The device name (e.g. “Socket S721 [E2ABB4]”).

  • guid: The connection session GUID (changes on each connection).

  • type: The device type (e.g. CaptureDeviceType.DeviceS721).

  • handle: The native SDK handle.

  • devCapture: The underlying CaptureRn instance for advanced use.

Device Information Methods

// Friendly name
const name = await device.getFriendlyName();
await device.setFriendlyName('My Scanner');

// Bluetooth address
const address = await device.getBluetoothAddress();

// Device type
const type = await device.getDeviceType();

// Firmware version
const fw = await device.getFirmwareVersion();
// fw: { major, middle, minor, build, year?, month?, day? }

Status Methods

// Battery level (returns 0–100 directly)
const level = await device.getBatteryLevel();

// Power state
const power = await device.getPowerState();

// Buttons state
const buttons = await device.getButtonsState();

Scan Control Methods

// Trigger a scan
await device.setTrigger(Trigger.Start);

// Enable/disable a symbology (data source)
const ds = await device.getDataSource(CaptureDataSourceID.SymbologyQRCode);
await device.setDataSource(CaptureDataSourceID.SymbologyQRCode, CaptureDataSourceStatus.Enable);

Configuration Methods

// Stand config
const stand = await device.getStandConfig();
await device.setStandConfig(StandConfig.Detect);

// Timers
const timers = await device.getTimers();
await device.setTimers(Timer.TriggerLock, 3000, 60000, 5000);

BLE Lifecycle Methods

// Disconnect device
await device.setDisconnect();

// Factory reset
await device.setFactoryReset();

// Reset device
await device.setReset();

// Power off device
await device.setPowerOff();

Migration from version 1.x

Step 1 — Replace CaptureRn + onCaptureEvent with CaptureHelper

// ❌ Before (v1.x)
const capture = new CaptureRn();
await capture.open(appInfo, onCaptureEvent);
// ...big switch/case in onCaptureEvent

// ✅ After (v2.0)
const helper = new CaptureHelper({
    appInfo,
    onDeviceArrival: (device) => { /* ... */ },
    onDecodedData: (data, device) => { /* ... */ },
});
await helper.open();

Step 2 — Use CaptureHelperDevice methods instead of raw properties

// ❌ Before — manual property construction
const prop = new CaptureProperty(
    CapturePropertyIds.FriendlyNameDevice,
    CapturePropertyTypes.None, {}
);
const result = await deviceCapture.getProperty(prop);
const name = result.value;

// ✅ After — typed method
const name = await device.getFriendlyName();

Step 3 — Update SocketCam code

// ❌ Before
await CaptureHelper.setSocketCamEnabled({ socketCamCapture, ... });

// ✅ After
await helper.setSocketCamEnabled(true);

Step 4 — Use discovery methods for BLE devices

// ❌ Before — manual DeviceManagerArrival handling, CaptureProperty for AddDevice
// ✅ After
await helper.addBluetoothDevice(BluetoothDiscoveryMode.BluetoothLowEnergy);
// onDiscoveredDevice callback fires for each device found
await helper.connectDiscoveredDevice(discoveredDevice);

Step 5 — Battery level is now a direct percentage

// ❌ Before — manual bit shifting
const raw = await device.getBatteryLevel();
const level = (raw >> 8) & 0xff;

// ✅ After — returns 0–100 directly
const level = await device.getBatteryLevel();