@capacitor-trancee/nearby

@capacitor-trancee/nearby

Uses Bluetooth LE to scan and advertise for nearby devices

Install

npm install @capacitor-trancee/nearby
npx cap sync

Example

Bluetooth

BLUETOOTH CORE SPECIFICATION Version 5.1 | Vol 3, Part A

4.22 LE CREDIT BASED CONNECTION REQUEST (CODE 0x14)

Configuration

Android

    <uses-permission
        android:name="android.permission.BLUETOOTH"
        android:maxSdkVersion="30" />
    <!-- https://developer.android.com/develop/connectivity/bluetooth/bt-permissions#discover-local-devices -->
    <uses-permission
        android:name="android.permission.BLUETOOTH_ADMIN"
        android:maxSdkVersion="30" />

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

    <uses-permission
        android:name="android.permission.ACCESS_COARSE_LOCATION"
        android:maxSdkVersion="28" />
    <uses-permission
        android:name="android.permission.ACCESS_FINE_LOCATION"
        android:maxSdkVersion="31"
        android:minSdkVersion="29"
        tools:ignore="CoarseFineLocation" />

    <!-- https://developer.android.com/develop/connectivity/bluetooth/bt-permissions#features -->
    <uses-feature
        android:name="android.hardware.bluetooth"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.bluetooth_le"
        android:required="true" />

These configuration values are available:

Prop	Type	Description	Since
endpointName	string	A human readable name for this endpoint, to appear on the remote device.	4.1.0
endpointInfo	string	Identifing information about this endpoint, to appear on the remote device. Note: maximum length is 14 bytes.	4.1.0
serviceID	ServiceID	An identifier to advertise your app to other endpoints. The serviceID value must uniquely identify your app. As a best practice, use the package name of your app (for example, com.example.myapp).	4.1.0

Examples

In capacitor.config.json:

{
  "plugins": {
    "Nearby": {
      "endpointName": "My App",
      "endpointInfo": "TXkgQXBw",
      "serviceID": "com.example.myapp"
    }
  }
}

In capacitor.config.ts:

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

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

const config: CapacitorConfig = {
  plugins: {
    Nearby: {
      endpointName: "My App",
      endpointInfo: "TXkgQXBw",
      serviceID: "com.example.myapp",
    },
  },
};

export default config;

API

• initialize(...)
• reset()
• startAdvertising(...)
• stopAdvertising()
• startDiscovering()
• stopDiscovering()
• connect(...)
• disconnect(...)
• sendPayload(...)
• status()
• checkPermissions()
• requestPermissions(...)
• addListener('onPermissionChanged', ...)
• addListener('onBluetoothStateChanged', ...)
• addListener('onEndpointFound', ...)
• addListener('onEndpointLost', ...)
• addListener('onEndpointConnected', ...)
• addListener('onEndpointDisconnected', ...)
• addListener('onPayloadReceived', ...)
• Interfaces
• Type Aliases
• Enums

initialize(...)

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

Initializes Nearby for advertising and discovering of endpoints.

Param	Type
options	InitializeOptions

Returns: Promise<InitializeResult>

Since: 4.1.0

reset()

reset() => Promise<void>

Stops and resets advertising and discovering of endpoints.

Since: 4.1.0

startAdvertising(...)

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

Starts advertising the local endpoint.

Param	Type
options	StartAdvertisingOptions

Since: 4.1.0

stopAdvertising()

stopAdvertising() => Promise<void>

Stops advertising the local endpoint.

Since: 4.1.0

startDiscovering()

startDiscovering() => Promise<void>

Starts discovering remote endpoints.

Since: 4.1.0

stopDiscovering()

stopDiscovering() => Promise<void>

Stops discovering remote endpoints.

Since: 4.1.0

connect(...)

connect(options: ConnectOptions) => Promise<void>

Param	Type
options	ConnectOptions

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.

Param	Type
options	DisconnectOptions

Since: 4.1.0

sendPayload(...)

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

Sends a Payload to a remote endpoint.

Param	Type
options	SendPayloadOptions

Since: 4.1.0

status()

status() => Promise<StatusResult>

Returns advertising and discovering status, and discovered endpoints.

Returns: Promise<StatusResult>

Since: 4.1.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check for the appropriate permissions to use Nearby.

Returns: Promise<PermissionStatus>

Since: 4.1.0

requestPermissions(...)

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

Request the appropriate permissions to use Nearby.

Param	Type
permissions	NearbyPermissions

Returns: Promise<PermissionStatus>

Since: 4.1.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.

Param	Type
eventName	'onPermissionChanged'
listenerFunc	(granted: boolean) => void

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

addListener('onBluetoothStateChanged', ...)

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

Called when state of Bluetooth has changed.

Param	Type
eventName	'onBluetoothStateChanged'
listenerFunc	(state: BluetoothState) => void

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

addListener('onEndpointFound', ...)

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

