Blecon Scanner Developer Guide

Programatically obtain Blecon Device IDs using the Blecon Scanner

There are a number of scenarios where an application may need to obtain the device ID of a Blecon device. These include:

• Initial registration of the device to your organisation’s Blecon network

• Associating a device ID with that of a customer account

• Accessing or updating information about a device in the field given its device ID

Your application can take advantage of the Blecon Scanner to scan for and obtain device IDs without you having to implement custom scanning functionality.

Using the Blecon Scanner

The Blecon Scanner, which is included in Blecon’s mobile (iOS and Android) apps, allows external mobile apps and websites to programmatically request scans for Blecon devices and will return the ID of a device that the user has picked.

Overview of operation

To use the Blecon Scanner, mobile apps or web applications on the mobile device open the Blecon Scanner URL along with specific configuration parameters that include a callback URL (i.e., a webhook), to which the results of a scan will be returned.

Opening the Blecon Scanner URL launches the Blecon Scanner on the mobile device. The Blecon Scanner prompts a user to scan a Blecon device. When the user successfully selects a device (or cancels the operation), the Blecon Scanner passes the ID of the selected device back to the application by opening the supplied callback URL.

Example showing Blecon Console webapp launching the Scanner

The Blecon Console uses the Blecon Scanner API to collect Device IDs to register Blecon Devices onto a network

Blecon Scanner API

Launch the Blecon Scanner by opening the following URL and passing the callback parameter:

https://blecon.app/scanner?callback=<callbackURL>

Where callbackURL is an URL template which is a URL containing variable substitution expressions such as {device_id}, which the Blecon Scanner will replace with information that is collected when the Blecon Scanner is run. The URL that results after substitutions have been made is the location where Blecon Scanner should redirect the user once scanning is completed. The URL can be that of a website or a Universal Link (iOS) or App Link (Android) that launches an application on the device.

Example

To specify that the Blecon Scanner should open https://www.example.org such that ID of the device the user selects in the scanner is passed back in the device_id parameter of the querystring, the application would use the following URL template:

https://www.example.org?device_id={device_id}

The application must URL encode the URL template and pass it in under the callback querystring parameter when opening the Blecon Scanner URL. Thus, the link to launch the scanner, with the URL-encoded callback is:

https://blecon.app/scanner?callback=https%3A%2F%2Fwww.example.org%3Fdevice_id%3D%7Bdevice_id%7D

If the device scanned has ID urn:uuid:123e4567-e89b-12d3-a456-426655440000, the Blecon Scanner will redirect the user to https://www.example.org?device_id=urn:uuid:123e4567-e89b-12d3-a456-426655440000and if no device was detected or the scanner was cancelled the Blecon Scanner will open https://www.example.org?device_id=None

---

Supported Parameters when Launching the Scanner

Parameter	Description
callback	Location to return the user to after scanning has completed. Required

Supported variables in URL templates

Variable	Description
device_id	Selected device ID or “None” if no device was selected.

Additional examples of how to construct the callback URL

The above example demonstrated passing back the selected device ID as a querystring parameter. However, the URL template can be used to create other formats for the callback URL.

For instance:

• Including the device ID as part of the URL path, e.g.: https://www.example.org/{device_id}/

• Including additional data (e.g., unique session identifier, authorization token, etc.) alongside the returned data, e.g.: https://www.example.org/register?&data=foo&device_id={device_id}