Testing and troubleshooting proximity in apps (HTML)

Article
10/13/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

This topic provides guidelines for app developers to test and troubleshoot Proximity in an app before submitting the app to the store.

Before you begin

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. Browsing for peer apps on other PCs takes place over WiFi-Direct. On Windows Phone, peer app discovery takes place over Bluetooth, and finds peer apps running on other phones.

To test capabilities that respond to a tap gesture, each device must have a Proximity device, such as a Near-Field Communication (NFC) radio, installed. To test capabilities that use wireless browsing on PCs, each PC must support Wi-Fi Direct.

Note To test browsing capabilities for Windows Phone Store apps, each phone must support Bluetooth.

Setting up to test:

If you do not have hardware that supports Proximity tapping such as Near-Field Communication (NFC) radio, you can use the Proximity driver sample that is part of the Windows Driver Kit (WDK) samples. You can use the sample driver to simulate a tap gesture over a network connection between two devices. For information on how to download the WDK, see Windows Driver Kit (WDK). Once you have installed the WDK and samples, you can find the Proximity driver sample in the src\nfp directory in the location where you installed the WDK samples. See the NetNfpProvider.html file in the src\nfp\net directory for instructions on building and running the simulator. Once you start the simulator, it runs in the background while your Proximity app is running in the foreground. Your app must be in the foreground for the tap simulation to work.

Connecting apps using the PeerFinder class

You can use the PeerFinder class to create a socket connection between the same app running on two different devices, that is, a peer app. Using the PeerFinder class, you can either connect peer apps from a tap gesture, or you can use Wi-Fi Direct to browse for peers within wireless range. Both methods of connecting peer apps create an open socket between peer apps and it is recommended that you support both triggered (tap) and browse (Wi-Fi Direct) connection capabilities in your app.

For an example of connecting peer apps, see Quickstart: Connecting applications using tapping or browsing or Proximity sample in the sample gallery. For guidelines on creating apps that use Proximity, see Guidelines for developing using Proximity.

Hh967765.wedge(en-us,WIN.10).gif Testing peer app connections

Install your app on two devices and start the app on both devices.
On both devices, advertise for a peer connection. This is done by calling the Start method.
To test triggered connections, tap the devices together.
Ensure that the UI in the app reflects the status of the tap gesture. That is, when a peer is found, when the devices are in the process of connecting, and so on. For more information, see the TriggeredConnectionStateChanged event.
If the connection is successful, then ensure that the UI in the app reflects that network capability is in effect for both devices.
If the connection is not successful, then ensure that the UI in the app informs the user that the network connection has failed.
To test wireless connections, have one of the two devices browse for available peer connections. This is done by calling the FindAllPeersAsync method. Browsing is only supported between PCs or between phones, but not between phones and PCs. The mechanism over which browsing takes place is different for an app running on a PC and an app running on a phone. Windows Phone only supports browsing over Bluetooth, whereas PCs only support browsing over WiFi-Direct.
If the connection is successful, then ensure that the UI in the app reflects that network capability is in effect for both devices.
If the connection is not successful, then ensure that the UI in the app informs the user that the network connection has failed.
If your app supports connections to more than two peers, expand the test to use multiple devices.

If an app that supports triggered (tap) connections is installed on two devices, requesting a connection from one device using a tap gesture will prompt the user of the second device to launch or install the app. The app must be running in the foreground on the requesting device. This capability is not supported when browsing for connections using the FindAllPeersAsync method.

Hh967765.wedge(en-us,WIN.10).gif Testing apps launched from a tap gesture

Install your app on two devices. Start the app on the first device only.
On the device running your app, advertise for a peer connection. This is done by calling the Start method.
Tap the devices together.
On the second device, ensure that a notification occurs prompting the user to launch the app. Accept the notification.
Ensure that the app successfully launches on the second device and that the app immediately establishes a Proximity network socket. Ensure that the UI in the app reflects that network capability is in effect for both devices.
If the app does not launch successfully, ensure that the UI in the app on the requesting device reflects the failed attempt. If the app launches, but fails to establish a Proximity network socket, ensure that the UI in the app on both devices reflects the failure.

Your app should be written to handle the scenario where a request for a peer app to start is declined.

Hh967765.wedge(en-us,WIN.10).gif Testing declined requests from a tap gesture

Install your app on two devices. Start the app on the first device only.
On the device running your app, advertise for a peer connection. This is done by calling the Start method.
Tap the devices together.
On the second device, ensure that a notification occurs prompting the user to launch or install the app. Decline the notification.
Ensure that the app does not launch on the second device and that the UI in the requesting app reflects that the request was declined.

Publishing and subscribing for messages using the ProximityDevice class

You can use the ProximityDevice class to publish small messages between devices during a tap gesture. The devices need to come within the range of the Proximity hardware installed. This is usually 2-3cm.

To publish a message during a tap gesture, use the PublishMessage, PublishBinaryMessage, or PublishUriMessage method on the publishing device and the SubscribeForMessage method on the receiving device. For an example of publishing and subscribing for messages, see Quickstart: Publishing and subscribing to messages using tapping or Proximity sample in the sample gallery.

