Supporting Proximity and tapping (HTML)

[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]

Purpose

Note  

Proximity is designed for developers who want to incorporate easy connections into their app via a tap. This might include a multi-player game, for example, in which two users tap their devices together to establish a shared game session. Or, it could be an app in which customers tap a device and receive a link to a location where they can get more information or make a purchase.To make a connection between two devices using a tap gesture, both devices must have a Proximity device, such as a Near Field Communication (NFC) radio.

You can enhance your apps to use near-field communications (NFC), and to connect two devices without the need for a network using Wi-Fi Direct, by using Proximity. Proximity and NFC enable you to connect devices with a simple tap gesture. If two devices come within a range of 4 centimeters or less, or are tapped together, the operating system of each device becomes aware of the other device. You can also connect two devices running your application that are within wireless range, by using peer browsing with Wi-Fi Direct. You can then connect the two devices together to share content such as photos or links, create a multi-player experience, or publish and subscribe to messages.

Important  

A device must have a Proximity device, such as a Near Field Communication (NFC) radio device, to enable tap connections. A device must have a Wi-Fi device that supports Wi-Fi Direct to enable peer browsing.

In this section

Developer audience

Proximity is designed for use by developers who wish to expand their application to enable easy connections via a tap or by browsing for other devices running your app, or peer apps, within wireless range. For example, these apps might include a multi-player game where two users tap their devices together to establish a shared game session. Or, an app might allow customers to tap a device and receive a link to a location where they can get more information or make a purchase.

You can use Proximity to enable a quick exchange of data during a tap gesture. Or, you can use the tap to set up a long-term communication channel using infrastructure network, Wi-Fi Direct, or Bluetooth.

Note  

For Windows Phone Store apps, setting up a communication channel using Wi-Fi Direct is not supported. You can only set up a long-term communication channel using an infrastructure network or Bluetooth.

Proximity is supported by the classes in the Windows Runtime that are in the Windows.Networking.Proximity namespace. You can use the ProximityDevice class to communicate with other devices within a range of 4 centimeters or less, and exchange a small amount of data during the tap. You can use the PeerFinder class to communicate with peer apps and set up a long-term socket connection. A peer app is another instance of an app running on a separate device.

For example, the following code uses the GetDefault static method of the ProximityDevice class to get a reference to the Proximity device for the local machine. By associating event handlers with the DeviceArrived and DeviceDeparted events, you can tell when a device enters or leaves Proximity.

function id(elementId) {
    return document.getElementById(elementId);
}

WinJS.Application.onmainwindowactivated = function (e) {
    if (e.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {

        var proximityDevice = Windows.Networking.Proximity.ProximityDevice.getDefault();

        if (proximityDevice != null) {
            proximityDevice.addEventListener("devicearrived", 
                                             proximityDeviceArrived, false);
            proximityDevice.addEventListener("devicedeparted", 
                                             proximityDeviceDeparted, false);
        }
        else {
            id("MessageBlock").innerHTML += "Failed to initialize proximity device.<br/>";
        }

    }
}

function proximityDeviceArrived() {
    id("MessageBlock").innerHTML += "Proximate device arrived.<br/>";
}

function proximityDeviceDeparted() {
    id("MessageBlock").innerHTML += "Proximate device departed.<br/>";
}

For sample code that shows how to create a network connection between devices that are tapped together or are connected by peer browsing, see Quickstart: Connecting applications using tapping or browsing. For sample code that shows how to share small messages between devices that are tapped together, see Quickstart: Publishing and subscribing to messages using tapping. For sample code that shows how to create multi-peer app connections and dynamically scan for peer apps within range using the PeerWatcher, ProximityDevice and PeerWatcher objects, see the Proximity sample.

Important  

To use tapping in your app, you must enable the Proximity capability in the package manifest of your app.

Important  

The Proximity APIs do not provide authentication. You should avoid exchanging sensitive data with these APIs.

How to determine if Proximity is supported

As mentioned earlier, a device must have a device installed that implements the Windows Proximity interface in order for you to make use of the Proximity capability (For information on implementing the Windows Proximity interface, see the Windows 8 Near Field Proximity Implementation Specification.). You can determine if a device that supports Proximity is installed by checking the PeerFinder.SupportedDiscoveryTypes property to see if Triggered connections are supported, or by checking whether the GetDefault method returns NULL, or by getting a list of all of the Proximity devices and ensuring that the list refers to at least one device. For an example of how to get a list of all of the installed Proximity devices, see the GetDeviceSelector method.

Proximity is only enabled when your app is running in the foreground

All ProximityDevice and PeerFinder operations are disabled if your app is moved to the background. You can only publish and subscribe for messages or open socket connections if your app is running in the foreground. If you open a socket connection and your app is then moved to the background, your socket connection will remain open.

Activating apps using Proximity

When you use the PeerFinder and tap to connect your app to a peer app on another device, Windows will prompt the user of the other device to activate the app if the app is not already running or is not in the foreground. If the app is already running in the foreground, it the activation event will be raised without prompting the user first. You can also activate an app that is not running in the foreground by calling the PeerFinder.Start method overload that takes a string parameter. The string parameter for the Start method contains a message that is sent to the peer app. The app will activate with the message passed to the activation arguments.

When you activate a peer app using a tap gesture, the Activated event is raised. The activation Kind is Launch. If you activate the event by sending a message using the PeerFinder.Start method, the message text can be retrieved from the Arguments property of the launch arguments. If your app is activated in order to open a StreamSocket, then the Arguments property will return the string Windows.Networking.Proximity.PeerFinder:StreamSocket. In this case, set the TriggeredConnectionStateChanged property to an appropriate event handler and call the PeerFinder.Start method to complete the socket connection.

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.arguments == "Windows.Networking.Proximity.PeerFinder:StreamSocket") {
            // Call PeerFinder.Start to begin multi-user mode.
        }
        else {
            // Respond to the message string in args.detail.arguments
        }

        args.setPromise(WinJS.UI.processAll());
    }
}

For an example of an app that activates from a tap gesture and automatically completes a socket connection, see Quickstart: Connecting applications using tapping or browsing.

Socket communication protocol

When you send information to a peer app using a StreamSocket object, it is up to you to define the protocol for how the information is shared. For example, you might use an XML format, delimited name/value pairs, and so on. When the PeerFinder class creats a socket connection between peer apps, it connects the apps regardless of the version of the app. As a result, you may have two different versions of your app communicating with each other. For example, if a receiving app expects two 4-byte values and a newer version of the app sends the data as two 8-byte values to accommodate larger data, then the receiving app that expects 4-byte values will encounter an error while processing the data. You should take care to ensure that newer versions of your app can still communicate with older versions of your app using your communication protocol. That is, ensure that older versions of your app can ignore new information sent from a newer version of your app without encountering a problem.

Tip  

When peer apps communicate, you often need to determine which app will send the first message and which app will listen. One way that you can determine if your app is the sender or listener is to compare streamSocket.information.localAddress.canonicalName to streamSocket.information.remoteHostName.canonicalName. By testing if the local host name is greater than the remote host name, you will always receive an opposite result between two instances of your app.

Related topics

Quickstart: Connecting applications using tapping or browsing

Quickstart: Publishing and subscribing to messages using tapping

Guidelines and checklist for Proximity

Testing and troubleshooting Proximity in apps

Windows.Networking.Proximity namespace

Samples

Proximity sample