ProGlove Documentation

Intent API - basic integration

Use this path for apps that already use Android Intents to exchange data.

It is a drop-in replacement of the existing configuration (e.g. integrated scanners of Zebra devices) that uses the Android Intent API.

A range of industrial browsers (e.g. Velocity by Ivanti), business applications (e.g. SmartTE by Staylinked), and other device manufacturers use this method.

The Insight Mobile app sends data via Broadcast Intents, and listens for the specified Intents. They can originate from any app on this device, including Cordova/React applications.

Important

For certain features, a scanner must be paired to Insight Mobile for the API to work.

To learn more about Intents on Android, see:

Select the Intent integration path

Prerequisite: Insight Webportal account activated.

  1. On Insight Webportal, under Device Visibility, select Configurations.

    The list of existing configurations displays.

  2. At the top right, click the AddIcon.png icon to add a configuration.

    Note

    You can also click the pencil icon next to an existing configuration to modify it.

  3. Select Insight Mobile (Android).

  4. Click Next.

  5. Click Select Connectivity Settings.

    The Integration Path section displays with Software Keyboard, Intent, WebSocket, and SDK options.

  6. Under Integration Path, select Intent.

  7. Under Intent Type, select the desired type: Broadcast Intent, Start Activity with Action, or Start Activity with Component.

  8. Enter the Intent Action or Component Path and Component Package.

  9. At the bottom of the page, click Save.

Barcode scan Intent structure

After every barcode scan, an Intent with the defined action is sent containing the following extras:

  • Use this extra to get a string with the barcode data:

com.proglove.api.extra.BARCODE_DATA

  • For easier integration, we provide the barcode data in these extras too:

com.symbol.datawedge.data_string
com.motorolasolutions.emdk.datawedge.data_string

  • Use this extra to get barcode’s symbology, e.g. “EAN-13” (see Symbology Settings for the full list of supported symbologies):

com.proglove.api.extra.BARCODE_SYMBOLOGY

  • For easier integration, we provide the symbology data in these extras too:

com.symbol.datawedge.label_type
com.motorolasolutions.emdk.datawedge.label_type

Note

To support compatibility with Zebra DataWedge, the symbology data contained in the extras com.symbol.datawedge.label_type and com.motorolasolutions.emdk.datawedge.label_type corresponds to the label type values used by Zebra.

Receive barcode data

To receive broadcast Intents:

  1. Implement a broadcast receiver (in this case the class is called MessageHandler):

    class MessageHandler : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        if (intent != null && intent.action == "com.proglove.api.BARCODE") {
            intent.getStringExtra("com.proglove.api.extra.BARCODE_DATA")
            intent.getStringExtra("com.proglove.api.extra.BARCODE_SYMBOLOGY")
        }
    }
}

  2. Define an IntentFilter for the specified actions:

    val messageHandler: MessageHandler = MessageHandler()
val filter = IntentFilter()
filter.addAction("com.proglove.api.BARCODE")
filter.addCategory(Intent.CATEGORY_DEFAULT)

  3. Register the broadcast receiver instance with a context. The usual place for this call would be in the onCreate method of a Service or an Activity class:

    context.registerReceiver(messageHandler, filter)

Note

Do not forget to unregister the receiver again, for example in onDestroy:

context.unregisterReceiver(messageHandler)
Receive scans with startActivity()

When you configure the Intent Action, there is a Start Activity checkbox.

This changes the Intent delivery from Broadcast Intents ( = sendBroadcast()) to startActivity(). To receive the Intent your code will have to reflect this change.

Note

Due to limitations on Android 10, this delivery method does not work reliably anymore on that version.

To learn more, see Restrictions on starting activities from the background.

Logging/Output

API return values, errors, and general information are logged to the Android console and can be viewed by filtering logcat to de.proglove.connect.intent.api or PGAPI.

   adb logcat -e PGAPI
Receive scanner connection state

The Insight Mobile app broadcasts the following Intent upon every scanner connection state change:

  • Action: com.proglove.api.SCANNER_STATE

  • Extra: String in com.proglove.api.extra.SCANNER_STATE

Example code to get scanner state events:

  1. Implement a broadcast receiver (in this case the class is called MessageHandler):

    class MessageHandler : BroadcastReceiver() {  
    override fun onReceive(context: Context?, intent: Intent?) {  
        if (intent != null && intent.action == "com.proglove.api.SCANNER_STATE") {  
            intent.getStringExtra("com.proglove.api.extra.SCANNER_STATE")  
        }  
    }  
}

  2. Define an IntentFilter for the desired actions:

    val messageHandler: MessageHandler = MessageHandler()  
