@capacitor-trancee/nearby-connections v0.2.6

@capacitor-trancee/nearby-connections

Uses Nearby Connections peer-to-peer networking API that allows apps to easily discover, connect to, and exchange data with nearby devices in real-time, regardless of network connectivity

Install

npm install @capacitor-trancee/nearby-connections
npx cap sync

iOS

Nearby Connections needs access to both Bluetooth and the local network to advertise, discover, make connections, and transfer data. Provide a usage description for each resource needed, in your app’s Info.plist. If you don’t, attempts to access the resource will fail, and might even cause your app to crash.

Required usage description keys:

• NSBluetoothAlwaysUsageDescription

  <key>NSBluetoothAlwaysUsageDescription</key>
  <string>${PRODUCT_NAME} uses Bluetooth to discover nearby devices.</string>

• NSLocalNetworkUsageDescription

  <key>NSLocalNetworkUsageDescription</key>
  <string>${PRODUCT_NAME} uses the local network to discover nearby devices on your WiFi network.</string>

In addition to usage description keys, an NSBonjourServices key with a list of the service types that will be browsed by the app, will also need to be added. The only service type that must be added can be generated by taking the first 12 bytes of the SHA-256 hash of your app's service ID.

Read about Configuring Info.plist in the iOS Guide for more information on setting iOS permissions in Xcode

Android

Before using Nearby Connections, your app must request the appropriate permissions. Add the following permissions to your AndroidManifest.xml:

    <!-- https://developers.google.com/nearby/connections/android/get-started#request_permissions -->

    <!-- Required for Nearby Connections -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

    <uses-permission
        android:name="android.permission.BLUETOOTH"
        android:maxSdkVersion="30" />
    <uses-permission
        android:name="android.permission.BLUETOOTH_ADMIN"
        android:maxSdkVersion="30" />

    <uses-permission
        android:name="android.permission.ACCESS_COARSE_LOCATION"
        android:maxSdkVersion="32" />
    <uses-permission
        android:name="android.permission.ACCESS_FINE_LOCATION"
        android:maxSdkVersion="32" />

    <uses-permission
        android:name="android.permission.BLUETOOTH_ADVERTISE" />
    <uses-permission
        android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission
        android:name="android.permission.BLUETOOTH_SCAN"
        android:usesPermissionFlags="neverForLocation"
        tools:targetApi="s" />

    <uses-permission
        android:name="android.permission.NEARBY_WIFI_DEVICES"
        android:usesPermissionFlags="neverForLocation"
        tools:targetApi="s" />

    <!-- Optional: only required for FILE payloads -->
    <uses-permission
        android:name="android.permission.READ_EXTERNAL_STORAGE"
        tools:ignore="ScopedStorage" />

    <uses-feature
        android:name="android.hardware.bluetooth_le"
        android:required="false" />

If the user does not grant all required permissions, the Nearby Connections API will refuse to allow your app to start advertising or discovering.

Read about Setting Permissions in the Android Guide for more information on setting Android permissions.

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

• playServicesNearbyVersion version of com.google.android.gms:play-services-nearby (default: 19.3.0)

• playServicesLocationVersion version of com.google.android.gms:play-services-location (default: 21.3.0)

• protoliteWellKnownTypesVersion version of com.google.firebase:protolite-well-known-types (default: 18.0.0)

Example

Configuration

These configuration values are available:

Examples

In capacitor.config.json:

{
  "plugins": {
    "NearbyConnections": {
      "endpointName": "My App",
      "serviceID": "com.example.myapp",
      "strategy": Strategy.STAR,
      "connectionType": ConnectionType.BALANCED,
      "lowPower": true,
      "autoConnect": true,
      "payload": "Hello, World!"
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor-trancee/nearby-connections" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    NearbyConnections: {
      endpointName: "My App",
      serviceID: "com.example.myapp",
      strategy: Strategy.STAR,
      connectionType: ConnectionType.BALANCED,
      lowPower: true,
      autoConnect: true,
      payload: "Hello, World!",
    },
  },
};

export default config;

API

