Suporte à proximidade e toque (HTML)

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Finalidade

Observação  

Proximidade é projetada para desenvolvedores que desejam incorporar conexões fáceis em seus aplicativos por meio de um toque. Isso pode incluir um jogo de vários jogadores, por exemplo, no qual dois usuários tocam em seus dispositivos para estabelecerem juntos uma sessão de jogo compartilhada. Ou, pode ser um aplicativo no qual os clientes tocam no dispositivo para receber um link para um local onde podem obter mais informações ou fazer uma compra. Para fazer uma conexão entre dois dispositivos usando um gesto de toque, ambos os dispositivos devem ter um dispositivo de Proximidade, como um rádio NFC (Near Field Communication).

Você pode aprimorar seus aplicativos para usar near-field communications (NFC) e para conectar dois dispositivos sem precisar de uma rede usando Wi-Fi Direct usando a Proximidade. A Proximidade e NFC permitem que você conecte dispositivos com um simples gesto de toque. Se dois dispositivos estiverem a uma distância de 4 centímetros ou menos ou se tocarem, o sistema operacional de cada dispositivo reconhece o outro. Você também pode conectar dois dispositivos executando o aplicativo que esteja dentro da distância sem fio usando navegação entre pares com Wi-Fi Direct. Você pode, então, conectar os dois dispositivos para compartilhar conteúdo, como fotos ou links, criar uma experiência de jogo com vários participantes ou publicar e assinar mensagens.

Importante  

Um dispositivo deve ter um dispositivo de Proximidade, como um dispositivo de rádio Near Field Communication (NFC), para permitir conexões por toque. Um dispositivo deve ter um dispositivo Wi-Fi compatível com Wi-Fi Direct para permitir a navegação entre pares.

Nesta seção

Audiência de desenvolvedores

A proximidade foi projetada para ser usada por desenvolvedores que queiram expandir seus aplicativos a fim de permitir conexões fáceis por meio de um toque ou da procura por outros dispositivos que estejam executando o mesmo aplicativo (aplicativos pares) dentro da distância sem fio. Por exemplo, esses aplicativos podem incluir um jogo com vários participantes em que dois usuários tocam os seus dispositivos para estabelecer uma sessão de jogo compartilhado. Ou um aplicativo poderia permitir que os clientes tocassem em um dispositivo e recebessem um link para uma localização onde pudessem obter mais informações ou fazer uma compra.

Você pode usar a Proximidade para ativar uma troca rápida de dados durante um gesto de toque. Ou você pode usar o toque para definir um canal de comunicação a longo prazo usando rede de infraestrutura, Wi-Fi Direct ou Bluetooth.

Observação  

Para aplicativos da Loja do Windows Phone, não é permitido configurar um canal de comunicação usando Wi-Fi Direct. Só é possível configurar um canal de comunicação de longo prazo usando uma rede de infraestrutura ou Bluetooth.

O suporte a proximidade é oferecido pelas classes do Tempo de Execução do Windows que estão no namespace Windows.Networking.Proximity. Você pode usar a classe ProximityDevice para se comunicar com outros dispositivos a uma distância de 4 centímetros ou menos ou trocar uma pequena quantidade de dados durante o toque. Você pode usar a classe PeerFinder para se comunicar com aplicativos pares e configurar uma conexão de soquete de longo prazo. Um aplicativo par é outra instância de um aplicativo executando em um dispositivo separado.

Por exemplo, o código a seguir usa o método estático GetDefault da classe ProximityDevice para obter uma referência ao dispositivo de Proximidade da máquina local. Ao associar manipuladores de eventos aos eventos DeviceArrived e DeviceDeparted, é possível saber quando um dispositivo entra ou sai da Proximidade.

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/>";
}

Para obter um exemplo de código mostrando como estabelecer uma conexão de rede entre dispositivos que são tocados simultaneamente ou são conectados por navegação entre pares, veja Guia de início rápido: Usando toque ou navegação para conectar aplicativos. Para obter um exemplo de código mostrando como compartilhar pequenas mensagens entre dispositivos que são tocados simultaneamente, veja Guia de início rápido: Usando toque para publicar ou assinar mensagens. Para obter um exemplo de código mostrando como criar conexões de aplicativos entre vários pares e verificar de forma dinâmica se há aplicativos pares no alcance usando os objetos PeerWatcher, ProximityDevice e PeerWatcher, consulte Exemplo de Proximidade.

Importante  

Para usar toque em seu aplicativo, você deve ativar o recurso de proximidade no manifesto do pacote de seu aplicativo.

Importante  

As APIs de Proximidade não fornecem autenticação. Você deve evitar a troca de dados confidenciais com essas APIs.

Como determinar se a proximidade é permitida

