Guidelines for proximity

Applies to Windows and Windows Phone

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

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.

There are several ways to communicate using Proximity:

  • 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 by using tap gestures.
    • Applies to Windows Phone

    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 establish a connection.
    • Applies to Windows Phone

    Note  Browsing for peers takes place over Bluetooth in a Windows Phone app. As a result, your app running on Windows Phone can only find phone peers and your app running on a PC can only find PC peers.

  • Publishing and subscribing for messages: You can send or receive messages during a tap gesture by using the ProximityDevice object.

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 wireless 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.

Note  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.

For more info and code that'll help you add proximity to your app, see:

Dos and don'ts

  • 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.
  • 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.
  • When a user puts an app in multi-user mode, update the UI to display one of these three connection states:
    • Waiting for a tap
    • Connecting devices (show progress)
    • Devices now connected, or connection failed.
  • Revert to single-user mode if a connection breaks or can't be established. Provide a message for your user stating that the connection failed.
  • Ensure that users can easily leave a proximity experience.
  • Don't continuously browse for other devices that are running the same app. Instead, provide the user an option to browse for peers within Wi-Fi range.
  • Don't use proximity if an app needs constant updates about the connection (for example, updates on bandwidth usage or speed).

Related topics

For developers (Windows Runtime apps using JavaScript and HTML)
Proximity and tapping
Testing and troubleshooting proximity in apps
Windows.Networking.Proximity namespace
StreamSocket
For developers (Windows Runtime apps using C#/VB/C++ and XAML)
Proximity and tapping
Testing and troubleshooting proximity in apps
Windows.Networking.Proximity namespace
StreamSocket
Samples
Proximity sample

 

 

Show:
© 2014 Microsoft. All rights reserved.