Language: JavaScript and HTML | VB/C#/C++ and XAML

Supporting proximity and tapping (Windows Runtime apps using JavaScript and HTML)

Applies to Windows and Windows Phone

Purpose

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

Important  

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

In this section

TopicDescription

Quickstart: Connecting apps using tapping or browsing

When you use proximity, you can create a connection between two devices with a simple tap gesture, 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.

Quickstart: Publishing and subscribing to messages using tapping

With proximity, you can publish and subscribe to messages between two computers and write static tags to a computer with a simple tap gesture. If two computers come within 3-4 centimeters of each other, proximity notifies the system. This topic shows you how to use proximity to publish or subscribe to a message.

Testing and troubleshooting proximity in apps

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

 

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 computers together to establish a shared game session. Or, an app might allow customers to tap a computer 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.

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 computers within a range of 3-4 centimeters, 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 computer.

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 object, see the Proximity sample.

Important  

To support Proximity in your app, you must enable the Proximity capability.

Important  

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.

How to determine if Proximity is supported

As mentioned earlier, a computer 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 computer, Windows will prompt the user of the other computer 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

 

 

Show:
© 2014 Microsoft. All rights reserved.