• initialize(...)
• reset()
• startAdvertising(...)
• stopAdvertising()
• startDiscovery(...)
• stopDiscovery()
• requestConnection(...)
• acceptConnection(...)
• rejectConnection(...)
• disconnect(...)
• sendPayload(...)
• cancelPayload(...)
• status()
• checkPermissions()
• requestPermissions(...)
• addListener('onPermissionChanged', ...)
• addListener('onBluetoothStateChanged', ...)
• addListener('onEndpointFound', ...)
• addListener('onEndpointLost', ...)
• addListener('onEndpointInitiated', ...)
• addListener('onEndpointConnected', ...)
• addListener('onEndpointRejected', ...)
• addListener('onEndpointFailed', ...)
• addListener('onEndpointDisconnected', ...)
• addListener('onEndpointBandwidthChanged', ...)
• addListener('onPayloadReceived', ...)
• addListener('onPayloadTransferUpdate', ...)
• Interfaces
• Type Aliases
• Enums

initialize(...)

initialize(options?: InitializeOptions | undefined) => Promise<void>

Initializes Nearby Connections for advertising and discovering of endpoints.

Since: 1.0.0

reset()

reset() => Promise<void>

Stops and resets advertising and discovering of endpoints.

Since: 1.0.0

startAdvertising(...)

startAdvertising(options?: StartAdvertisingOptions | undefined) => Promise<void>

Starts advertising the local endpoint.

Since: 1.0.0

stopAdvertising()

stopAdvertising() => Promise<void>

Stops advertising the local endpoint.

Since: 1.0.0

startDiscovery(...)

startDiscovery(options?: StartDiscoveryOptions | undefined) => Promise<void>

Starts discovery for remote endpoints.

Since: 1.0.0

stopDiscovery()

stopDiscovery() => Promise<void>

Stops discovery for remote endpoints.

Since: 1.0.0

requestConnection(...)

requestConnection(options: RequestConnectionOptions) => Promise<void>

Sends a request to connect to a remote endpoint.

Since: 1.0.0

acceptConnection(...)

acceptConnection(options: AcceptConnectionOptions) => Promise<void>

Accepts a connection to a remote endpoint.

Since: 1.0.0

rejectConnection(...)

rejectConnection(options: RejectConnectionOptions) => Promise<void>

Rejects a connection to a remote endpoint.

Since: 1.0.0

disconnect(...)

disconnect(options: DisconnectOptions) => Promise<void>

Disconnects from a remote endpoint. Payloads can no longer be sent to or received from the endpoint after this method is called.

sendPayload(...)

sendPayload(options: SendPayloadOptions) => Promise<SendPayloadResult>

Sends a Payload to a remote endpoint.

Returns: Promise<SendPayloadResult>

Since: 1.0.0

cancelPayload(...)

cancelPayload(options: CancelPayloadOptions) => Promise<void>

Cancels a Payload currently in-flight to or from remote endpoint(s).

Since: 1.0.0

status()

status() => Promise<StatusResult>

Returns advertising and discovering status, and discovered endpoints.

Returns: Promise<StatusResult>

Since: 1.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check for the appropriate permissions to use Nearby.

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions(...)

requestPermissions(permissions?: NearbyConnectionsPermissions | undefined) => Promise<PermissionStatus>

Request the appropriate permissions to use Nearby.

Returns: Promise<PermissionStatus>

Since: 1.0.0

addListener('onPermissionChanged', ...)

addListener(eventName: 'onPermissionChanged', listenerFunc: (granted: boolean) => void) => Promise<PluginListenerHandle>

Called when permission is granted or revoked for this app to use Nearby.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onBluetoothStateChanged', ...)

addListener(eventName: 'onBluetoothStateChanged', listenerFunc: (state: BluetoothState) => void) => Promise<PluginListenerHandle>

Called when state of Bluetooth has changed.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onEndpointFound', ...)

addListener(eventName: 'onEndpointFound', listenerFunc: EndpointFoundCallback) => Promise<PluginListenerHandle>

Called when a remote endpoint is discovered.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onEndpointLost', ...)

addListener(eventName: 'onEndpointLost', listenerFunc: EndpointLostCallback) => Promise<PluginListenerHandle>

Called when a remote endpoint is no longer discoverable.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onEndpointInitiated', ...)

addListener(eventName: 'onEndpointInitiated', listenerFunc: EndpointInitiatedCallback) => Promise<PluginListenerHandle>

