-
Notifications
You must be signed in to change notification settings - Fork 1
Fing Android SDK
Using Fing’s developer tools is simple and straightforward on Android.
Create an app, access your unique Fing License Key and simply add the relevant frameworks for Fing integration. You can then initialise Fing and start a network scan.
The SDK is available as a public library on Jitpack, suitable to be used with the standard development tools (Android Studio) and to be published on the official Play Store.
As a framework, it may also be used by applications written in Kotlin language.
It is compatible with Android 5.0 and above.
The following dependencies will be added as FING SDK dependencies in your Gradle-based or Maven-based project:
| Group | Name | Version |
|---|---|---|
| androidx.appcompat | appcompat | 1.1.0 |
| androidx.coordinatorlayout | coordinatorlayout | 1.1.0 |
| com.google.android.material | material | 1.1.0 |
| com.google.android.gms | play-services-analytics | 17.0.0 |
| com.google.protobuf | protobuf-java | 2.6.1 |
| org.snmp4j | snmp4j | 2.5.0 |
| com.squareup.okhttp3 | okhttp | 4.8.0 |
Android Studio automatically includes the framework in the final package. Below is an excerpt of a Gradle build module that includes the library in the build system.
To get a Git project into your build:
Step 1. Add the JitPack repository to your build file
Add it in your root build.gradle at the end of repositories:
allprojects {
repositories {
jcenter()
google()
maven { url 'https://jitpack.io' }
}
}Step 2. Add the dependencies
dependencies {
implementation 'com.github.fingltd:devrecog:2.5.3'
}The functionalities are accessed via the main singleton class FingScanner.
Fing SDK operates asynchronously, to ensure your App is never blocked during each operation. A callback block is used to deliver the result of an operation, or the error object in case the operation could not be completed. All callback methods are invoked in the main thread.
public interface FingResultCallback {
void handle(String result, Exception error);
}| Parameter | Type | Description |
|---|---|---|
| result | String | The result coming from Fing. It may be nil/null if there is no result or if an error occurred. The result is usually in JSON format, but in general it depends on the type of operation |
| error | Exception | An error descriptor, in case the operation may not be completed. |
If successful, the completion callback result string contains a JSON-formatted result and a null error.
The execution of the scanning request must be initiated from main thread in foreground execution on both platforms.
Executing the activity from a scheduled background task on Android may lead to inconsistent states and errors.
To enable the functionalities delivered by the Fing SDK, you must first obtain a License Key. You can request a new key here
The validation requires access to the internet, and it shall be executed at every application session in order to activate the features; a missing or failed validation disables the features of the Fing SDK.
public void validateLicenseKey(String key, String token, FingResultCallback completion); | Parameter | Type | Required | Description |
|---|---|---|---|
| key | String | yes | The unique license key that enable the usage of Fing API. The key is used to identify the owner, assess the services that are enabled for a given license and to ensure the usage of the functionalities within the agreed terms. |
| token | String | no | A token generated by your App or by your backend services, that will be sent back to your remote services through a webhook. The purpose of the optional token is to allow you to recognize, if needed, the activation of a session using your license key. |
| completion | FingResultCalllback | no | A callback block that is invoked when the validation terminates. |
If successful, the callback contains a JSON-formatted result as described in the following table, and a null error.
| Key | Value | Example |
|---|---|---|
| kitLicenseId | Your license key | Will be the same value passed as parameter |
| kitCustomerId | Your unique customer identifier assigned on sign up. Usually, it’s your company or App name | ACME |
| expiryDate | The time at which the provided key expires, and a new key or new validation shall be performed | 2016/11/23 02:00:07 |
| state | The state of the license. It may be one of: [Ok, Suspended, Revoked] | Ok |
| grantDiscovery | A Boolean value indicating if the network discovery feature is granted by your license | true |
| grantEnrichment | A Boolean value indicating if a Fing Service enrichment is enabled. Enrichment provides additional results on top the local scan, such as device type recognition. | true |
| grantAccount | Deprecated feature. A Boolean value indicating if the ability to attach the App to an account is granted by your license. | true |
| usageToken | A token assigned to the running device for the present month | ABC123 |
| usageCounted | A Boolean value indicating if this validation was the first validation of the licensing period | true |
An example of the JSON result is reported below:
{
"kitLicenseId":"ABC123",
"kitCustomerId":"ACME2",
"expiryDate":"2016/12/30 00:00:00",
"state":"Ok",
"grantDiscovery":"true",
"grantEnrichment":"true",
"grantAccount": "false",
"usageToken": "ABC123",
"usageCounted": "false"
}Fing allows to conveniently retrieve network details from the Wi-Fi the device is connected to. The network details may be retrieved through the following method:
public void networkInfo(FingResultCallback completion);If successful, the callback contains a JSON-formatted result as described in the following table, and a null error:
{
"address": "192.168.0.0 ",
"netmask": 24,
"bssid": "AA:BB:CC:00:01:02",
"bssidIsLAA": true,
"bssidIsMasked": true,
"ssid": "My network",
"gatewayAddress":"192.168.0.1",
"dnsAddress": "192.168.0.1 ",
"hasConnectivity": true
}Starting from Android 8.1, geolocation permissions are required to access Wi-Fi details (BSSID and SSID). The hosting App must acquire coarse location permissions before attempting to execute the scan or retrieve the network info. If location permissions are not granted, the SDK may return a Locally Administered Address (usually 02:00:00:00:00:00). Hosting Apps can use the Boolean values “bssidIsLAA” and “bssidIsMasked” to respectively check
Below the description of any field:
| Key | Value | Example |
|---|---|---|
| address | The base IP address of the network | 192.168.0.0 |
| netmask | The netmask expressed as CIDR notation. It represents the number of bits that make up the subnet part, and consequently the remaining bits identify the host part | 24 |
| bssid | The BSSID, that is the MAC Address of the Access Point the device is connected to at the moment | AA:BB:CC:00:01:02 |
| bssidIsLAA | A Boolean indicating if the BSSID has been generated by the current device and therefore not representing a real MAC Address. It could be anonymized, randomized or masking the real address | true |
| bssidIsMasked | A Boolean indicating if the real MAC address has been masked with a fixed value, usually 02:00:00:00:00:00 | false |
| ssid | The name of the network, as assigned by the network administrator | My Network |
| gatewayAddress | The IP Address of the network gateway, if available | 192.168.0.1 |
| dnsAddress | The IP Address of the network DNS, if available | 192.168.0.1 |
| hasConnectivity | Discriminates if the current connection with the server has network connectivity | true |
This functionality is accessed via a single method that performs the scan and enrichment of data, if enabled. The scan is integrated with the Fing Device Recognition Service, based on the features and services enabled on your API key.
public void networkScan(FingScanOptions options, FingResultCallback completion);
public void networkScanStop(); Scan progress is delivered asynchronously to a completion handler, so that hosting Apps can be informed and display the progress of the execution.
The method “scan” accepts the following list of parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| options | FingScanOptions | false | The set of options to tune the network scan procedure. See Scan Options for details |
| completion | FingResultCallback | false | A callback block that is invoked when the validation terminates. The validation may check both locally and remotely the given key and report the result or an empty result with an error. |
The scan can be stopped at any time using the corresponding method networkScanStop; if the scan was not running at that time, nothing is performed. After the stop operation is requested, all pending updates and the enrichment update will be delivered to scan completion handler.
| Option | Type | Description |
|---|---|---|
| mReverseDnsEnabled | Boolean | Enables Reverse DNS |
| upnpEnabled | Boolean | Enables UPnP scan |
| bonjourEnabled | Boolean | Enables Bonjour scan |
| netbiosEnabled | Boolean | Enables NetBIOS scan |
| snmpEnabled | Bool/Boolean | Enables SNMP scan |
| maxNetworkSize | integer | Imposes a maximum network size |
| resultLevelScanInProgress | FingScanResultLevel | The level of results that shall be returned while the scan is in progress. One of NONE, SUMMARY, FULL. The default is value is NONE. |
| resultLevelScanCompleted | FingScanResultLevel | The level of results that shall be returned when the scan is complete. The default is value is SUMMARY. |
| resultLevelScanEnriched | FingScanResultLevel | The level of results that shall be returned when the scan is enriched. The default level is FULL. |
| outputFormat | String | The output format, expressed as MIME type. Currently only “application/json” is supported. |
Regardless of the platform being used, the Fing returns the same set of results in the requested format. At the moment, JSON format is supported, which allow an easy integration with any kind of hosting app or process. Since Android 10, local MAC address may not be retrieved for the local device and the scanned device and are therefore not reported in the JSON result.
This SDK still provide the list of real MAC address for the scanned devices!
For the current network, Fing will provide a JSON data structure describing the network details and analysed properties. This is the set of details returned at SUMMARY level.
| Key | Value | Example |
|---|---|---|
nodes_count |
The number of nodes found in the network | 12 |
nodes_up_count |
The number of nodes found online in the network. The state of network devices is preserved locally by the system and merged with the latest scan | 10 |
nodes_down_count |
The number of nodes found offline in the network. The state of network devices is preserved locally by the system and merged with the latest scan | 2 |
last_scan_timestamp |
The time of the last scan | 2016/11/23 02:00:07 |
network_short_address |
The network address, in CIDR format | 192.168.0.1/24 |
progress |
The progress of the scan, in percentage from 0 to 100 | 80 |
enriched |
A Boolean flag discriminating if this scan has been enriched by Fing Device Recognition service | true |
completed |
A Boolean flag discriminating if this scan completes the scan progress. Depending on the license and enrichment, the last scan report may come from as the last operation of the scan or as the last operation after the scan has completed | false |
This is the set of details returned at FULL level, in addition to all the details provided at SUMMARY level. This structure is contained in the “network” JSON key.
| Key | Value | Example |
|---|---|---|
last _change_timestamp |
The time of the last change | 2016/11/23 02:00:07 |
gateway_ip_address |
The IP address of the gateway | 192.168.0.1 |
gateway_mac_address |
The MAC address of the gateway | AB:00:DD:FF:01:CC |
address |
The network address | 192.16.0.0 |
address_type |
IPv4 or IPv6 | IPv4 |
dns_address |
The IP address of the DNS | 192.168.0.1 |
mask_prefix_length |
The netmask length applied by the scan engine, in bits | 24 |
original_prefix_length |
The netmask length as defined in the network, in bits | 22 |
name |
The network name from the Wi-Fi SSID, if any | My Network |
bssid_list |
A list of the access points BSSID | [“AB:00:DD:FF:01:CC”, “AB:00:DD:FF:01:CD”] |
time_zone |
The time zone of the scanning device | Europe/London |
If internet connection is available, the scan reports also additional details on the ISP connection and location. Some of these details may not be available, depending on the user’s connection.
| Key | Value | Example |
|---|---|---|
address |
The public IP address | 44.211.2.94 |
host_name |
The public host name | host.viacom.com |
country_code |
The 2-letters country code | UK |
country_code_3 |
The 3-letters country code | ITA |
country_name |
The name of the country | United States |
country_region_code |
The region code | LAZ |
country_region |
The region name | Tuscany |
country_city |
The city name Washington country_postal_code The latitude of the ISP point in decimal degrees | W10 5BN |
latitude |
The longitude of the ISP point in decimal degrees | 20.23123 |
longitude |
The time zone of the scanning device | -82.22938 |
isp_name |
The name of the Internet Service Provider | AT&T |
organization |
The name of the organization providing Internet Access | Your Local Building |
net_speed |
The nominal network speed | 40 Mbs |
For each identified device, Fing will provide a data structure describing the network details and analysed properties.
| Key | Value | Example |
|---|---|---|
best_name |
The best name of the device, evaluated from the names returned from the various protocols it replies to | “HP 2832”, “Marco’s iPhone” |
best_type |
A single type identifying its major role. It’s intended to be as brandless as possible | “Laptop”, “Mobile”, “Photo Camera”. best_category
|
best_make |
The name of the makers/vendor of the device. It may overlap with the manufacturer, but it may be also different in case the network interface (ETH, WIFI) is different. | “Apple”, “Belkin” (but not “Foxconn”) |
best_model |
The human-readable name of the model | “iPhone 5S”, “P9” |
is_family |
Flag advising if the model is a generic family rather than a specific model. | true |
best_os |
The name of the Operating system, when applicable | “iOS 9.3.2”, “Android 5.0.1”, “Windows 7” |
best_osver |
The version of the Operating system, when applicable | “7 Ultimate”, “10 Pro”, “Mojave” |
best_osbuild |
The build number of the Operating system, when applicable | “19D88”, “30.3454” |
recog_rank |
Rank value of the device recognition. Higher values indicate a more confident device recognition | 95 |
mac_address |
The MAC Address of the device that is currently using to connect to the network | “06:5c:89:c9:e7:d1” |
vendor |
The name of the company that is officially manufacturing the network interface (ETH or WIFI). Names are reviewed and optimized to be consistent | “Samsung”, “Apple”, “Lenovo” for major brands, but also “Foxconn” for manufacturers that registered their components directly |
ip_addresses |
The list of IP address assigned to the device in the current network. It may be multiple if the element is a network bridge or if it’s temporarily being assigned multiple addresses | “172.28.0.14” |
host_name |
The DNS name of the device | “mydevice.thissite.com” |
state |
Discriminates if the device is connected to the network or not. Can be “UP” or “DOWN” | “UP” |
first_seen_timestamp |
The timestamp the device was first discovered in this network | “2016-04-28 11:34:45” |
last_change_timestamp |
The timestamp the device changed the state (UP/DOWN) | “2016-04-28 11:34:45” |
In addition to general-purpose properties, Fing exports for NetBIOS the following JSON structure, contained in the “NetBIOS” JSON key.
| Property | Description | Example |
|---|---|---|
name |
The NetBIOS name is used to uniquely identify the NetBIOS services listening on the first IP address that is bound to an adapter. The NetBIOS name is also known as a NetBIOS computer name. | “MACBOOKPRO” |
domain |
A type of Fully qualified Domain Name. | “mypc.locallan” |
user |
An optional user name. Due to security concerns, this is rarely available in the standard implementation | “MARCO” |
In addition to general-purpose properties, Fing exports for Bonjour the following JSON structure, contained in the “bonjour” JSON key.
| Property | Description | Example |
|---|---|---|
name |
The Bonjour name the device publishes | “My MacBook” |
model |
The Bonjour model the device publishes | “SCD8291221”, “Apple TV4,5” |
os |
The Bonjour Operating System name the device publishes | “Linux 12.4” |
service_list |
A list of bonjour services published by the device | “_afpovertcp._tcp.local.” “_smb._tcp.local.” |
In addition to general-purpose properties, Fing exports for UPnP the following JSON structure, contained in the “upnp” JSON key.
| Property | Description | Example |
|---|---|---|
name |
The UPnP name the device publishes | “My MacBook” |
make |
The UPnP Make name the device publishes | “Samsung” |
model |
The UPnP Model the device publishes | “SCD8291221” |
type_list |
A list of UPnP device types published by the device | “urn:Belkin:device:controllee:1” |
service_list |
A list of UPnP services published by the device | “urn:Belkin:service:manufacture:1” “urn:Belkin:service:smartsetup:1” |
In addition to general-purpose properties, Fing exports for SNMP the following JSON structure, contained in the “snmp” JSON key.
| Property | Description | Example |
|---|---|---|
name |
The SNMP name the device publishes | “HP” |
description |
The SNMP description of the device | “Cisco IOS Software, C3750 Software (C3750-IPSERVICESK9-M), Version 12.2(46)SE” |
location |
The SNMP location of device | “North Corridor” |
contact |
The SNMP contact point | “[email protected]” |
sysoid |
The unique identifier of the device type | “1.3.6.1.4.1.9.1.516” |
In addition to general-purpose properties, Fing exports for DHCP the following JSON structure, contained in the “dhcp” JSON key.
| Property | Description | Example |
|---|---|---|
name |
The DHCP name the device publishes | “My MacBook” |
vendor |
The DHCP vendor | “Samsung” |