Close by Connections for Android: Getting Began

Units could not all the time be linked to the web. Regardless of that, Close by Connections permits Android gadgets inside shut proximity to attach in a peer-to-peer vogue enabling the alternate of information. This permits use instances equivalent to native multiplayer gaming, offline knowledge transfers and controlling an Android TV utilizing a telephone or pill.

Internally, Close by Connections combines and abstracts options, equivalent to Bluetooth and Wi-Fi, to create an easy-to-use API. Close by Connections allows/disables these options as wanted and restores the machine to its earlier state as soon as the app isn’t utilizing the API anymore. This lets you focus in your particular area with out the concern of integrating complicated networking code.

On this tutorial, you’ll study:

• What Advertisers and Discoverers are.
• About promoting your telephone for Close by Connections.
• How one can set up a connection between an advertiser and a discoverer.
• How one can ship and obtain payloads.

Getting Began

All through this tutorial, you’ll work with a TicTacToe sport. In a single machine, a participant will host the match; in one other, a second participant will connect with the host, and the sport will begin. The sport will let every participant know whose flip it’s.

Use the Obtain Supplies button on the prime or backside of this tutorial to obtain the starter undertaking.

Though you could possibly run the starter undertaking utilizing an emulator, later within the tutorial, you’ll want bodily gadgets as a result of, at present, Close by Connections API requires bodily gadgets to work.

As soon as downloaded, open the starter undertaking in Android Studio 2021.2.1 or newer. Construct and run, and also you’ll see the next display screen:

You’ll see which you could select to both host a match or uncover an current one. Nonetheless, it doesn’t really do both of these issues, you’re going to repair that.

Assessment the undertaking to familiarize your self with the recordsdata:

• HomeScreen.kt: Let’s you select to host or uncover a sport.
• WaitingScreen.kt: You’ll discover the app’s screens after selecting to host or uncover.
• GameScreen.kt: This accommodates screens associated to the sport.
• TicTacToe.kt: Fashions a TicTacToe sport.
• TicTacToeRouter.kt: This lets you navigate between screens.
• TicTacToeViewModel.kt: This orchestrates the interactions between the screens, the sport, and later, with the Close by Connections consumer.

Setting Up Dependencies and Permissions

To make use of the Close by Connections API, you will need to first add a dependency. Open your app’s construct.gradle file and add the next dependency:

implementation 'com.google.android.gms:play-services-nearby:18.3.0'

Sync your undertaking so Android Studio can obtain the dependency.

Now open your AndroidManifest.xml and add the next permissions:

<uses-permission android:identify="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:identify="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:identify="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:identify="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:identify="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28" />
<uses-permission android:identify="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:identify="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:identify="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:identify="android.permission.BLUETOOTH_SCAN" />

A few of these are harmful permissions, due to this fact you’ll must request person consent. Open MainActivity and assign REQUIRED_PERMISSIONS contained in the companion object as follows:

val REQUIRED_PERMISSIONS =
  if (Construct.VERSION.SDK_INT >= Construct.VERSION_CODES.S) {
    arrayOf(
      Manifest.permission.BLUETOOTH_SCAN,
      Manifest.permission.BLUETOOTH_ADVERTISE,
      Manifest.permission.BLUETOOTH_CONNECT,
      Manifest.permission.ACCESS_FINE_LOCATION
    )
  } else if (Construct.VERSION.SDK_INT >= Construct.VERSION_CODES.Q) {
    arrayOf(Manifest.permission.ACCESS_FINE_LOCATION)
  } else {
    arrayOf(Manifest.permission.ACCESS_COARSE_LOCATION)
  }

You’ll want these imports:

import android.Manifest
import android.os.Construct

The exercise already has the code to request these permissions from the person.

Now that you simply’ve added the wanted dependency, you can begin utilizing the Close by Connections consumer that you simply’ll take a look at within the subsequent part.

Getting the Connection Consumer

To get the consumer for Close by Connections, you’ll be able to merely name:

Close by.getConnectionsClient(context)

Since you’ll use it contained in the ViewModel, open TicTacToeViewModel and replace the constructor with the next:

class TicTacToeViewModel(personal val connectionsClient: ConnectionsClient)

Subsequent, open TicTacToeViewModelFactory and replace it like this:

