Configurar uma cerca geográfica (HTML)

Artigo
12/12/2015

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

Este tópico guia você pelas etapas de configuração de uma Geofence no seu aplicativo.

Mapa: como este tópico está relacionado aos outros? Veja:

Mapa de aplicativos que usam JavaScript

Introdução

Há várias etapas a serem seguidas para configurar seu Geofence. Além de definir a região de interesse, você também precisa ter as permissões de localização adequadas. Por fim, você precisa configurar um manipulador de eventos caso o usuário mude essas permissões durante a execução do aplicativo.

Verificar se a localização está habilitada

Para que seu aplicativo possa acessar a localização, é necessário habilitar Localização no dispositivo. No aplicativo Configurações, verifique se as seguintes configurações de privacidade de localização estão ativadas:

Localização deste dispositivo... está ativada (não aplicável no Windows 10 Mobile)
A configuração de serviços de localização, Localização, está ativada
Em Choose apps that can use your location, seu aplicativo está definido como ativado

Habilitar o recurso de localização

Clique duas vezes em package.appxmanifest no Gerenciador de Soluções e selecione a guia Funcionalidades. Em seguida, selecione Localização na lista Funcionalidades. Isso adiciona a funcionalidade Location do dispositivo ao arquivo de manifesto do pacote.

  <Capabilities>
    <!-- DeviceCapability elements must follow Capability elements (if present) -->
    <DeviceCapability Name="location"/>
  </Capabilities>

Verificar permissões de localização

Primeiro, você pode querer adicionar código ao seu aplicativo durante a inicialização para obter a localização. Na primeira vez em que o aplicativo usa a API para obter a localização atual, o sistema solicita que o usuário tenha permissão de localização. Se o aplicativo não tiver permissão do usuário, alerte o usuário. Observe que você ainda pode configurar um Geofence sem as permissões de localização, mas não receberá nenhuma notificação até as permissões serem habilitadas.

    function initialize() {

        promise = geolocator.getGeopositionAsync();
        promise.done(
            function (pos) {
                var coord = pos.coordinate;

            },
            function (err) {
            // handle situations where location permissions are not granted to your app
            }
        );

    }

Escutar alterações de permissão de localização

Em seguida, é melhor registrar eventos de alteração de permissão, caso o usuário decida desabilitar as permissões de localização por algum motivo. Primeiro, adicione os manipuladores de eventos a seu método de inicialização:


var accessInfo = null;
accessInfo = DeviceAccessInformation.createFromDeviceClass(Enumeration.DeviceClass.location);
accessInfo.addEventListener("accesschanged", onAccessChanged);

Depois manipule a alteração de permissões para que o usuário saiba que a cerca geográfica não vai mais funcionar se as permissões de localização forem desabilitadas:

function onAccessChanged(args) {
    var eventDescription = getTimeStampedMessage("Device Access Status");
    var item = null;

    if (DeviceAccessStatus.deniedByUser === args.status) {
        eventDescription += " (DeniedByUser)";

        WinJS.log && WinJS.log("Location has been disabled by the user. Enable access through the settings charm.", "sample", "status");
    } else if (DeviceAccessStatus.deniedBySystem === args.status) {
        eventDescription += " (DeniedBySystem)";

        WinJS.log && WinJS.log("Location has been disabled by the system. The administrator of the device must enable location access through the location control panel.", "sample", "status");
    } else if (DeviceAccessStatus.unspecified === args.status) {
        eventDescription += " (Unspecified)";

        WinJS.log && WinJS.log("Location has been disabled by unspecified source. The administrator of the device may need to enable location access through the location control panel, then enable access through the settings charm.", "sample", "status");
    } else if (DeviceAccessStatus.allowed === args.status) {
        eventDescription += " (Allowed)";

        // clear status
        WinJS.log && WinJS.log("", "sample", "status");
    } else {
        eventDescription += " (Unknown)";

        WinJS.log && WinJS.log("Unknown device access information status", "sample", "status");
    }

    addEventDescription(eventDescription);
}

Observação Você pode determinar se o usuário desabilitou a localização em Configurações verificando a propriedade LocationStatus. Se o valor for Disabled, então a localização foi desabilitada.

Criar a cerca geográfica

Agora você está pronto para definir e configurar uma cerca geográfica. Alguns dos valores que podem ser definidos para a cerca geográfica são:

Uma Id para identificá-lo.
A região circular de interesse, definida pelo Geoshape.
Os MonitoredStates, que indicam os eventos de cerca geográfica para os quais você deseja receber notificações: entrada na região definida, saída da região definida ou remoção da cerca geográfica.
Um sinalizador SingleUse, que remove a cerca geográfica quando todos os estados que estão sendo monitorados na cerca geográfica são cumpridos.
Um DwellTime, que indica por quanto tempo o usuário deve permanecer dentro ou fora da área definida para que os eventos de entrada/saída sejam disparados.
O StartTime, que indica quando começar a monitorar a cerca geográfica.
A Duration de monitoração da cerca geográfica.


function generateGeofence() {
    var geofence = null;

    try {
        var fenceKey = nameElement.value;

        var position = {
            latitude: decimalFormatter.parseDouble(latitude.value),
            longitude: decimalFormatter.parseDouble(longitude.value),
            altitude: 0
        };
        var radiusValue = decimalFormatter.parseDouble(radius.value);

        // the geofence is a circular region
        var geocircle = new Windows.Devices.Geolocation.Geocircle(position, radiusValue);

        var singleUse = false;

        if (geofenceSingleUse.checked) {
            singleUse = true;
        }

        // want to listen for enter geofence, exit geofence and remove geofence events
        var mask = 0;

        mask = mask | Windows.Devices.Geolocation.Geofencing.MonitoredGeofenceStates.entered;
        mask = mask | Windows.Devices.Geolocation.Geofencing.MonitoredGeofenceStates.exited;
        mask = mask | Windows.Devices.Geolocation.Geofencing.MonitoredGeofenceStates.removed;

        var dwellTimeSpan = new Number(parseTimeSpan(dwellTimeField, defaultDwellTimeSeconds));
        var durationTimeSpan = null;
        if (durationField.value.length) {
            durationTimeSpan = new Number(parseTimeSpan(durationField, 0));
        } else {
            durationTimeSpan = new Number(0); // duration needs to be set since start time is set below
        }
        var startDateTime = null;
        if (startTimeField.value.length) {
            startDateTime = new Date(startTimeField.value);
        } else {
            startDateTime = new Date(); // if you don't set start time in JavaScript the start time defaults to 1/1/1601
        }

        geofence = new Windows.Devices.Geolocation.Geofencing.Geofence(fenceKey, geocircle, mask, singleUse, dwellTimeSpan, startDateTime, durationTimeSpan);
    } catch (ex) {
        WinJS.log && WinJS.log(ex.toString(), "sample", "error");
    }

    return geofence;
}