Tag Archives: nearby

Discontinuing support for Android Nearby Notifications

Posted by Ritesh Nayak M, Product Manager

Three years ago, we created Nearby Notifications as a way for Android users to discover apps and content based on what is nearby. Our goal was to bring relevant and engaging content to users - to provide useful information proactively. Developers have leveraged this technology to let users know about free wifi nearby, provide guides while in a museum, and list transit schedules at bus stops.

We've learned a lot building and launching Nearby Notifications. However, earlier this year, we noticed a significant increase in locally irrelevant and spammy notifications that were leading to a poor user experience. While filtering and tuning can help, in the end, we have a very high bar for the quality of content that we deliver to users, especially content that is delivered through notifications. Ultimately, we have determined these notifications did not meet that bar. As a result, we have decided to discontinue support for Nearby Notifications. We will stop serving Nearby Notifications on December 6th, 2018.

What does it mean for Android users

Android users will stop receiving Nearby Notifications.

What does it mean for developers

On December 6th we will stop delivering both Eddystone and Physical Web beacon notifications. You will still continue to have access to the beacon dashboard and can deliver proximity based experiences similar to Nearby Notifications via your own apps using our Proximity Beacons API.

We have two related APIs, Nearby Messages and Connections, that are available for developers to build device-to-device connectivity experiences, and also have Fast Pair, for device discovery and pairing. We will continue to invest in these APIs and support products using these technologies.

We sincerely appreciate the efforts of the Android developer community in supporting and evolving Nearby technology and the feedback that has helped us improve. We look forward to continuing to deliver engaging proximity experiences to users and seeing what developers create within their apps with our APIs.

Alternative input methods for Android TV

Posted by Benjamin Baxter, Developer Advocate and Bacon Connoisseur

Hero image displaying phones and tvs communicating to each other

All TVs have the same problem with keyboard input: It is very cumbersome to hunt and peck for each letter using a D-pad with a remote. And if you make a mistake, trying to correct it compounds the problem.

APIs like Smart Lock and Autofill, can ease user's frustrations, but for certain types of input, like login, you need to collect complex input that is difficult for users using the on-screen keyboard.

With the Nearby Connections API, you can use a second screen to gather input from the user with less friction.

How Nearby Connections works

From the documentation:

"Nearby Connections is an offline peer-to-peer socket model for communication based on advertising and discovering devices in proximity.

Usage of the API falls into two phases: pre-connection, and post-connection.

In the pre-connection phase, Advertisers advertise themselves, while Discoverers discover nearby Advertisers and send connection requests. A connection request from a Discoverer to an Advertiser initiates a symmetric authentication flow that results in both sides independently accepting (or rejecting) the connection request.

After a connection request is accepted by both sides, the connection is established and the devices enter the post-connection phase, during which both sides can exchange data."

In most cases the TV is the advertiser and the phone is the discoverer. In the example below, the assumed second device is a phone. The API and patterns described in this article are not limited to a phone. For example, a tablet could also be the second screen device.

The TV is the Advertiser and the phone is the Discoverer.

Login Example

There are many times when keyboard input is required. Authenticating users and collecting billing information (like zip codes and name on card) are common cases. This example handles a login flow that uses a second screen to see how Nearby Connections can help reduce friction.

1. The user opens your app on her TV and needs to login. You can show a screen of options similar to the setup flow for a new TV.

Android TV setup with prompt to continue on the user's phone.

2. After the user chooses to login with their phone, the TV should start advertising and send the user to the associated login app on their phone, which should start discovering.

There are a variety of solutions to open the app on the phone. As an example, Android TV's setup flow has the user open the corresponding app on their mobile device. Initiating the hand-off is a more a UX concern than a technology concern.

Animation showing setup hand off from TV to phone.

3. The phone app should display the advertising TV and prompt the user to initiate the connection. After the (encrypted -- see Security Considerations below for more on this) connection is established the TV can stop advertising and the phone can stop discovering.

"Advertising/Discovery using Nearby Connections for hours on end can affect a device's battery. While this is not usually an issue for a plugged-in TV, it can be for mobile devices, so be conscious about stopping advertising and discovery once they're no longer needed."

4. Next, the phone can start collecting the user's input. Once the user enters their login information, the phone should send it to the TV in a BYTES payload over the secure connection.

5. When the TV receives the message it should send an ACK (using a BYTES payload) back to the phone to confirm delivery.

6. When the phone receives the ACK, it can safely close the connection.

The following diagram summarizes the sequence of events:

Sequence diagram of order of events to setup a connect and send a message.

UX considerations

