Skip to main content

ProGlove Documentation

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.

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.9.2'

Your project can now build/assemble without issues.

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.disconnectScanner() method.

Connect a 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.

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 help 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 apps demonstrate using the SDK to display the last scanned value in a text field. Use the SDK Sample app to see how to implement the Scanner API.

Symbologies

For the list of supported Symbologies, see Symbology Settings.

Cross-platform integration

To integrate Insight Mobile with a Xamarin app, see the official Microsoft documentation and use the Intent API integration.

Android 11 limitation

Android 11 introduced some changes related to package visibility that affect apps which target Android 11.

For further description of the changes, see Package visibility filtering on Android.

Impact on Insight Mobile

If a client's app targets the API level 30 and uses Connect SDK to communicate with Insight Mobile, communication will not be established without the <queries> element in the client’s app Manifest. This <queries> element should make Insight Mobile visible to the Connect SDK, which is initiating the connection.

In the Connect SDK 1.8.0 we included the <queries> element in the SDK’s Manifest file, so that apps that implement this version or higher are not affected by this limitation.

Important

Client apps that target API level 30+ and use Connect SDK version lower than 1.8.0 will be affected.

Proposed solution
  • Use Connect SDK version 1.8.0 or higher

  • Add <queries> element to app Manifest file

    <queries>
        <package android:name="de.proglove.connect" />
    </queries>