Como mencionado anteriormente, um dispositivo tem que ter um dispositivo instalado que implemente a interface de Proximidade do Windows para você usar o recurso de Proximidade. (Para saber mais sobre como implementar a interface de Proximidade do Windows, veja a Especificação da implementação proximidade de curta distância do Windows 8.). Você pode determinar se há um dispositivo que permite Proximidade instalado verificando a propriedade PeerFinder.SupportedDiscoveryTypes para ver se as conexões Triggered são permitidas, verificando se o método GetDefault retorna NULL ou obtendo uma lista de todos os dispositivos de Proximidade e assegurando que a lista mencione pelo menos um dispositivo. Para ver um exemplo de como obter a lista de todos os dispositivos de Proximidade instalados, confira o método GetDeviceSelector.

A proximidade só é habilitada quando o aplicativo é executado em primeiro plano

Todas as operações ProximityDevice e PeerFinder são desabilitadas quando o aplicativo passa para segundo plano. Você só pode publicar e assinar mensagens ou conexões de soquete abertas quando o aplicativo é executado em primeiro plano. Se você abrir uma conexão de soquete e seu aplicativo passar para segundo plano, a conexão de soquete vai permanecer aberta.

Ativando aplicativos usando proximidade

Quando você usa o PeerFinder e toca para conectar seu aplicativo a um aplicativo par em outro dispositivo, o Windows solicita ao usuário do outro dispositivo a ativação do aplicativo, caso ele não esteja em execução ou em primeiro plano. Quando o aplicativo já está sendo executado em primeiro plano, o evento de ativação é acionado sem antes avisar o usuário. Você também pode ativar um aplicativo que não esteja sendo executado em primeiro plano chamando a sobrecarga do método PeerFinder.Start que obtém o parâmetro da cadeia de caracteres. O parâmetro da cadeia de caracteres do método Start inclui uma mensagem que é enviada ao aplicativo par. O aplicativo é ativado com a mensagem transmitida para os argumentos de ativação.

Quando você ativa um aplicativo par usando o gesto de toque, o evento Activated é acionado. O Kind de ativação é Launch. Quando você ativa o evento enviando uma mensagem através do método PeerFinder.Start, o texto da mensagem pode ser recuperado da propriedade Arguments dos argumentos de inicialização. Quando o aplicativo é ativado para abrir um StreamSocket, a propriedade Arguments retorna a cadeia de caracteres Windows.Networking.Proximity.PeerFinder:StreamSocket. Nesse caso, defina a propriedade TriggeredConnectionStateChanged como um manipulador de eventos e chame o método PeerFinder.Start para concluir a conexão de soquete.

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());
    }
}

Para ver um exemplo de aplicativo que é ativado a partir de um gesto de toque e conclui automaticamente uma conexão de soquete, veja Guia de início rápido: Usando toque ou navegação para conectar aplicativos.

Protocolo de comunicação de soquetes

Quando você envia informações a um aplicativo par usando um objeto StreamSocket, pode decidir qual protocolo prefere usar para o compartilhamento dessas informações. Por exemplo, você pode usar um formato XML, pares de nomes/valores delimitados e assim por diante. Quando a classe PeerFinder cria uma conexão de soquete entre aplicativos pares, ela conecta esses aplicativos independentemente da versão deles. Como resultado, você pode ter duas versões diferentes do seu aplicativo comunicando-se entre si. Por exemplo, se um aplicativo receptor espera dois valores de 4 bytes, e uma versão mais recente do aplicativo envia os dados como dois valores de 8 bytes para acomodar dados maiores, o aplicativo receptor que espera valores de 4 bytes irá se deparar com um erro durante o processamento dos dados. É necessário ter cautela para garantir que versões mais recentes do seu aplicativo ainda possam se comunicar com versões mais antigas dele usando seu protocolo de comunicação. Ou seja, verifique se as versões mais antigas do seu aplicativo podem ignorar novas informações enviadas de uma versão mais recente sem gerar problemas.

Dica  

Quando aplicativos pares se comunicam, você geralmente precisa determinar qual aplicativo enviará a primeira mensagem e qual aplicativo será o ouvinte. Uma maneira de determinar se o seu aplicativo é o emissor ou o ouvinte é comparar streamSocket.information.localAddress.canonicalName com streamSocket.information.remoteHostName.canonicalName. Testando se o nome do host local é maior que o nome do host remoto, você sempre receberá um resultado oposto entre duas instâncias do seu aplicativo.

Tópicos relacionados

Guia de início rápido: Usando toque ou navegação para conectar aplicativos

Guia de início rápido: Usando toque para publicar ou assinar mensagens

Diretrizes e lista de verificação para Proximidade

Testando e solucionando problemas de proximidade em aplicativos

Windows.Networking.Proximity namespace

Exemplos

Exemplo de proximidade