Nearby Connections API is one of the many APIs available in google play services.
This framework was introduced in early 2015.
Initially, it allowed only those devices to share data which connected to the same wifi network.
After June 2017, in the version 11.0, it also made use of Wifi hotspots, Bluetooth and BLE to provide offline communication support to the devices.

Using this API, devices can advertise themselves, discover nearby devices, send connection request to other devices and share data after the connection is made successfully.

Now, advertising, discovering and sending request for connection comes under one phase called as pre-connection phase.

Once the connection is established successfully, next phase of sharing data (often termed as post-connection phase) is symmetrical i.e. there is no distinction between the advertiser and discoverer.

In this blog, we are going to discuss about the pre-connection phase.
We’ll cover post-connection phase in another blog.

Steps of pre-connection phase are :

1. First, advertisers need to advertise themselves.
2. Discoverers then discover the nearby advertisers.
3. Then, discoverers will send connection request to the advertisers.
4. Once the connection request is accepted by both advertiser and discoverer, the connection is established successfully.

In nearby connections, there are two strategies for advertising and discovery.

P2P_CLUSTER
In this strategy, there can be M advertisers and N discoverers (M may or may not be equal to N), where each device can both advertise and discover.

P2P_STAR
In this strategy, there is only one advertiser but discoverers can be more than one.

Depending on your use case, you can opt a particular strategy.

Let’s now discuss different steps of pre-connection phase in detail..

Advertising and Discovery :

The devices have to call startAdvertising() method in order to advertise themselves.

Syntax of startAdvertising() method is :

Nearby.getConnectionsClient(context).startAdvertising(
        userName,
        SERVICE_ID,
        connectionLifecycleCallback,
        new AdvertisingOptions(STRATEGY));

where,
1st parameter, userName is the name of the advertiser.
2nd parameter, SERVICE_ID is a string which uniquely identifies your app.
3rd parameter, connectionLifecycleCallback is an instance of implementation class of abstract class ConnectionLifecycleCallback.
One instance of this class you need to pass in requestConnection() method also (on discoverer’s side).
In the last parameter, you need to pass the desired startegy, either P2P_STAR or P2P_CLUSTER.

To know more about this method, check this reference :
https://developers.google.com/android/reference/com/google/android/gms/nearby/connection/ConnectionsClient#startAdvertising(java.lang.String,%20java.lang.String,%20com.google.android.gms.nearby.connection.ConnectionLifecycleCallback,%20com.google.android.gms.nearby.connection.AdvertisingOptions)

Now, if other devices want to discover this advertiser then they need to call startDiscovery() method.

Syntax of startDiscovery() method is :

Nearby.getConnectionsClient(context).startDiscovery(
        SERVICE_ID,
        endpointDiscoveryCallback,
        new DiscoveryOptions(STRATEGY));

1st parameter, SERVICE_ID is the same string which uniquely identifies your app.
2nd parameter, endpointDiscoveryCallback is an instance of implementation class of abstract class EndpointDiscoveryCallback.
3rd parameter, the desired startegy, either P2P_STAR or P2P_CLUSTER.

To know more about this method, check this reference :
https://developers.google.com/android/reference/com/google/android/gms/nearby/connection/ConnectionsClient#startDiscovery(java.lang.String,%20com.google.android.gms.nearby.connection.EndpointDiscoveryCallback,%20com.google.android.gms.nearby.connection.DiscoveryOptions)

Note : EndpointDiscoveryCallback class has two methods, onEndpointFound() and onEndpointLost().
As soon as an advertiser is discovered, it’s unique endpointID is passed as a parameter to onEndpointFound() method.
If a previously discovered advertiser has been lost, it’s endpointID is passed as a parameter to onEndpointLost() method.

Request for Connection :

Finally, in order the discovererers to send connection request to the advertiser, they need to call requestConnection() method.

Syntax of requestConnection() method is :

Nearby.getConnectionsClient(context).requestConnection(
 userName,
 endpointId,
 connectionLifecycleCallback);

Here, userName and endpointId are the ones which you received in onEndpointFound() method.
connectionLifecycleCallback is the instance of implementation class of abstract class ConnectionLifecycleCallback like you passed in startAdvertising() method.

To know more about this method, check this reference :
https://developers.google.com/android/reference/com/google/android/gms/nearby/connection/ConnectionsClient#requestConnection(java.lang.String,%20java.lang.String,%20com.google.android.gms.nearby.connection.ConnectionLifecycleCallback)

Note : ConnectionLifecycleCallback class has two methods onConnectionInitiated() and onConnectionResult().
If the connection request from discoverer results in success, then onConnectionInitiated() method is called on both advertiser and discoverer sides.
Here, both can either accept or reject the connection.
And the result of connection (either accepted or rejected) is passed in onConnectionResult() method.

After the connection is made successfully, post-connection phase (i.e. sharing of data) starts.