Nearby Connections needs location permissions to be able to discover nearby devices. Be transparent with your users. Tell them why they need to grant the location permission on their phone.

Since the TV is advertising, it does not need location permissions.

Start advertising: The TV code

After the user chooses to login on the phone, the TV should start advertising. This is a very simple process with the Nearby API.

override fun onGuidedActionClicked(action: GuidedAction?) {
    super.onGuidedActionClicked(action)
    if( action == loginAction ) {
        // Update the UI so the user knows to check their phone
        navigationFlowCallback.navigateToConnectionDialog()
        doStartAdvertising(requireContext()) { payload ->
            handlePayload(payload)
        }
    }
}

When the user clicks a button, update the UI to tell them to look at their phone to continue. Be sure to offer a way to cancel the remote login and try manually with the cumbersome onscreen keyboard.

This example uses a GuidedStepFragment but the same UX pattern applies to whatever design you choose.

Advertising is straightforward. You need to supply a name, a service id (typically the package name), and a `ConnectionLifeCycleCallback`.

You also need to choose a strategy that both the TV and the phone use. Since it is possible that the users has multiple TVs (living room, bedroom, etc) the best strategy to use is P2P_CLUSTER.

Then start advertising. The onSuccessListener and onFailureListener tell you whether or not the device was able to start advertising, they do not indicate a device has been discovered.

fun doStartAdvertising(context: Context) {
    Nearby.getConnectionsClient(context).startAdvertising(
        context.getString(R.string.tv_name),
        context.packageName,
        connectionLifecycleCallback,
        AdvertisingOptions.Builder().setStrategy(Strategy.P2P_CLUSTER).build()
    )
    .addOnSuccessListener {
        Log.d(LoginStepFragment.TAG, "We are advertising!")
    }
    .addOnFailureListener {
        Log.d(LoginStepFragment.TAG, "We cannot start advertising.")
        Toast.makeText(
            context, "We cannot start advertising.", Toast.LENGTH_LONG)
                .show()
    }
}

The real magic happens in the `connectionLifecycleCallback` that is triggered when devices start to initiate a connection. The TV should accept the handshake from the phone (after performing the necessary authentication -- see Security Considerations below for more) and supply a payload listener.

val connectionLifecycleCallback = object : ConnectionLifecycleCallback() {

    override fun onConnectionInitiated(
            endpointId: String, 
            connectionInfo: ConnectionInfo
    ) {
        Log.d(TAG, "Connection initialized to endpoint: $endpointId")
        // Make sure to authenticate using `connectionInfo.authenticationToken` 
        // before accepting
        Nearby.getConnectionsClient(context)
            .acceptConnection(endpointId, payloadCallback)
    }

    override fun onConnectionResult(
        endpointId: String, 
        connectionResolution: ConnectionResolution
    ) {
        Log.d(TAG, "Received result from connection: ${connectionResolution.status.statusCode}")
        doStopAdvertising()
        when (connectionResolution.status.statusCode) {
            ConnectionsStatusCodes.STATUS_OK -> {
                Log.d(TAG, "Connected to endpoint: $endpointId")
                otherDeviceEndpointId = endpointId
            }
            else -> {
                otherDeviceEndpointId = null
            }
        }
    }

    override fun onDisconnected(endpointId: String) {
        Log.d(TAG, "Disconnected from endpoint: $endpointId")
        otherDeviceEndpointId = null
    }
}

The payloadCallback listens for the phone to send the login information needed. After receiving the login information, the connection is no longer needed. We go into more detail later in the Ending the Conversation section.

Discovering the big screen: The phone code

Nearby Connections does not require the user's consent. However, the location permission must be granted in order for discovery with Nearby Connections to work its magic. (It uses BLE scanning under the covers.)

After opening the app on the phone, start by prompting the user for location permission if not already granted on devices running Marshmallow and higher.

Once the permission is granted, start discovering, confirm the connection, collect the credentials, and send a message to the TV app.

Discovering is as simple as advertising. You need a service id (typically the package name -- this should be the same on the Discoverer and Advertiser for them to see each other), a name, and a `EndpointDiscoveryCallback`. Similar to the TV code, the flow is triggered by callbacks based on the connection status.

Nearby.getConnectionsClient(context).startDiscovery(
        context.packageName,
        mobileEndpointDiscoveryCallback,
        DiscoveryOptions.Builder().setStrategy(Strategy.P2P_CLUSTER).build()
        )
        .addOnSuccessListener {
            // We're discovering!
            Log.d(TAG, "We are discovering!")
        }
         .addOnFailureListener {
            // We were unable to start discovering.
            Log.d(TAG, "We cannot start discovering!")
        }

