Windows apps
Collapse the table of content
Expand the table of content

Guidelines for developing using proximity

Applies to Windows and Windows Phone

Note  Pre-Release Content: This topic is currently being adapted to apply to both Windows 8.1 and Windows Phone (code-named "Blue"). To view the Windows 8.1 version of this topic, click here.

This topic describes best practices for using Proximity to connect apps and share content.

Introduction

Proximity is a great way to create a shared app experience between two instances of your app running on two different devices. In a proximity-enabled app, app users simply tap two devices together to initiate a connection, or a user can browse to find another device in wireless range that is running the app. On a PC, the user can use Wi-Fi Direct to find the app running on other PCs. On Windows Phone, the user can use Bluetooth to find the app running on other Windows Phones.

Proximity connections

There are several ways you can design your app to communicate by using proximity:

TermDescription

Out-of-band sessions

You can establish a session using the PeerFinder object, which connects devices over an out-of-band transport (Bluetooth, infrastructure network, or Wi-Fi Direct). Although the range for a tap is limited to 4 centimeters or less, the range for out-of-band transport options is much larger. You may not need to include proximity in your app to share resources. If Windows supports your sharing scenario, then enable the Sharing contract and use built-in Windows functionality to share resources using tap gestures.

Note  

Wi-Fi Direct is not supported on Windows Phone.

Browse for peers

You can establish a session by using the PeerFinder.FindAllPeersAsync() method. This method finds all remote peers that are running the same app, if they have also called the PeerFinder.Start() method to advertise that they are available for a peer session. Browsing for peers does not use a tap gesture, but instead uses Wi-Fi Direct to discover the remote peer and establish a connection.

Note  

Browsing uses Bluetooth to discover remote peers. As a result, your app running on Windows Phone can only find Windows Phone peers and your app running on Windows can only find Windows peers.

Publishing and subscribing for messages

You can send or receive messages during a tap gesture by using the ProximityDevice object. Messages are received by subscribers as ProximityMessage objects.

 

If an app calls the ConnectAsync method to create a connection with a peer, the app will no longer advertise for a connection and will not be found by the FindAllPeersAsync() method until the app calls the StreamSocket.Close method to close the socket connection.

You will only find peers when the device is within range and the peer app is running in the foreground. If a peer app is running in the background, proximity does not advertise for peer connections.

If you open a socket connection by calling the ConnectAsync method, only one socket connection can be open at a time for the device. If your app or another app calls the ConnectAsync method, then the existing socket connection will be closed.

Each app on a device can have one open connection to a peer app on another device if that connection was established using a tap gesture. You can open socket connections from one app to a peer app on multiple devices by tapping each device. If you create a connection using a tap gesture, a new tap gesture will not close the existing connection. You must call the StreamSocket.Close method of the socket object to create a new connection to the same peer app on the same peer device using a tap gesture.

Best practices

The overall feel of a proximity experience should be easy, lightweight, and intuitive. Users should go through minimal setup to participate in a proximity experience. When ending a proximity experience, exiting the experience should be as sleek as entering it. Proximity is intended for an app that just wants a connection with another instance of itself, without being concerned about the details of the connection. If an app needs constant updates about the connection (for example, bandwidth usage or speed), do not use proximity.

TermDescription

Finding peers

When your app browses for other peers that are running your app, do not continuously browse for peers. Instead, let the user initiate the action by providing an option to browse for peers within range.

Ask for consent

Always ask for user consent to start a connected proximity experience and put an app in multi-user mode. Asking for consent should be straightforward and dismissible while users are running an app. For example, two people each playing a game should be given a chance to provide consent before they decide to play the game together through proximity. If a tap occurs as the app launches, users should be given a chance to provide consent on the start menu or in the lobby of the app.

Show the state of the connection

When a user puts an app in multi-user mode, the UI should reflect one of three connection states:

  • Waiting for a tap
  • Connecting devices (show progress)
  • Devices now connected, or connection failed

Revert to single-user mode after a failed connection

If a connection breaks or fails to establish, you should convey this information to users by putting the app back into single-user mode and displaying a message to indicate that the connection has failed.

Keep the user in control

Ensure that users can easily navigate out of a proximity experience.

Proximity only creates StreamSocket objects for network connections

If your app requires a different type of connection object than a StreamSocket object, you cannot use proximity to connect.

 

Security considerations

The following articles provide guidance for writing secure code.

Related topics

Proximity and tapping overview
Quickstart: Connecting apps using tapping or browsing
Quickstart: Publishing and subscribing to messages using tapping
Testing and troubleshooting proximity in apps
Windows.Networking.Proximity namespace
Samples
Proximity sample

 

 

Show:
© 2017 Microsoft