Skip to content

SDK API - basic integration

This path provides a code-level integration of Insight Mobile with your system and offers full control over connection and callback features.

Prerequisites:

  • Insight Webportal account activated
  • Insight Mobile (Android) app installed on your Android device
  • The minimum required Android version is 6.0 or higher (7.0 is recommended)
  • The ProGlove Insight Mobile SDK requires a minimum Android API Level of 18.

How to add a library

To download the AAR:

  1. Add this snippet to your Gradle repository, top level (code in Groovy):
    allprojects {
  repositories {
      maven {
          url "https://dl.cloudsmith.io/public/proglove/pgconnect-public/maven/"
      }
   }
}
  2. Add this snippet to your app's build.gradle in the dependencies block:
    implementation 'de.proglove:connect-sdk:1.6.0'
    Your project can now build/assemble without issues.

How to integrate a scanner

To integrate a scanner, you need somewhere to hold a reference to it.
If you need access to the scanner in multiple places of your application, the SDK can be instantiated in the Application Android Object. However, any other Context object will work as well (Activity or Service).
In the onCreate, instantiate the Scanner Manager and connect it to the Insight Mobile app.

Note: The example below is taken from the sample app, where everything is implemented in a single Activity (code in Kotlin). You can adapt this to your business needs. 

val pgManager: PgManager = PgManager()

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate()
    val result = pgManager.ensureConnectionToService(this.applicationContext)
}

Check the return value (boolean) to see if the service binding worked. If the correct version of Insight Mobile is installed on your device, you will get a positive response.

After this, access the pgManager variable to use the SDK.

(Optional) Callback for service connection

The connection to the SDK Service is fast and you should not encounter any issues by proceeding with the pairing process right away.
But it is still asynchronous, so you may want to register for callbacks of the Service connection. Before calling pgManager.connect(...), register your implementation of the IServiceOutput interface (In this case this).
Also, make sure to unsubscribe from these events. onCreate and onDestroy are great for that. 

override fun onCreate(savedInstanceState: Bundle?) {

    //...
    pgManager.subscribeToServiceEvents(this)
}

override fun onDestroy() {
    super.onDestroy()

    pgManager.unsubscribeFromServiceEvents(this)
}

Callback for scanned barcodes

To receive new barcode scan data, call the pgManager.subscribeToScans() function and implement the IScannerOutput interface.
For example, in the same onCreate of our sample app, we subscribe to the scanner info. And we unsubscribe in the onDestroy function. 

override fun onCreate(savedInstanceState: Bundle?) {

     //...

     pgManager.subscribeToScans(this)

     //...
}

override fun onDestroy() {
     super.onDestroy()
     pgManager.unsubscribeFromScans(this)
}

To do this, our Activity needs to implement the IScannerOutput interface:

//
// -- IScannerOutput --
//

override fun onBarcodeScanned(barcodeScanResults: BarcodeScanResults) {
      // the scanner input will come on background threads, make sure to execute this on the UI Thread
    runOnUiThread {
        if(barcodeScanResults.symbology.isNotEmpty()) {
            Toast.makeText(this, "Got barcode: ${barcodeScanResults.barcodeContent} with symbology: ${barcodeScanResults.symbology}", Toast.LENGTH_LONG).show()
            // do some custom logic here to react on received barcodes and symbology
        } else {
            Toast.makeText(this, "Got barcode: ${barcodeScanResults.barcodeContent}", Toast.LENGTH_LONG).show()
            // not every scanner currently has the ability to send the barcode symbology
        }
    }
}

override fun onScannerConnected() {
        // let the user know that the scanner is connected
}

override fun onScannerDisconnected() {
     // Inform the user that the scanner has been disconnected
}

Scanner state

The IScannerOutput callback and PgManager provide you with several methods for tracking the scanner state.

As shown above, the IScannerOutput interface will be called whenever a scanner connects or disconnects.

You can also query the PgManager methods.

To disconnect, call the PgManager.disconnect() method.

How to pair with scanner

To start the pairing process, call startPairing() on your PgManager reference. The Insight Mobile app will take over and show the paring QR code. After your device was paired with a scanner or the process was canceled by the user, your Activity will be brought back to the foreground. Your registered IScannerOutput implementations will be called according to the updated scanner state.

How to pair from the pinned Activity

If your app runs inside the Android's pinned application mode, you have to use startPairingFromPinnedActivity(activity).
activity must be an Activity running in the currently pinned task. Pairing works the same as with startPairing() but works in the pinning mode.
pgManager.connect(this.applicationContext) should still be called with the ApplicationContext. That way a scanner stays connected regardless of the Lifecycle of a single Activity.

Starting the pairing from a Background Task: Only startPairing() is able to work from a Service's Context.

Logging

To facilitate with debugging, the PgManager can be injected with a java.util.Logger object that will receive all log information.

    private val pgManager = PgManager(logger)

Sample Apps

The Sample App is a (very simple) implementation using the SDK to display the last scanned value in a text field. You can use this application to see how to implement the Scanner API.

Symbologies

For the list of supported Symbologies, see Symbologies.

Cross-platform integration

To learn how to integrate Insight Mobile with a Xamarin app, see the official Microsoft documentation, and download the relevant connect-sdk .AAR file from here.