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), 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:

How to select the Intent integration path

Prerequisite: Insight Webportal account activated.

Go to Insight Webportal.
At the top, under Device Visibility, select Configurations.
The list of existing configurations displays.
At the bottom of the page, select Create New Configuration.

Note: Alternatively, you can 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, 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 Symbologies 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.

How to receive barcode data

To receive broadcast Intents:

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

KOTLIN

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:

KOTLIN

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:

KOTLIN

context.registerReceiver(messageHandler, filter)

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

KOTLIN

context.unregisterReceiver(messageHandler)

How to 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

How to 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 connection state events:

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

KOTLIN

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:

KOTLIN

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:

KOTLIN

context.registerReceiver(messageHandler, filter)

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

KOTLIN

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.

How to 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 code:

KOTLIN

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.

KOTLIN

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

How to disconnect a scanner

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

Action: com.proglove.api.DISCONNECT
No Extras

Example code:

KOTLIN

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

How to query scanner connection state

To query the scanner connection state, 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 section above.

Example code:

KOTLIN

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

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

How to start your application automatically with an action

To start your 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 above.
You also need to implement the same action in your 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 application with an action by an oncoming barcode event.

How to start your application automatically with a component

To start your 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 above.

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

Symbologies

For the list of supported symbologies, see Symbologies.

Intent API - basic integration

How to select the Intent integration path

Barcode scan Intent structure

How to receive barcode data

How to receive scans with startActivity()

Logging/Output

How to receive scanner connection state

How to connect a scanner

How to disconnect a scanner

How to query scanner connection state

How to start your application automatically with an action

How to start your application automatically with a component

Symbologies

How to receive scans with `startActivity()`