val filter = IntentFilter()  
filter.addAction("com.proglove.api.SCANNER_STATE")  
filter.addCategory(Intent.CATEGORY_DEFAULT)

  3. Register the broadcast receiver instance with a Context. The usual place for this call would be in the onCreate method of a Service or an Activity class:

    context.registerReceiver(messageHandler, filter)

  4. Do not forget to unregister the receiver, for example in onDestroy, to avoid a memory leak, battery drain, etc.:

    context.registerReceiver(messageHandler, filter)

The passed Status String can be:

  • CONNECTED: Scanner is connected, you can start scanning.

  • DISCONNECTED: No scanner connected.

  • CONNECTING: In the process of establishing a scanner BLE connection.

  • ERROR: Something went wrong trying to establish the scanner connection or the BLE search. Consult the Insight Mobile app.

  • RECONNECTING: Lost connection to a previously connected scanner, trying to re-establish the connection.

  • SEARCHING: Searching for a scanner and showing the PAIRING Screen (including the QR code).

The examples above can be unified to one class handling all events by adding the other Action to the IntentFilter object. Then onReceive gets called for both kinds of events.

Connect a scanner

To start the scanner pairing process and show the QR activity, send a Broadcast Intent to:

  • Action: com.proglove.api.CONNECT

  • No Extras

Example 16. Example code:
val intent = Intent()  
intent.setAction("com.proglove.api.CONNECT")  
sendBroadcast(intent)


Note

On Android 8 or higher, this may fail because the Insight Mobile app is not running in the background. As a workaround, you can start the pairing process from the Insight Mobile app or using the code below.

val intent = Intent()
val component = ComponentName(
    "de.proglove.connect",
    "de.proglove.coreui.activities.PairingActivity"
)
intent.setComponent(component)
// Make sure to use the activity context here and not the application context.
context.startActivity(intent)

Note

On starting the PairingActivity, the scanner will be disconnected (which means the user has to pair again). However, you can check beforehand if the scanner is connected or disconnected by querying the scanner connection state.

This results in the scanner connection state broadcasts as listed above.

If there is no response, either the service is not running/started or the app is not installed.

In the case of no response you can still startActivity(PairingActivity) (in which case the user has to pair again).s

Disconnect a scanner

To disconnect a connected scanner, send a Broadcast Intent to:

  • Action: com.proglove.api.DISCONNECT

  • No Extras

Example code:

val intent = Intent()  
intent.setAction("com.proglove.api.DISCONNECT")  
sendBroadcast(intent)
Query scanner state

To query the connection state of the scanner, send a Broadcast Intent to:

  • Action: com.proglove.api.GET_SCANNER_STATE

  • No Extras

This triggers the com.proglove.api.SCANNER_STATE broadcast from the Insight Mobile app as explained in the Receive scanner connection state.

Example 17. Example code:
val intent = Intent()  
intent.setAction("com.proglove.api.GET_SCANNER_STATE")  
sendBroadcast(intent)


Note

To receive continuous scanner state updates, you can keep a registered broadcast receiver as explained in the Receive scanner connection state.

Start your app automatically with an action

To start your business application automatically with an action, Insight Mobile needs to send an Intent of the following structure:

  • Action: com.proglove.api.BARCODE_START_ACTIVITY

  • No Extras

To set this, when choosing the Intent integration, select the Start Activity with Action option and paste the above action or the one you use in your app as described Select the Intent integration path. You also need to implement the same action in your business application.

Add the following snippet to your application’s .XML file under activity. The action name can be modified, but the category name must be android.intent.category.DEFAULT.

<intent-filter>  
<action android:name="com.proglove.api.BARCODE_START_ACTIVITY"/>  
<category android:name="android.intent.category.DEFAULT"/>  
</intent-filter>

A default startActivity rule is created, which is pre-defined to start your business app with an action by an oncoming barcode event.

Start your app automatically with a component

To start your business application automatically with a component, Insight Mobile needs to send an Intent of the following structure:

  • Component Path - the name of the Activity class inside of Component Package that implements the component

  • Component Package - the name of the package that the component exists in.

To set this, when choosing the Intent integration, select the Start Activity with Component option and fill in the above parameters as described in Select the Intent integration path.

A default Integration Path: Intent rule is created, which is pre-defined to start your business app with a component after a barcode event.

Symbologies

For the list of supported Symbologies, see Symbology Settings.

In this section: