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.

On Insight Webportal, under Device Visibility, select Configurations.
The list of existing configurations displays.
At the top right, click the icon to add a configuration.
Note
You can also click the pencil icon next to an existing configuration to modify it.
Select Insight Mobile (Android).
Click Next.
Click Select Connectivity Settings.
The Integration Path section displays with Software Keyboard, Intent, WebSocket, and SDK options.
Under Integration Path, select Intent.
Under Intent Type, select the desired type: Broadcast Intent, Start Activity with Action, or Start Activity with Component.
Enter the Intent Action or Component Path and Component Package.
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:

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")
        }
    }
}

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)

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 is no longer reliable. To bypass this, you have to grant a system permissions to the INSIGHT Mobile (Android) app and allow it to run and activate over other apps that are running in the foreground. Depending on the Android version, this permission can be found as either Appear on top, or Display over other apps.

To learn more, see Restrictions on starting activities from the background and also required permissions for INSIGHT Mobile.

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:

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")  
        }  
    }  
}

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)

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)
```
Do not forget to unregister the receiver, for example in onDestroy, to avoid a memory leak, battery drain, etc.:
```
context.unregisterReceiver(messageHandler)
```

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, start the pairing activity from Insight Mobile with an explicit Intent and no extras:

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)

You can also start the scanner pairing process by sending a Broadcast Intent with the com.proglove.api.CONNECT action and no extras.

Note

On Android 8 or higher, this may fail because the Insight Mobile app is not running in the background.

val intent = Intent()  
intent.setAction("com.proglove.api.CONNECT")  
sendBroadcast(intent)

Caution

On Android 10 or higher, sending a Broadcast Intent with the com.proglove.api.CONNECT action will not work due to the restrictions on starting activities from the background.

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).

Activate a photo session

Use Intent to invoke a photo session activity on your ProGlove scanners and capture a photo report. You can immediately define the title and description of your report using the command listed below. Once completed, each report is sent to the INSIGHT webportal for review. See here for more about working with photo reports.

To activate a photo session, use the following:

adb shell am start -n de.proglove.connect/.app.photo.PhotoSessionActivity

To activate a photo session with a title and description, use:

adb shell am start -n de.proglove.connect/.app.photo.PhotoSessionActivity --es title "Test\ Title" --es description "Test\ Description"

Note

All whitespace characters need to be escaped with a backslash "\" when using the above adb commands.

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 55. Example code:

val intent = Intent()  
intent.setAction("com.proglove.api.GET_SCANNER_STATE")  
sendBroadcast(intent)

To query the details of both your scanner and the connected Android device when using the INSIGHT Visibility subscription plan, send the following Intent:

Action: com.proglove.api.OBTAIN_DEVICE_VISIBILITY_INFO
No Extras

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:

ProGlove Documentation

Intent API - basic integration

Important

Select the Intent integration path

Note

Barcode scan Intent structure

Note

Receive barcode data

Note

Receive scans with startActivity()

Note

Logging/Output

Receive scanner connection state

Connect a scanner

Note

Caution

Activate a photo session

Note

Disconnect a scanner

Query scanner state

Note

Start your app automatically with an action

Start your app automatically with a component

Symbologies

Search results

Receive scans with `startActivity()`