The Discoverer's listeners are similar to the Advertiser's success and failure listeners; they signal if the request to start discovery was successful or not.

Once you discover an advertiser, the `EndpointDiscoveryCallback` is triggered. You need to keep track of the other endpoint to know who to send the payload, e.g.: the user's credentials, to later.

val mobileEndpointDiscoveryCallback = object : EndpointDiscoveryCallback() {
    override fun onEndpointFound(
        endpointId: String, 
        discoveredEndpointInfo: DiscoveredEndpointInfo
    ) {
        // An endpoint was found!
        Log.d(TAG, "An endpoint was found, ${discoveredEndpointInfo.endpointName}")
        Nearby.getConnectionsClient(context)
            .requestConnection(
                context.getString(R.string.phone_name), 
                endpointId, 
                connectionLifecycleCallback)
    }

    override fun onEndpointLost(endpointId: String) {
        // A previously discovered endpoint has gone away.
        Log.d(TAG, "An endpoint was lost, $endpointId")
    }
}

One of the devices must initiate the connection. Since the Discoverer has a callback for endpoint discovery, it makes sense for the phone to request the connection to the TV.

The phone asks for a connection supplying a `connectionLifecycleCallback` which is symmetric to the callback in the TV code.

val connectionLifecycleCallback = object : ConnectionLifecycleCallback() {
    override fun onConnectionInitiated(
        endpointId: String,
        connectionInfo: ConnectionInfo
    ) {
        Log.d(TAG, "Connection initialized to endpoint: $endpointId")
        // Make sure to authenticate using `connectionInfo.authenticationToken` before accepting
        Nearby.getConnectionsClient(context)
                .acceptConnection(endpointId, payloadCallback)
    }

    override fun onConnectionResult(
        endpointId: String,
        connectionResolution: ConnectionResolution
    ) {
        Log.d(TAG, "Connection result from endpoint: $endpointId")
        when (connectionResolution.status.statusCode) {
            ConnectionsStatusCodes.STATUS_OK -> {
                Log.d(TAG, "Connected to endpoint: $endpointId")
                otherDeviceEndpointId = endpointId
                waitingIndicator.visibility = View.GONE
                emailInput.editText?.isEnabled = true
                passwordInput.editText?.isEnabled = true

                Nearby.getConnectionsClient(this).stopDiscovery()
            }
            else -> {
                otherDeviceEndpointId = null
            }
        }
    }

    override fun onDisconnected(endpointId: String) {
        Log.d(TAG, "Disconnected from endpoint: $endpointId")
        otherDeviceEndpointId = null
    }
}

Once the connection is established, stop discovery to avoid keeping this battery-intensive operation running longer than needed. The example stops discovery after the connection is established, but it is possible for a user to leave the activity before that happens. Be sure to stop the discovery/advertising in onStop() on both the TV and phone.


override fun onStop() {
    super.onStop()
    Nearby.getConnectionsClient(this).stopDiscovery()
}


Just like a TV app, when you accept the connection you supply a payload callback. The callback listens for messages from the TV app such as the ACK described above to clean up the connection.

After the devices are connected, the user can use the keyboard and send their authentication information to the TV by calling `sendPayload()`.

fun sendCreditials() {

    val email = emailInput.editText?.text.toString()
    val password = passwordInput.editText?.text.toString()

    val creds = "$email:$password"
    val payload = Payload.fromBytes(creds.toByteArray())
    Log.d(TAG, "sending payload: $creds")
    if (otherDeviceEndpointId != null) {
        Nearby.getConnectionsClient(this)
                .sendPayload(otherDeviceEndpointId, payload)
    }
}

Ending the conversation

After the phone sends the payload to the TV (and the login is successful), there is no reason for the devices to remain connected. The TV can initiate the disconnection with a simple shutdown protocol.

The TV should send an ACK to the phone after it receives the credential payload.

val payloadCallback = object : PayloadCallback() {
    override fun onPayloadReceived(endpointId: String, payload: Payload) {
        if (payload.type == Payload.Type.BYTES) {
            payload.asBytes()?.let {
                val body = String(it)
                Log.d(TAG, "A payload was received: $body")
                // Validate that this payload contains the login credentials, and process them.

                val ack = Payload.fromBytes(ACK_PAYLOAD.toByteArray())
                Nearby.getConnectionsClient(context).sendPayload(endpointId, ack)
            }
        }
    }

    override fun onPayloadTransferUpdate(
        endpointId: String,
        update: PayloadTransferUpdate
    ) {    }
}

