Guidelines for developing using proximity

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

Introduction

Proximity allows users to connect two devices with the human gesture of a tap, or by browsing for devices within wireless range. You do not need to be connected to a network. You can simply tap two computers together, or connect using Wi-Fi Direct. You can use proximity to connect apps on two computers, for a multi-player game experience or to share content, such as photos or links.

Proximity Connections

There are several ways 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). While the range for a tap is limited to 3-4 centimeters, 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 tapping.

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.

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 where the computer 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 computer. If your app, or another app calls the ConnectAsync method, then the existing socket connection will be closed.

Each app on your computer can have one open connection to a peer app on another computer if that connection was established using a tap gesture. You can open socket connections from one app to a peer app on multiple computers by tapping each computer. 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 computer 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. Once a proximity experience is over, 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, speed), then do not use proximity.

TermDescription

Finding Peers

When your app browses for other peers that are running the same app, do not continuously browse for peers. Instead, provide the user an option to browse for peers within Wi-Fi range.

Ask for consent

Always ask for user consent to start a connected proximity experience, that is, to put an app in multi-user mode. While users are running an application, asking for consent should be forward and dismissible. For example, two people playing a game could be given a chance to provide consent before they decide to play together. In cases where a tap occurs as the app launches, users should be given a chance to provide consent in the start menu or 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
Windows.Networking.Proximity namespace
Samples
Proximity sample

 

 

Show:
© 2014 Microsoft