@capacitor-trancee/nearby

v4.1.0

Published

a year ago

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

0High
0Medium
0Low

trancee

capacitor plugin native

@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)

LE Protocol/Service Multiplexer - LE_PSM

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(...)

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 |