Plugin.Maui.NearbyConnectivity 1.0.0-preview.1

Plugin.Maui.NearbyConnectivity

Plugin.Maui.NearbyConnectivity provides the ability to discover, connect to, and exchange data with nearby devices that run your .NET MAUI application, without a server or an internet connection.

Features

• Discovery. Advertise to nearby devices, and discover the devices that advertise the same ServiceId. Read them from Devices, or handle DeviceChanged.
• Connection consent. Answer each inbound connection request with AcceptAsync or DeclineAsync, or call SetConsent to set a policy that answers for you. An unanswered request times out.
• Bytes, files, and streams. Send byte payloads up to 32 KiB, files with progress reporting, and streams (experimental, opt in with NEARBY001). Receive payloads from every connection in one await foreach loop. Received files are staged in the app's cache directory until you move or dispose them.
• Presence. Advertise a display name of up to 63 UTF-8 bytes and up to 57 bytes of app-defined data. Both are broadcast unencrypted to nearby devices before a connection exists.
• Encrypted connections. Every connection is encrypted on both platforms. Each one exposes a six-digit AuthenticationCode that users compare out of band to detect a man-in-the-middle.
• Bindable types. NearbyDeviceCollection implements INotifyCollectionChanged, and NearbySessionState implements INotifyPropertyChanged. Both raise their events on the UI thread, so XAML binds to them directly.
• Permissions and availability. NearbyPermission works with Permissions.RequestAsync<T>() and covers every Android runtime permission the plugin needs. CheckAvailabilityAsync reports Bluetooth or Wi-Fi turned off, missing Google Play services, or a missing Info.plist entry.
• Trimming and Native AOT. The library is compatible with both.
• Logging. The plugin logs through ILogger with a stable EventId for each message. It registers no logging provider and sends no telemetry.

Supported platforms

No cross-platform connections. Android connects only to Android, and iOS only to iOS. On iOS, the plugin stops the session when the app enters the background. On Android, a connection lives as long as the process, so it survives backgrounding only if your app runs a foreground service. See Platform behavior.

Install

dotnet add package Plugin.Maui.NearbyConnectivity

Android needs no manifest changes. iOS needs two Info.plist keys. See Set up Android and iOS.

This package replaces Plugin.Maui.NearbyConnections. The 0.x previews under that name are deprecated and receive no fixes.

Usage

Register the plugin

Register the plugin in MauiProgram.cs. Devices discover each other only when they use the same ServiceId.

builder.AddNearbyConnectivity(options => options.ServiceId = "nearbyminimal");

AddNearbyConnectivity registers INearbyConnectivity as a singleton. Inject it, or use NearbyConnectivity.Default where constructor injection is not available. The same method exists on IServiceCollection for a host without a MauiAppBuilder, such as a unit test.

Request permission and start

Advertising and discovery do not start automatically.

if (await Permissions.RequestAsync<NearbyPermission>() != PermissionStatus.Granted)
{
    return;
}

nearbyConnectivity.Advertiser.SetConsent(NearbyConsentPolicy.AcceptAll);
await nearbyConnectivity.Advertiser.StartAsync();
await nearbyConnectivity.Discoverer.StartAsync();

AcceptAll accepts every inbound request without a prompt, so use it only in a demo. To prompt the user instead, see Accept and make connections.

Send a message

Pick a NearbyDevice from nearbyConnectivity.Devices, call ConnectAsync, and send on the returned NearbyConnection.

var connection = await device.ConnectAsync();
await connection.SendAsync("Hello"u8.ToArray());

Receive messages

PayloadsAsync merges the inbound payloads from every connection into one IAsyncEnumerable. The stream is single-consumer, so enumerate it in one place.

await foreach (var (sender, payload) in nearbyConnectivity.PayloadsAsync(cancellationToken))
{
    using (payload)
    {
        if (payload is NearbyBytesPayload bytes)
        {
            var text = Encoding.UTF8.GetString(bytes.Data.Span);
            Console.WriteLine($"{sender.Presence.DisplayName}: {text}");
        }
    }
}

These snippets follow samples/Minimal, the app from the Get started tutorial.

Documentation

• Get started builds a working two-device app in eight steps.
• How-to guides: Accept and make connections, Send and receive payloads, Show a presence before connecting, Bind to a MAUI page, Test code that uses the plugin, Troubleshooting, and Turn on logging.
• Security and Platform behavior document the plugin's limitations. Read both before you ship.
• API reference and Options and limits
• Samples: NearbyChat shows consent prompts with a countdown, authentication code checks before the first send, presence avatars, file transfer with cancel and retry, and an Android foreground service that keeps connections open in the background.

Feedback and contributing

Issues and pull requests are welcome. See CONTRIBUTING.md. Ask questions in Discussions. Report bugs and request features with the issue forms.

Report vulnerabilities privately through SECURITY.md. Do not open a public issue.

Licensed under the MIT License.

Acknowledgements

This plugin started from Gerald Versluis's Plugin.Maui.Feature template.