Nearby connections is a 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.
This new API uses a combination of WiFi hotspots, Bluetooth Low Energy & Classic Bluetooth to discover and advertise to nearby devices. Connections between devices are high-bandwidth, low-latency, and fully encrypted to enable fast secure data transfers.
As a convenience, users are not prompted to turn on Bluetooth or Wi-Fi Nearby Connections enables these features as they are required, and restores the device to its prior state once the app is done using the API, ensuring a smooth user experience.
The API is located in thecom.google.android.gms.nearby.connection
package.
one of the use cases of using Nearby connection API is Offline file transfers you can share photos, videos, or any other type of data quickly and without requiring a network connection.
Strategies
Nearby Connections supports different Strategies for advertising and discovery. The best Strategy
to use depends on the use case. Detail description of each and every strategy can be found here.
P2P_CLUSTER
P2P_CLUSTER
is a peer-to-peer strategy that supports an M-to-N, In other words, this enables connecting amorphous clusters of devices within radio range (~100m), where each device can both initiate outgoing connections to other devices and accept incoming connections from other devices.
P2P_STAR
P2P_STAR
is a peer-to-peer strategy that supports a 1-to-N, or star-shaped, connection topology. In other words, this enables connecting devices within radio range (~100m) in a star shape, where each device can, at any given time, play the role of either a hub (where it can accept incoming connections from N other devices), or a spoke (where it can initiate an outgoing connection to a single hub), but not both.
For example, a classroom app where the teacher wants to host a quiz for all the students, that would probably be best mounted over P2P_STAR
with the teacher as the one advertiser and the students at the end discovers
P2P_POINT_TO_POINT
P2P_POINT_TO_POINT
is a peer-to-peer strategy that supports a 1-to-1 connection topology. In other words, this enables connecting devices within radio range (~100m) with the highest possible throughput, but does not allow for more than a single connection at a time. It is good for high-bandwidth use cases such as sharing a large video to another device.
To explore this API I have created small POC which will transfer messages from one device to another using Nearby Connection API.
Workflow
we require 2 devices A and B, device A will advertise and Device B will discover nearby advertiser.
compile ‘com.google.android.gms:play-services-nearby:15.0.0’
Permission required
<uses-permission android:name=”android.permission.BLUETOOTH” /> <uses-permission android:name=”android.permission.BLUETOOTH_ADMIN”/> <uses … “android.permission.ACCESS_WIFI_STATE” /> <uses … “android.permission.CHANGE_WIFI_STATE” /> <uses … “android.permission.ACCESS_COARSE_LOCATION” />
Define strategy and service id, this should be the same for both devices.
public static final Strategy STRATEGY = Strategy.P2P_POINT_TO_POINT; public static final String SERVICE_ID="120001";
Code for Device A (Advertiser)
Once the user has granted all required permissions, your app can begin to advertise and discover in order to find nearby devices.
On devices that will advertise, call startAdvertising()
with the desired Strategy
and a serviceId
that identifies your app. The serviceId
value must uniquely identify your app. As a best practice, use the package name of your app.
Send Payload Method
Once connections are established between devices, you can exchange data by sending and receiving Payload
objects. A Payload
can represent a simple byte array, such as a short text message; a file, such as a photo or a video; or a stream, such as the audio stream from the device's microphone.
Payloads are sent using the sendPayload()
method, and received in implementation of PayloadCallback
that's passed to acceptConnection()
as described in Manage Connections.
Code for Device B (Discoverer)
On devices that will discover nearby advertisers, call startDiscovery()
with the same Strategy
and serviceId
.When nearby devices are found, the discoverer can initiate connections.
When a connection is requested, your app can authenticate the connection by using the authentication token provided to onConnectionInitiated()
. This provides a way to let users confirm that they are connecting to the intended device. Both devices are given the same token, which is a short random string; it's up to you to decide how to verify it. Typically this involves showing the token on both devices and asking the users to manually compare and confirm, similar to a bluetooth pairing dialog.
Payload receive callback
OnPayloadReceived()
is called when the first byte of a Payload is received; it does not indicate that the entire Payload has been received.
The completion of the transfer is indicated whenonPayloadTransferUpdate()
is called with a status of PayloadTransferUpdate.Status.SUCCESS.
Closing connection
We should close the connection when all the work is done.
Nearby.getConnectionsClient(BaseApplication.getInstance() .getActivity()).stopAllEndpoints();
That’s all for now! suggestions and questions are welcome.