Getting Started with Capture JS

Requirements

The Socket Mobile Capture JS requires Socket Mobile Companion running on Windows or Android host or any Socket Maraca enabled apps such as Socket Mobile Rumba browser.

For web applications that need to work with barcode scanners, make sure the following requirements are met:

  1. Your application will need a SocketMobile AppKey. Follow the link to create an AppKey. AppKeys can be generated online and at no additional cost beyond the nominal one time registration fee. The AppKey is validated by the SDK library on the device, no internet connection is required. Note: You don’t need to create your own AppKey to compile and run the sample apps.

  2. The scanner needs to be paired with your devices in Application Mode. This can be done using the Socket Mobile Companion app (recommended), which can be downloaded from the App Store and also on the Play Store and for Windows.

  3. Use a web app with an iOS device. You will need to download the Rumba app. Rumba acts as a browser to host your web app. It leverages Maraca to make the webview Capture JS enabled. An easy way to do this is to first download Rumba from the App store, and then run your app on a local http server using ngrok and put the generated secure URL in the Rumba browser. For more on how to do this, please read this blog post.

  4. Try a sample web app. Check out our Github repository to get started with our demo web app, Single Entry.

Capture JS Installation

CaptureJS can be used directly from this CDN: https://socketimagescdn.azureedge.net/cdn/scripts/captureJs-1.0.5.6.js or of course downloaded from there.

The release process always copies 8 files to this CDN location. captureJs-[version].min.js for the minimized version, captureJs-[version].js for the non-minimized version, captureJs-latest.min.js for the latest minimized version, captureJs-latest.js for the latest non-minimized version.

Each of these files have their associated map file for helping during the debugging process.

By example the captureJs-latest.js has a captureJs-latest.map file.

We recommend to use the latest version while developing your application, and then switch to the file name with version once you’re ready to QA your application.

The actual corresponding version number of the latest file could be found in the first line of the file.

Using Capture JS

CaptureJS.js can be used by simply adding a script tag in your web application like this: <script type='module' src='https://socketimagescdn.azureedge.net/cdn/scripts/captureJs-1.0.5.6.js'></script>

Capture is then available in the web app using SocketMobile prefix.

By example to open and initialize Capture here are the lines required for achieving this:

let appInfo = {
        appId: 'web:singleentry.socketmobile.com',
        developerId: 'bb57d8e1-f911-47ba-b510-693be162686a',
        appKey: 'MCwCFG+OuO7Xuh2oG091QerDjN3x8kheAhQT/HBNoYjhptLjJXWwW5DVM3I2zg=='
};

capture = new SocketMobile.Capture();

// open Capture
capture.open(appInfo, eventNotification)
        .then(result => {
        console.log('opening Capture result: ', result);
        setStatus(`opening Capture result: ${result}`);
        })
        .catch(err => {
        console.log('opening Capture error: ', err);
        // error code to watch for to check if the Companion service is
        // running
        if(err === SocketMobile.SktErrors.ESKT_UNABLEOPENDEVICE){
                setStatus('no able to connect to the service, is it running?');
        }
        else {
                setStatus(`opening Capture error: ${err}`);
        }
        });

Once Capture is open with success, the notifications are received in the eventNotification callback.

Once a device connects, a deviceArrival notification with the information about the device is received in the notification callback. If the application needs this device, it can create a capture instance for this device and open it with the device UUID as shown below:

const eventNotification = (event, handle) => {
        if(event) {
                if(event.id === SocketMobile.CaptureEventIds.DeviceArrival) {
                        captureDevice = new SocketMobile.Capture();
                        captureDevice.openDevice(event.value.guid, capture)
                        .then(result => {
                                console.log('opening device returns:', result);
                        })
                        .catch(err => {
                                console.log(err);
                        });
                }
        }
};

This is assuming the eventNotification is the notification callback passed in the Capture.open method along with the AppInfo.

As soon as a Socket Mobile is connected and open by the web app, then the web app could receive the decoded data in the same notification callback.

Here is an example of the eventNotification callback that can be used to open a Socket Mobile device as soon as it connects and to receive the decoded data:

const eventNotification = (event, handle) => {
        if(event) {
                if(event.id === SocketMobile.CaptureEventIds.DeviceArrival) {
                        console.log('Open the device:');
                        console.log(event.value.guid);
                        captureDevice = new SocketMobile.Capture();
                        captureDevice.openDevice(event.value.guid, capture)
                        .then(result => {
                                console.log('opening device returns:', result);
                        })
                        .catch(err => {
                                console.log(err);
                        });
                }
                else if (event.id === SocketMobile.CaptureEventIds.DecodedData) {
                        setName(event.value.name);
                        setLength(event.value.data.length);
                        setData(arrayToString(event.value.data));
                }
        }
};