Called when a remote endpoint is discovered.

Param	Type
eventName	'onEndpointFound'
listenerFunc	EndpointFoundCallback

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

addListener('onEndpointLost', ...)

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

Called when a remote endpoint is no longer discoverable.

Param	Type
eventName	'onEndpointLost'
listenerFunc	EndpointLostCallback

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

addListener('onEndpointConnected', ...)

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

Called when a remote endpoint is connected.

Param	Type
eventName	'onEndpointConnected'
listenerFunc	EndpointConnectedCallback

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

addListener('onEndpointDisconnected', ...)

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

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

Param	Type
eventName	'onEndpointDisconnected'
listenerFunc	EndpointDisconnectedCallback

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

addListener('onPayloadReceived', ...)

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

Called when a Payload is received from a remote endpoint.

Param	Type
eventName	'onPayloadReceived'
listenerFunc	PayloadReceivedCallback

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

Interfaces

InitializeResult

Prop	Type	Description	Since
endpointID	EndpointID	A unique identifier for this endpoint.	4.1.0

InitializeOptions

Prop	Type	Description	Since
endpointName	string	A human readable name for this endpoint, to appear on the remote device.	4.1.0
endpointInfo	string	Identifing information about this endpoint, to appear on the remote device. Note: maximum length is 14 bytes.	4.1.0
serviceID	ServiceID	An identifier to advertise your app to other endpoints. The serviceID value must uniquely identify your app. As a best practice, use the package name of your app (for example, com.example.myapp).	4.1.0

StartAdvertisingOptions

Prop	Type	Description	Since
endpointInfo	string	Identifing information about this endpoint. Note: maximum length is 14 bytes.	4.1.0

ConnectOptions

Prop	Type	Description	Since
endpointID	EndpointID	The identifier for the remote endpoint to connect to.	4.1.0

DisconnectOptions

Prop	Type	Description	Since
endpointID	EndpointID	The identifier for the remote endpoint to disconnect from.	4.1.0

SendPayloadOptions

Prop	Type	Description	Since
endpointID	EndpointID	The identifier for the remote endpoint to which the payload should be sent.	4.1.0
endpointIDs	string[]	The identifiers for the remote endpoints to which the payload should be sent.	4.1.0
payload	string	The Payload to be sent.	4.1.0

StatusResult

Prop	Type
isAdvertising	boolean
isDiscovering	boolean

PermissionStatus

Prop	Type	Description	Since
bluetooth	PermissionState	BLUETOOTH_ADVERTISE Required to be able to advertise to nearby Bluetooth devices. BLUETOOTH_CONNECT Required to be able to connect to paired Bluetooth devices. BLUETOOTH_SCAN Required to be able to discover and pair nearby Bluetooth devices. BLUETOOTH Allows applications to connect to paired bluetooth devices. BLUETOOTH_ADMIN Allows applications to discover and pair bluetooth devices.	4.1.0
location	PermissionState	ACCESS_FINE_LOCATION Allows an app to access precise location. ACCESS_COARSE_LOCATION Allows an app to access approximate location.	4.1.0

NearbyPermissions

Prop	Type
permissions	NearbyPermissionType[]

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

Endpoint

Prop	Type	Description	Since
endpointID	EndpointID	The ID of the remote endpoint that was discovered.	4.1.0
endpointName	string	A human readable name for this endpoint.	4.1.0
endpointInfo	string	Identifing information about this endpoint. Note: maximum length is 14 bytes.	4.1.0

Payload

A Payload sent between devices.

Prop	Type	Description	Since
payload	string	Payload data.	4.1.0

Type Aliases

EndpointID

Used to represent an endpoint.

string

ServiceID

Used to represent a service identifier.

string

PermissionState

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

NearbyPermissionType

'bluetooth' | 'location'

EndpointFoundCallback

Called when a remote endpoint is discovered.

(_: Endpoint): void

EndpointLostCallback

Called when a remote endpoint is no longer discoverable.

(_: Endpoint): void

EndpointConnectedCallback

Called when a remote endpoint is connected.

(_: Endpoint): void

EndpointDisconnectedCallback

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

(_: Endpoint): 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

Enums

BluetoothState

Members	Value	Description	Since
UNKNOWN	'unknown'	The manager’s state is unknown.	1.0.0
RESETTING	'resetting'	A state that indicates the connection with the system service was momentarily lost.	1.0.0
UNSUPPORTED	'unsupported'	A state that indicates this device doesn’t support the Bluetooth low energy central or client role.	1.0.0
UNAUTHORIZED	'unauthorized'	A state that indicates the application isn’t authorized to use the Bluetooth low energy role.	1.0.0
POWERED_OFF	'poweredOff'	A state that indicates Bluetooth is currently powered off.	1.0.0
POWERED_ON	'poweredOn'	A state that indicates Bluetooth is currently powered on and available to use.	1.0.0