# NordicID.NurApi.Android

> Generated: 2026-05-06 07:29 UTC  
> Package version: `5.0.2`

## Guide

## Overview

`NordicID.NurApi.Android` is a support library that extends `NordicID.NurApi.Net`
with Bluetooth Low Energy (BLE) and USB transport capabilities for Android. It
enables discovery and connection to Nordic ID RFID readers over BLE and USB on
Android devices.

Install it from NuGet:

```
dotnet add package NordicID.NurApi.Android
```

### Supported platforms

- Android (Xamarin & .NET MAUI)

### Transports

This library registers three transport schemes:

| Scheme | Transport | URI example |
|---|---|---|
| `ble` | Bluetooth Low Energy | `ble://AABBCCDDEEFF?name=Nordic%20ID%20Reader` |
| `usb` | USB (CDC ACM) | `usb://3592/dev/bus/usb/001/002?name=NUR%203` |
| `int` | Integrated reader | `int://integrated_reader?name=Integrated reader` |

The `int` scheme is automatically registered on Nordic ID Android-based handheld
readers (manufacturer contains "nordicid"). It provides access to the built-in
RFID module.

For BLE URIs, only the MAC address (without colons) is required for connecting.
For USB URIs, the device path after the vendor ID is used to identify the device.
The `name` query parameter is added by discovery for display purposes.

### Sample projects

- [`maui_nur_app_template`](https://github.com/NordicID/maui_nur_app_template) — .NET MAUI multiplatform sample (Android + iOS)
- [`rfiddemo_xamarin`](https://github.com/NordicID/rfiddemo_xamarin) — Xamarin RFID demo (Android, iOS, UWP)

### Prerequisites

- `NordicID.NurApi.Net` must be installed.
- The Android manifest must declare Bluetooth and USB permissions (see below).
- BLE scanning and USB device access also require **runtime permissions** to be
  requested before calling discovery / connect. The library does not request
  these for you.

#### Required manifest entries

Add the following to `AndroidManifest.xml`:

```xml
<!-- Legacy Bluetooth permissions for Android 11 (API 30) and earlier -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_PRIVILEGED" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- Bluetooth permissions for Android 12 (API 31) and newer -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<!-- Required hardware features and USB permission -->
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
<uses-feature android:name="android.hardware.usb.host" android:required="true" />
<uses-permission android:name="android.permission.USB_PERMISSION" />
```

#### Runtime permissions

- **BLE**: Request `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` (Android 12+) or
  `ACCESS_FINE_LOCATION` (older) at runtime before starting discovery.
- **USB**: After discovery, request per-device permission with
  `NurApiUSBDevicePermissionRequest.Request(uri, callback)` before connecting.
  If `Connect()` is called without permission, a `NurApiPermissionException` is
  thrown.

## Initialization and Usage

### Initialization

Initialize the Android support once during application startup. The `Init`
method requires an Android `Context` parameter.

In **.NET MAUI**, call `Init()` in `MauiProgram.cs` (`CreateMauiApp`):

```csharp
#if __ANDROID__
NurApiDotNet.Android.Support.Init(
    Microsoft.Maui.ApplicationModel.Platform.AppContext);
#endif
```

In **Xamarin**, call it in `MainActivity.OnCreate`:

```csharp
protected override void OnCreate(Bundle savedInstanceState)
{
    base.OnCreate(savedInstanceState);
    NurApiDotNet.Android.Support.Init(this);
}
```

This registers the `ble://`, `usb://`, and (on Nordic ID devices) `int://`
transport schemes and their device discovery providers.

### Device Discovery

After initialization, use `NurDeviceDiscovery` to find devices.

#### 1. Create a discovery callback

```csharp
var callback = new NurDeviceDiscoveryCallback((sender, args) =>
{
    Console.WriteLine($"Found device: {args.Uri}");
});
```

#### 2. Start discovery

```csharp
NurDeviceDiscovery.Start(callback);
```

To discover only a specific transport type:

```csharp
NurDeviceDiscovery.Start(callback, new string[] { "ble" }); // BLE only
NurDeviceDiscovery.Start(callback, new string[] { "usb" }); // USB only
```

#### 3. Connect using the discovered URI

```csharp
var api = new NurApi();

var callback = new NurDeviceDiscoveryCallback((sender, args) =>
{
    api.Connect(args.Uri);
});

NurDeviceDiscovery.Start(callback);
```

### USB Auto-Connect

USB supports an auto-connect URI that handles discovery and reconnection
automatically:

```csharp
var api = new NurApi();
api.Connect("usb://autoconnect");
```

### Requesting USB device permission

USB devices on Android require per-device user permission. Request it before
connecting:

```csharp
NurApiUSBDevicePermissionRequest.Request(args.Uri, granted =>
{
    if (granted)
    {
        api.Connect(args.Uri);
    }
});
```

If `Connect()` is called without permission, a `NurApiPermissionException` is
thrown.

### Monitoring connection status

```csharp
api.ConnectionStatusEvent += (sender, status) =>
{
    Console.WriteLine($"Connection status: {status}");
};
```