class TicTacToeViewModelFactory(
  personal val connectionsClient: ConnectionsClient
) : ViewModelProvider.Manufacturing facility {
  override enjoyable <T : ViewModel> create(modelClass: Class<T>): T {
    if (modelClass.isAssignableFrom(TicTacToeViewModel::class.java)) {
      @Suppress("UNCHECKED_CAST")
      return TicTacToeViewModel(connectionsClient) as T
  ...

For each recordsdata, you’ll must import the next:

import com.google.android.gms.close by.connection.ConnectionsClient

Lastly, open MainActivity and modify the viewModel property like this:

personal val viewModel: TicTacToeViewModel by viewModels {
  TicTacToeViewModelFactory(Close by.getConnectionsClient(applicationContext))
}

Make certain to import the next:

import com.google.android.gms.close by.Close by

Now your ViewModel and related manufacturing facility lessons have the ConnectionsClient occasion supplied. You’re prepared to start out utilizing it and set up a connection!

Selecting a Technique

Now you’ll select a connection technique primarily based on how the gadgets want to attach.

Test the next desk to grasp the options:

You’ll use P2P_CLUSTER when a tool can each request outgoing connections to different gadgets and obtain incoming connections from different gadgets. If you happen to want a star-shaped topology the place there’s a central internet hosting machine, and the remaining will connect with it, you’d use P2P_STAR.

On this case, since you’ll join between two gadgets, you’ll use P2P_POINT_TO_POINT. Open TicTacToeViewModel and add the next fixed:

personal companion object {
  ...
  val STRATEGY = Technique.P2P_POINT_TO_POINT
}

You’ll must import:

import com.google.android.gms.close by.connection.Technique

It’s necessary to notice that each Advertiser and Discoverer, which you’ll study later, have to make use of the identical technique.

To set the technique, replace startHosting() with the next code:

enjoyable startHosting() {
  Log.d(TAG, "Begin promoting...")
  TicTacToeRouter.navigateTo(Display screen.Internet hosting)
  val advertisingOptions = AdvertisingOptions.Builder().setStrategy(STRATEGY).construct()
}

This begins the promoting code and units the technique to P2P kind that you simply outlined earlier. You’ll get again an choices variable that you simply’ll use later to arrange the promoting connection.

Additionally, replace startDiscovering() with the next:

enjoyable startDiscovering() {
  Log.d(TAG, "Begin discovering...")
  TicTacToeRouter.navigateTo(Display screen.Discovering)
  val discoveryOptions = DiscoveryOptions.Builder().setStrategy(STRATEGY).construct()
}

Much like the promoting code, this units up the invention choices to make use of the identical P2P technique.

Within the following sections, you’ll study what Advertisers and Discoverers are and the way they alternate knowledge.

Making ready Your Units

To start out exchanging knowledge between two gadgets, certainly one of them, the Advertiser, has to promote itself in order that the opposite machine, the Discoverer, can request a connection.

Promoting

To start out promoting, replace startHosting() with the next:

enjoyable startHosting() {
  Log.d(TAG, "Begin promoting...")
  TicTacToeRouter.navigateTo(Display screen.Internet hosting)
  val advertisingOptions = AdvertisingOptions.Builder().setStrategy(STRATEGY).construct()

  // 1
  connectionsClient.startAdvertising(
    localUsername, // 2
    BuildConfig.APPLICATION_ID, // 3
    connectionLifecycleCallback, // 4
    advertisingOptions // 5
  ).addOnSuccessListener {
    // 6
    Log.d(TAG, "Promoting...")
    localPlayer = 1
    opponentPlayer = 2
  }.addOnFailureListener {
    // 7
    Log.d(TAG, "Unable to start out promoting")
    TicTacToeRouter.navigateTo(Display screen.Residence)
  }
}

Let’s see what’s occurring right here:

1. Name startAdvertising() on the consumer.
2. You’ll want to go an area endpoint identify.
3. You set BuildConfig.APPLICATION_ID for service ID since you desire a Discoverer to seek out you with this distinctive id.
4. Calls to the connectionLifecycleCallback strategies happen when establishing a reference to a Discoverer.
5. You go the choices containing the technique beforehand configured.
6. As soon as the consumer efficiently begins promoting, you set the native participant as participant 1, and the opponent can be participant 2.
7. If the consumer fails to promote, it logs to the console and returns to the house display screen.

These are the imports you want:

import com.google.android.gms.close by.connection.AdvertisingOptions
import com.yourcompany.android.tictactoe.BuildConfig

Add a property named connectionLifecycleCallback with the next content material:

personal val connectionLifecycleCallback = object : ConnectionLifecycleCallback() {
  override enjoyable onConnectionInitiated(endpointId: String, information: ConnectionInfo) {
    Log.d(TAG, "onConnectionInitiated")
  }

  override enjoyable onConnectionResult(endpointId: String, decision: ConnectionResolution) {
    Log.d(TAG, "onConnectionResult")

    when (decision.standing.statusCode) {
      ConnectionsStatusCodes.STATUS_OK -> {
        Log.d(TAG, "ConnectionsStatusCodes.STATUS_OK")
      }
      ConnectionsStatusCodes.STATUS_CONNECTION_REJECTED -> {
        Log.d(TAG, "ConnectionsStatusCodes.STATUS_CONNECTION_REJECTED")
      }
      ConnectionsStatusCodes.STATUS_ERROR -> {
        Log.d(TAG, "ConnectionsStatusCodes.STATUS_ERROR")
      }
      else -> {
        Log.d(TAG, "Unknown standing code ${decision.standing.statusCode}")
      }
    }
  }

  override enjoyable onDisconnected(endpointId: String) {
    Log.d(TAG, "onDisconnected")
  }
}

When a Discoverer requests a connection, the Advertiser’s ConnectionLifecycleCallback.onConnectionInitiated() will hearth. In a later part, you’ll add code to this methodology callback. When there’s a connection change that happens, the ConnectionLifecycleCallback.onConnectionResult() fires. You’ll deal with three particular connection standing varieties: OK, rejected and error. There’s additionally a catch-all for the every other unknown standing code that’s returned.

You’ll want the next imports:

import com.google.android.gms.close by.connection.ConnectionLifecycleCallback
import com.google.android.gms.close by.connection.ConnectionInfo
import com.google.android.gms.close by.connection.ConnectionResolution
import com.google.android.gms.close by.connection.ConnectionsStatusCodes

Discovering

The Discoverer is the machine that wishes to find an Advertiser to request a connection.

To start out discovering, replace the next methodology:

enjoyable startDiscovering() {
  Log.d(TAG, "Begin discovering...")
  TicTacToeRouter.navigateTo(Display screen.Discovering)
  val discoveryOptions = DiscoveryOptions.Builder().setStrategy(STRATEGY).construct()

  // 1
  connectionsClient.startDiscovery(
    BuildConfig.APPLICATION_ID, // 2
    endpointDiscoveryCallback, // 3
    discoveryOptions // 4
  ).addOnSuccessListener {
    // 5
    Log.d(TAG, "Discovering...")
    localPlayer = 2
    opponentPlayer = 1
  }.addOnFailureListener {
    // 6
    Log.d(TAG, "Unable to start out discovering")
    TicTacToeRouter.navigateTo(Display screen.Residence)
  }
}

That is what’s occurring:

1. You name startDiscovery() on the consumer.
2. You set BuildConfig.APPLICATION_ID for service ID since you wish to discover an Advertiser this distinctive ID.
3. Calls to the endpointDiscoveryCallback strategies happen when establishing a reference to an Advertiser.
4. You go the choices containing the technique beforehand configured.
5. As soon as the consumer efficiently begins discovering you set the native participant as participant 2, the opponent can be participant 1.
6. If the consumer fails to find, it logs to the console and returns to the house display screen.

Add this import:

import com.google.android.gms.close by.connection.DiscoveryOptions

Add a property named endpointDiscoveryCallback with the next content material:

personal val endpointDiscoveryCallback = object : EndpointDiscoveryCallback() {
  override enjoyable onEndpointFound(endpointId: String, information: DiscoveredEndpointInfo) {
    Log.d(TAG, "onEndpointFound")
  }

  override enjoyable onEndpointLost(endpointId: String) {
    Log.d(TAG, "onEndpointLost")
  }
}

You additionally must import these:

import com.google.android.gms.close by.connection.EndpointDiscoveryCallback
import com.google.android.gms.close by.connection.DiscoveredEndpointInfo

When a Discoverer finds an Advertiser, the Discoverer’s EndpointDiscoveryCallback.onEndpointFound() can be known as. You’ll add code to this methodology callback within the following part.

Establishing a Connection

After discovering an Advertiser, the Discoverer has to request a connection. Replace EndpointDiscoveryCallback.onEndpointFound() with the next code:

override enjoyable onEndpointFound(endpointId: String, information: DiscoveredEndpointInfo) {
  Log.d(TAG, "onEndpointFound")

  Log.d(TAG, "Requesting connection...")
  // 1
  connectionsClient.requestConnection(
    localUsername, // 2
    endpointId, // 3
    connectionLifecycleCallback // 4
  ).addOnSuccessListener {
    // 5
    Log.d(TAG, "Efficiently requested a connection")
  }.addOnFailureListener {
    // 6
    Log.d(TAG, "Didn't request the connection")
  }
}

Let’s assessment step-by-step:

1. You name requestConnection() on the consumer.
2. You’ll want to go an area endpoint identify.
3. Move the endpointId you’ve simply discovered.
4. Calls to the connectionLifecycleCallback strategies happen later when the connection initiates with the Advertiser.
5. As soon as the consumer efficiently requests a connection, it logs to the console.
6. If the consumer fails, it logs to the console.

The Advertiser and Discoverer want to just accept the connection, each will get notified through ConnectionLifecycleCallback.onConnectionInitiated(), so replace the code with this:

override enjoyable onConnectionInitiated(endpointId: String, information: ConnectionInfo) {
  Log.d(TAG, "onConnectionInitiated")

  Log.d(TAG, "Accepting connection...")
  connectionsClient.acceptConnection(endpointId, payloadCallback)
}

You’ll want to present a payloadCallback, which accommodates strategies that’ll execute later when the gadgets alternate knowledge. For now, simply create a property with the next content material:

personal val payloadCallback: PayloadCallback = object : PayloadCallback() {
  override enjoyable onPayloadReceived(endpointId: String, payload: Payload) {
    Log.d(TAG, "onPayloadReceived")
  }

  override enjoyable onPayloadTransferUpdate(endpointId: String, replace: PayloadTransferUpdate) {
    Log.d(TAG, "onPayloadTransferUpdate")
  }
}

You’ll want to import these:

import com.google.android.gms.close by.connection.PayloadCallback
import com.google.android.gms.close by.connection.Payload
import com.google.android.gms.close by.connection.PayloadTransferUpdate

After accepting, ConnectionLifecycleCallback.onConnectionResult() notifies either side of the brand new connection. Replace its code to the next:

override enjoyable onConnectionResult(endpointId: String, decision: ConnectionResolution) {
  Log.d(TAG, "onConnectionResult")

  when (decision.standing.statusCode) {
    ConnectionsStatusCodes.STATUS_OK -> {
      Log.d(TAG, "ConnectionsStatusCodes.STATUS_OK")

      opponentEndpointId = endpointId
      Log.d(TAG, "opponentEndpointId: $opponentEndpointId")
      newGame()
      TicTacToeRouter.navigateTo(Display screen.Recreation)
    }
...

If the standing code is STATUS_OK, you save the opponentEndpointId to ship payloads later. Now you’ll be able to navigate to the sport display screen to start out enjoying!

Construct and run the appliance on two bodily gadgets, click on Host on certainly one of them and Uncover on the opposite one. After a couple of seconds, you need to see the sport board on every machine:

Utilizing a Payload

Sending

You’ll want to ship the participant place to the opposite machine everytime you make a transfer. Modify sendPosition() with the next code:

personal enjoyable sendPosition(place: Pair<Int, Int>) {
  Log.d(TAG, "Sending [${position.first},${position.second}] to $opponentEndpointId")
  connectionsClient.sendPayload(
    opponentEndpointId,
    place.toPayLoad()
  )
}

Right here, you’re utilizing the opponentEndpointId you beforehand saved to ship the place. You’ll want to convert the place, which is a Pair to a Payload object. To do this, add the next extension to the tip of the file:

enjoyable Pair<Int, Int>.toPayLoad() = Payload.fromBytes("$first,$second".toByteArray(UTF_8))

Import this:

import kotlin.textual content.Charsets.UTF_8

You’ve now transformed the pair right into a comma separated string which is transformed to a ByteArray that’s lastly used to create a Payload.

Receiving

To obtain this payload, replace the PayloadCallback.onPayloadReceived() with this:

override enjoyable onPayloadReceived(endpointId: String, payload: Payload) {
  Log.d(TAG, "onPayloadReceived")

  // 1
  if (payload.kind == Payload.Sort.BYTES) {
    // 2
    val place = payload.toPosition()
    Log.d(TAG, "Obtained [${position.first},${position.second}] from $endpointId")
    // 3
    play(opponentPlayer, place)
  }
}

That is what’s occurring:

1. You test if the payload kind is BYTES.
2. You exchange again the Payload to a place Pair object.
3. Instruct the sport that the opponent has performed this place.

Add the extension to transform a Payload to a Pair place to the tip of the file:

enjoyable Payload.toPosition(): Pair<Int, Int> {
  val positionStr = String(asBytes()!!, UTF_8)
  val positionArray = positionStr.cut up(",")
  return positionArray[0].toInt() to positionArray[1].toInt()
}

Construct and run the appliance on two gadgets and begin enjoying!

Clearing Connections

When the Advertiser and Discoverer have discovered one another, you need to cease promoting and discovering. Add the next code to the ConnectionLifecycleCallback.onConnectionResult():

override enjoyable onConnectionResult(endpointId: String, decision: ConnectionResolution) {
  Log.d(TAG, "onConnectionResult")

  when (decision.standing.statusCode) {
    ConnectionsStatusCodes.STATUS_OK -> {
      Log.d(TAG, "ConnectionsStatusCodes.STATUS_OK")

      connectionsClient.stopAdvertising()
      connectionsClient.stopDiscovery()
...

You’ll want to disconnect the consumer every time one participant decides to exit the sport. Add the next to make sure the consumer is stopped every time the ViewModel is destroyed:

override enjoyable onCleared() {
  stopClient()
  tremendous.onCleared()
}

Replace goToHome() as follows:

enjoyable goToHome() {
  stopClient()
  TicTacToeRouter.navigateTo(Display screen.Residence)
}

Add the code for stopClient() as follows:

personal enjoyable stopClient() {
  Log.d(TAG, "Cease promoting, discovering, all endpoints")
  connectionsClient.stopAdvertising()
  connectionsClient.stopDiscovery()
  connectionsClient.stopAllEndpoints()
  localPlayer = 0
  opponentPlayer = 0
  opponentEndpointId = ""
}

Right here you’re additionally calling stopAllEndpoints() which is able to make sure the disconnection of the consumer.

If you wish to disconnect from a selected endpoint you should use disconnectFromEndpoint(endpointId).

Lastly, every time an Advertiser or Discoverer executes stopAllEndpoints() (or disconnectFromEndpoint(endpointId)) the counterpart can be notified through ConnectionLifecycleCallback.onDisconnected(), so replace it as follows:

override enjoyable onDisconnected(endpointId: String) {
  Log.d(TAG, "onDisconnected")
  goToHome()
}

Construct and run the app on each gadgets. Begin a brand new sport and press the again button on any machine. You’ll discover that the sport ends on each gadgets and takes you again to the house display screen.

Congratulations! You’ve simply discovered the fundamentals of Android’s Close by Connections API.

The place to Go From Right here?

You possibly can obtain the ultimate model of the undertaking utilizing the Obtain Supplies button on the prime or backside of this tutorial.

As a problem, you’ll be able to let extra gamers connect with the host and use a much bigger board, the TicTacToe mannequin already permits that. Listed below are a couple of suggestions that may assist you to:

• You’ll want to decide on one other connection technique.
• Let the host determine the board measurement.
• As a result of the host doesn’t know what number of opponents will join beforehand, you’ll must set the native and opponent participant numbers when the sport begins.
• As a substitute of instantly beginning the sport every time an opponent joins, await a couple of to hitch and let the host determine when to start out.
• You’ll want a brand new payload to sign to all of the opponents that the host has began a brand new sport.

You could find the answer within the supplies.

Listed below are some nice references to study extra concerning the topic:

• You could find the official documentation right here.
• Right here you’ll discover the API reference.
• If you happen to appreciated this, you may wish to construct a ‘rock, paper and scissors’ multiplayer sport, simply observe alongside this codelab.
• For different Close by use instances, test this weblog collection.

Be at liberty to share your suggestions and findings or ask any questions within the feedback under or within the boards. We hope you loved this tutorial!