Hh967765.wedge(en-us,WIN.10).gif Testing an app that publishes and subscribes for a message

Start the publishing app on one device and the subscribing app on another device. This can be the same app on both devices, but does not have to be.
Put the apps in a state to publish and receive a message. This involves calling one of the publish methods in the publishing app, and the SubscribeForMessage method in the receiving app.
Tap the devices together.
If the message is successfully transmitted, then ensure that the UI in the subscribing app reflects that the message was received. As an option in the publishing app, you can call the overload of the publish method that includes a parameter for an event handler of type MessageTransmittedHandler that is called when the message has been transmitted. In the code for this event handler, you can update the UI in the publishing app to reflect that the message was successfully transmitted.
If the message fails to publish or is not received, review the code in your app to determine the problem. For troubleshooting steps, see "A message that is published and subscribed for is not received" in the "Troubleshooting" section of this topic.
Test that both apps can be taken out of the state of publishing and subscribing for a message. On the publishing device, call the StopPublishingMessage method. On the subscribing device, call the StopSubscribingForMessage method. After tapping the devices together, ensure that the message is no longer published or received.

Troubleshooting

If the problem that you are encountering is not listed here, you may be able to find an answer in the Windows developer forums.

Issue	Troubleshooting steps
Tap does not respond. When connecting peer apps using a tap gesture, or publishing and subscribing for a message during a tap, the code to respond to the tap gesture does not get executed.	Ensure that the devices involved in the tap gesture come within proximate range, at least 2cm. You may have to align the devices based on the location of the Proximity device. Windows plays a sound when devices come within proximate range. You can use the DeviceArrived and DeviceDeparted events to tell when a device enters or leaves proximity. Add event handlers to your code for the DeviceArrived and DeviceDeparted events. If the event handler code is executed, then the tap gesture was successful. If the event handler code for the DeviceArrived and DeviceDeparted events is not executed, then you may have an issue with your Proximity hardware or driver. If your app is using the PeerFinder class to create a triggered connection, and the DeviceArrived event is raised, but the TriggeredConnection event is not raised, verify all of the following: Both instances of your app have called the Start method before attempting to connect with a tap. There is not an open socket connection between the devices from a previous tap. If this is the case, ensure that your app calls the Close method on a socket that is no longer needed. If you need to, you can close an open socket connection between peer instances of your app by exiting and restarting the app.
App does not launch after a tap.	Ensure that the app is running in the foreground on at least one of the two devices involved in the tap. If this is true, and the app still does not launch after a tap, refer to the troubleshooting steps for "Tap does not respond". If the TriggeredConnection event is raised in the app running in the foreground, but there is no prompt to launch the app on the other device involved in the tap gesture, ensure that the app is installed correctly. If the app is installed correctly it will launch from the start tile and connect from a tap gesture while it is running in the foreground.
No peers are found while browsing.	Ensure that the app is running in the foreground and that you have called the Start method on all devices that are browsing or available for a connection. If browsing for peer apps on Windows devices, verify that Wi-Fi Direct is enabled on all devices available for a connection. If browsing for peer apps on Window Phone, verify that Bluetooth is enabled on all phones. You can determine if the computer supports browsing for peers using the SupportedDiscoveryTypes property. Ensure that the browsing app does not have an open socket connection from a previous call to the ConnectAsync method. If this is the case, ensure that your app calls the Close method on a socket that is no longer needed. If you need to, you can close an open socket connection between peer instances of your app by exiting and restarting the app. Browsing for peers will only find peer devices running the same, Proximity-enabled app. Ensure that the same app is running on all of the devices that you are testing with. You can only connect two devices at a time using the ConnectAsync method. If the devices that you are trying to connect are joined to a domain, domain policy may prevent a new connection or close an existing one. If the connection succeeds for devices that are not joined to the domain and fails for devices that are joined to the domain, review the firewall policy for your domain. If your connections are failing on a PC, it may be a limitation of your Wi-Fi Direct hardware. Try running the app on both PCs with the wireless radio on, but disconnected from all wireless networks.
An attempt to connect from a tap fails after one minute.	Check the wireless settings on both devices involved in the tap and ensure that their Wi-Fi and Bluetooth radios are on. If either device does not have a wireless device that supports Wi-Fi Direct, or a Bluetooth radio, ensure that both devices are connected to the same network.
A message that is published and subscribed for is not received. When publishing and subscribing for messages, the published message is not received by the subscribing device.	On the publishing device, you can use the overload of the PublishMessage, PublishUriMessage, or PublishBinaryMessage method that includes a parameter for an event handler of type MessageTransmittedHandler that is called when the message has been transmitted. If the call to the publish method is successful, and the code in the MessageTransmittedHandler event handler is executed, then the message has been successfully transmitted. On the subscribing device, ensure that the value of the messageType parameter that you have passed to the SubscribeForMessage method matches the value of the messageType parameter that was passed to the PublishMessage or PublishBinaryMessage method (for the PublishUriMessage method, the messageType value is always WindowsUri. Message type values are case-sensitive.