A basic encrypted channel has been created between you and the endpoint. Both sides are now asked if they wish to accept or reject the connection before any data can be sent over this channel.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onEndpointConnected', ...)

addListener(eventName: 'onEndpointConnected', listenerFunc: EndpointConnectedCallback) => Promise<PluginListenerHandle>

Called after both sides have accepted the connection. Both sides may now send Payloads to each other.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onEndpointRejected', ...)

addListener(eventName: 'onEndpointRejected', listenerFunc: EndpointRejectedCallback) => Promise<PluginListenerHandle>

Called when either side rejected the connection. Payloads can not be exchaged.

Returns: Promise<PluginListenerHandle>

addListener('onEndpointFailed', ...)

addListener(eventName: 'onEndpointFailed', listenerFunc: EndpointFailedCallback) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener('onEndpointDisconnected', ...)

addListener(eventName: 'onEndpointDisconnected', listenerFunc: EndpointDisconnectedCallback) => Promise<PluginListenerHandle>

Called when a remote endpoint is disconnected or has become unreachable.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onEndpointBandwidthChanged', ...)

addListener(eventName: 'onEndpointBandwidthChanged', listenerFunc: EndpointBandwidthChangedCallback) => Promise<PluginListenerHandle>

Called when a connection is established or if the connection quality improves to a higher connection bandwidth.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onPayloadReceived', ...)

addListener(eventName: 'onPayloadReceived', listenerFunc: PayloadReceivedCallback) => Promise<PluginListenerHandle>

Called when a Payload is received from a remote endpoint.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('onPayloadTransferUpdate', ...)

addListener(eventName: 'onPayloadTransferUpdate', listenerFunc: PayloadTransferUpdateCallback) => Promise<PluginListenerHandle>

Called with progress information about an active Payload transfer, either incoming or outgoing.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

Interfaces

InitializeOptions

StartAdvertisingOptions

StartDiscoveryOptions

RequestConnectionOptions

AcceptConnectionOptions

RejectConnectionOptions

DisconnectOptions

SendPayloadResult

SendPayloadOptions

CancelPayloadOptions

StatusResult

PermissionStatus

NearbyConnectionsPermissions

PluginListenerHandle

Endpoint

ConnectionInfo

Information about a connection that is being initiated.

BandwidthInfo

Information about a connection's bandwidth.

Payload

A Payload sent between devices.

PayloadTransferUpdate

Describes the status for an active Payload transfer, either incoming or outgoing.

Type Aliases

ServiceID

Used to represent a service identifier.

string

EndpointID

Used to represent an endpoint.

string

PayloadID

Used to represent a payload.

number

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

NearbyConnectionPermissionType

'wifiNearby' | 'wifiState' | 'bluetoothNearby' | 'bluetoothLegacy' | 'location' | 'locationCoarse'

EndpointFoundCallback

Called when a remote endpoint is discovered.

(_: Endpoint): void

EndpointLostCallback

Called when a remote endpoint is no longer discoverable.

(_: Endpoint): void

EndpointInitiatedCallback

A basic encrypted channel has been created between you and the endpoint. Both sides are now asked if they wish to accept or reject the connection before any data can be sent over this channel.

(_: Endpoint & ConnectionInfo): void

EndpointConnectedCallback

Called after both sides have accepted the connection. Both sides may now send Payloads to each other.

(_: Endpoint): void

EndpointRejectedCallback

Called when either side rejected the connection. Payloads can not be exchaged.

(_: Endpoint): void

EndpointFailedCallback

(_: Endpoint & Status): void

EndpointDisconnectedCallback

Called when a remote endpoint is disconnected or has become unreachable. At this point service (re-)discovery may start again.

(_: Endpoint): void

EndpointBandwidthChangedCallback

Called when a connection is established or if the connection quality improves to a higher connection bandwidth.

(_: Endpoint & BandwidthInfo): void

PayloadReceivedCallback

Called when a payload is received from a remote endpoint. Depending on the type of the payload, all of the data may or may not have been received at the time of this call.

(_: Endpoint & Payload): void

PayloadTransferUpdateCallback

Called with progress information about an active payload transfer, either incoming or outgoing.

(_: Endpoint & PayloadTransferUpdate): void

Enums

Strategy

ConnectionType

PayloadType

PayloadTransferUpdateStatus

BluetoothState

Status

Quality