The phone should have a `PayloadCallback` that initiates a disconnection in response to the ACK. This is also a good time to reset the UI to show an authenticated state.

private val payloadCallback = object : PayloadCallback() {
    override fun onPayloadReceived(endpointId: String, payload: Payload) {
        if (payload.type == Payload.Type.BYTES) {
            payload.asBytes()?.let {
                val body = String(it)
                Log.d(TAG, "A payload was received: $body")

                if (body == ACK_PAYLOAD) {
                    waitingIndicator.visibility = View.VISIBLE
                    waitingIndicator.text = getString(R.string.login_successful)
                    emailInput.editText?.isEnabled = false
                    passwordInput.editText?.isEnabled = false
                    loginButton.isEnabled = false

                    Nearby.getConnectionsClient([email protected])
                        .disconnectFromEndpoint(endpointId)
                }
            }
        }
    }

    override fun onPayloadTransferUpdate(
        endpointId: String,
        update: PayloadTransferUpdate
    ) {    }
}

Security considerations

For security (especially since we're sending over sensitive information like login credentials), it's strongly recommended that you authenticate the connection by showing a code and having the user confirm that the two devices being connected are the intended ones -- without this, the connection established by Nearby Connection is encrypted but not authenticated, and that's susceptible to Man-In-The-Middle attacks. The documentation goes into greater detail on how to authenticate a connection.

Let the user accept the connection by displaying a confirmation code on both devices.

Does your app offer a second screen experience?

There are many times when a user needs to supply input to a TV app. The Nearby API provides a way to offload the hardships of an onscreen-dpad-driven keyboard to an easy and familiar phone keyboard.

What use cases do you have where a second screen would simplify your user's life? Leave a comment or send me (@benjamintravels) or Varun (@varunkapoor, Team Lead for Nearby Connections) a tweet to continue the discussion.

Announcing Nearby Connections 2.0: fully offline, high bandwidth peer to peer device communication

Posted by Ritesh Nayak M, Product Manager

Imagine walking into a hotel room and having the temperature set just right, your favorite sub-genre of progressive-math-rock playing in the background, and the TV urging you to continue binging on your saved guilty-pleasures watchlist. What if your phone's contact book could expand to merge with your spouse's when you're together, so you're never again put in the excruciatingly compromising position of having to ask for your mother-in-law's phone number (which you ought to have had on speed dial, in your favorites, and listed as an emergency contact)? Now imagine a world where you can drive up to an empty driveway or private parking space in a city like New York or San Francisco, and negotiate with that space to rent it out until its owner returns.

The common thread among all these scenarios is being able to detect proximity to -- and being able to communicate with -- people, places, and things "near" you.

At I/O this year, we spoke about a refresh to the Nearby Connections API that can provide high bandwidth, low latency, encrypted data transfers between nearby devices in a fully-offline P2P manner. Today we're announcing the availability of this API across all Android devices running Google Play services 11.0 and up.

Nearby Connections uses WiFi, Bluetooth LE & Classic Bluetooth under the hood to discover and establish connections to nearby devices. It abstracts away the inherent complexity of these radios by leveraging the strengths of each, while circumventing their respective weaknesses. Aside from the obvious advantage of sidestepping the pain of dealing with the vagaries of these radios across different OS versions and devices, this abstraction enables seamlessly upgrading the bandwidth of a connection by switching between the radios as and when it makes sense, as well as getting invisible over-the-air updates to use new radio technology as it becomes available -- with no change whatsoever in the application code.

At the heart of this API is a connection (with Unix-socket-like semantics) that you can use to transfer bytes, files, or streams of data. There are two supported connection topologies:
  • Star: Useful for creating 1:N topologies where there's a centralized device that others are especially interested in. For example, the host of an offline game, or the teacher's device in a classroom quiz app.
  • Cluster: Useful for creating M:N topologies that allow for creating looser mesh-like networks. For example, a classroom app that supports forming ad-hoc project groups for realtime collaboration, or an offline hyper-proximity-based chat app.
As a part of the process of building this API we worked with a few partners, each with unique offline-data-transfer needs and environments. It's been great to see what they've built on top of early versions of this API, and their feedback has been invaluable in guiding us towards today's launch. Take a look at some of the cool things they're building:
  • The Weather Channel is building on-demand mesh networks in data-deficient areas to spread urgent weather warnings.
  • Hotstar enables offline media sharing in places with spotty/no internet connectivity (like on public transportation, airplanes, etc.)
  • GameInsight is using Nearby Connections to not only find nearby players, but also to run entire games offline.
  • Android TV is building a remote control app (powered by Nearby Connections) to simplify initial setup, and to enable subsequent second screen experiences.
Now that the API is publicly available, we can't wait to see how you will use Nearby Connections in your applications. To get started, visit our developer site, check our code samples, and post any questions you have on Stackoverflow (tagged with google-nearby). To stay up to date on the latest Android Nearby offerings (and our other Context-related APIs), please subscribe to our mailing list.



Google Play services 7.8 – Let’s see what’s Nearby!

Posted by Magnus Hyttsten, Developer Advocate, Play services team

Today we’ve finished the roll-out of Google Play services 7.8. In this release, we’ve added two new APIs. The Nearby Messages API allows you to build simple interactions between nearby devices and people, while the Mobile Vision API helps you create apps that make sense of the visual world, using real-time on-device vision technology. We’ve also added optimization and new features to existing APIs. Check out the highlights in the video or read about them below.

Nearby Messages

Nearby Messages introduces a cross-platform API to find and communicate with mobile devices and beacons, based on proximity. Nearby uses a combination of Bluetooth, Wi-Fi, and an ultrasonic audio modem to connect devices. And it works across Android and iOS. For more info on Nearby Messages, check out the documentation and the launch blog post.

Mobile Vision API

We’re happy to announce a new Mobile Vision API. Mobile Vision has two components.

The Face API allows developers to find human faces in images and video. It’s faster, more accurate and provides more information than the Android FaceDetector.Face API. It finds faces in any orientation, allows developers to find landmarks such as the eyes, nose, and mouth, and identifies faces that are smiling and/or have their eyes open. Applications include photography, games, and hands-free user interfaces.

The Barcode API allows apps to recognize barcodes in real-time, on device, in any orientation. It supports a range of barcodes and can detect multiple barcodes at once. For more information, check out the Mobile Vision documentation.

Google Cloud Messaging

And finally, Google Cloud Messaging - Google’s simple and reliable messaging service - has expanded notification to support localization for Android. When composing the notification from the server, set the appropriate body_loc_key, body_loc_args, title_loc_key, and title_loc_args. GCM will handle displaying the notification based on current device locale, which saves you having to figure out which messages to display on which devices! Check out the docs for more info.

And getting ready for the Android M release, we've added high and normal priority to GCM messaging, giving you additional control over message delivery through GCM. Set messages that need immediate users attention to high priority, e.g., chat message alert, incoming voice call alert. And keep the remaining messages at normal priority so that it can be handled in the most battery efficient way without impeding your app performance.

SDK Now Available!

You can get started developing today by downloading the Google Play services SDK from the Android SDK Manager.

To learn more about Google Play services and the APIs available to you through it, visit our documentation on Google Developers.

Connect With the World Around You Through Nearby APIs

Originally posted on the Google Developers blog.

Posted by Akshay Kannan, Product Manager

Mobile phones have made it easy to communicate with anyone, whether they’re right next to you or on the other side of the world. The great irony, however, is that those interactions can often feel really awkward when you're sitting right next to someone.

Today, it takes several steps -- whether it’s exchanging contact information, scanning a QR code, or pairing via bluetooth -- to get a simple piece of information to someone right next to you. Ideally, you should be able to just turn to them and do so, the same way you do in the real world.

This is why we built Nearby. Nearby provides a proximity API, Nearby Messages, for iOS and Android devices to discover and communicate with each other, as well as with beacons.

Nearby uses a combination of Bluetooth, Wi-Fi, and inaudible sound (using the device’s speaker and microphone) to establish proximity. We’ve incorporated Nearby technology into several products, including Chromecast Guest Mode, Nearby Players in Google Play Games, and Google Tone.

With the latest release of Google Play services 7.8, the Nearby Messages API becomes available to all developers across iOS and Android devices (Gingerbread and higher). Nearby doesn’t use or require a Google Account. The first time an app calls Nearby, users get a permission dialog to grant that app access.

A few of our partners have built creative experiences to show what's possible with Nearby.

Edjing uses Nearby to let DJs publish their tracklist to people around them. The audience can vote on tracks that they like, and their votes are updated in realtime.

Trello uses Nearby to simplify sharing. Share a Trello board to the people around you with a tap of a button.

Pocket Casts uses Nearby to let you find and compare podcasts with people around you. Open the Nearby tab in Pocket Casts to view a list of podcasts that people around you have, as well as podcasts that you have in common with others.

Trulia uses Nearby to simplify the house hunting process. Create a board and use Nearby to make it easy for the people around you to join it.

To learn more, visit developers.google.com/nearby.