Spec-Zone.ru › Cordova 6

cordova-plugin-geolocation

Этот плагин предоставляет информацию о местоположении устройства, например, широту и долготу.

Общие источники информации о местоположении включают Глобальную систему позиционирования (GPS) и местоположение, определяемое по сигналам сети, таким как IP-адрес, RFID, WiFi и Bluetooth MAC-адреса и идентификаторы ячеек GSM/CDMA. Нет гарантии, что API возвращает фактическое местоположение устройства.

Чтобы получить несколько идей, ознакомьтесь с примером внизу этой страницы или перейдите непосредственно к справочной информации.

Этот API основан на спецификации W3C Geolocation API и выполняется только на устройствах, которые еще не предоставляют реализацию.

ПРЕДУПРЕЖДЕНИЕ: Сбор и использование данных о местоположении поднимают важные вопросы конфиденциальности. Политика конфиденциальности вашего приложения должна обсуждать, как приложение использует данные о местоположении, делится ли оно ими с другими сторонами и каков уровень точности данных (например, грубый, точный, уровень почтового индекса и т. д.). Данные о местоположении обычно считаются конфиденциальными, так как они могут раскрывать местонахождение пользователя и, если хранятся, историю его перемещений. Поэтому, помимо политики конфиденциальности приложения, следует серьезно рассмотреть возможность предоставления своевременного уведомления перед доступом приложения к данным о местоположении (если операционная система устройства этого не делает). Это уведомление должно содержать ту же информацию, что и выше, а также получить разрешение пользователя (например, представив варианты ОК и Отклонить). Для получения дополнительной информации см. Руководство по конфиденциальности.

Этот плагин определяет глобальный navigator.geolocation объект (для платформ, где он отсутствует).

Хотя объект находится в глобальной области видимости, функции, предоставляемые этим плагином, недоступны до события deviceready. 

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log("navigator.geolocation works well");
}

Справочная информация

Установка

Требуется cordova 5.0+ (текущая стабильная версия 1.0.0)

cordova plugin add cordova-plugin-geolocation

Старые версии cordova все еще могут устанавливаться через устаревший идентификатор (устаревший 0.3.12)

cordova plugin add org.apache.cordova.geolocation

Также можно установить через URL репозитория напрямую (нестабильно)

cordova plugin add https://github.com/apache/cordova-plugin-geolocation.git

Поддерживаемые платформы

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Tizen
  • Windows Phone 7 и 8
  • Windows

Методы

  • navigator.geolocation.getCurrentPosition
  • navigator.geolocation.watchPosition
  • navigator.geolocation.clearWatch

Объекты (только для чтения)

  • Position
  • PositionError
  • Coordinates

navigator.geolocation.getCurrentPosition

Возвращает текущее положение устройства в geolocationSuccess обратный вызов с Position объектом в качестве параметра. При ошибке geolocationError обратный вызов получает PositionError объект.

navigator.geolocation.getCurrentPosition(geolocationSuccess,
                                         [geolocationError],
                                         [geolocationOptions]);

Параметры

  • geolocationSuccess: Обратный вызов, которому передается текущее положение.

  • geolocationError: (Необязательно) Обратный вызов, который выполняется при возникновении ошибки.

  • geolocationOptions: (Необязательно) Параметры геолокации.

Пример

// onSuccess Callback
// This method accepts a Position object, which contains the
// current GPS coordinates
//
var onSuccess = function(position) {
    alert('Latitude: '          + position.coords.latitude          + '\n' +
          'Longitude: '         + position.coords.longitude         + '\n' +
          'Altitude: '          + position.coords.altitude          + '\n' +
          'Accuracy: '          + position.coords.accuracy          + '\n' +
          'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
          'Heading: '           + position.coords.heading           + '\n' +
          'Speed: '             + position.coords.speed             + '\n' +
          'Timestamp: '         + position.timestamp                + '\n');
};

// onError Callback receives a PositionError object
//
function onError(error) {
    alert('code: '    + error.code    + '\n' +
          'message: ' + error.message + '\n');
}

navigator.geolocation.getCurrentPosition(onSuccess, onError);

Особенности iOS

Начиная с iOS 10, необходимо добавить запись NSLocationWhenInUseUsageDescription в info.plist.

NSLocationWhenInUseUsageDescription описывает причину доступа приложения к местоположению пользователя. Когда система запросит у пользователя разрешение на доступ, эта строка будет отображаться в диалоговом окне. Чтобы добавить эту запись, вы можете передать переменную GEOLOCATION_USAGE_DESCRIPTION при установке плагина.

Пример: cordova plugin add cordova-plugin-geolocation --variable GEOLOCATION_USAGE_DESCRIPTION="your usage message"

Если переменная не передается, плагин добавит пустую строку в качестве значения.

Особенности Android

Если служба геолокации выключена, onError обратный вызов вызывается после timeout интервала (если указан). Если timeout параметр не указан, обратный вызов не вызывается.

navigator.geolocation.watchPosition

Возвращает текущее положение устройства при обнаружении изменения местоположения. При получении устройства нового местоположения geolocationSuccess обратный вызов выполняется с Position объектом в качестве параметра. При ошибке geolocationError обратный вызов выполняется с PositionError объектом в качестве параметра.

var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
                                                  [geolocationError],
                                                  [geolocationOptions]);

Параметры

  • geolocationSuccess: Обратный вызов, которому передается текущее положение.

  • geolocationError: (Необязательно) Обратный вызов, который выполняется при возникновении ошибки.

  • geolocationOptions: (Необязательно) Параметры геолокации.

Возвращаемое значение

  • Строка: возвращает идентификатор наблюдения, который ссылается на интервал наблюдения местоположения. Идентификатор наблюдения следует использовать с navigator.geolocation.clearWatch для остановки наблюдения за изменениями местоположения.

Пример

// onSuccess Callback
//   This method accepts a `Position` object, which contains
//   the current GPS coordinates
//
function onSuccess(position) {
    var element = document.getElementById('geolocation');
    element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
                        'Longitude: ' + position.coords.longitude     + '<br />' +
                        '<hr />'      + element.innerHTML;
}

// onError Callback receives a PositionError object
//
function onError(error) {
    alert('code: '    + error.code    + '\n' +
          'message: ' + error.message + '\n');
}

// Options: throw an error if no update is received every 30 seconds.
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 });

Параметры геолокации

Необязательные параметры для настройки получения данных о местоположении Position. 

{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };

Параметры

  • enableHighAccuracy: Указывает, что приложение нуждается в наилучших возможных результатах. По умолчанию устройство пытается получить местоположение с помощью методов, основанных на сети. Установка этого свойства в true заставляет фреймворк использовать более точные методы, такие как спутниковое позиционирование. (Булево значение)

  • timeout: Максимальное время (в миллисекундах), которое может пройти с вызова navigator.geolocation.getCurrentPosition или geolocation.watchPosition до выполнения соответствующего geolocationSuccess обратного вызова. Если geolocationSuccess обратный вызов не будет вызван в течение этого времени, geolocationError обратный вызов получает PositionError.TIMEOUT код ошибки. (Обратите внимание, что при использовании совместно с geolocation.watchPosition, geolocationError обратный вызов может вызываться с интервалом в timeout миллисекунд!) (Число)

  • maximumAge: Принять кэшированное местоположение, если его возраст не превышает указанное время в миллисекундах. (Число)

Особенности Android

Если служба геолокации выключена, onError обратный вызов вызывается после timeout интервала (если указан). Если timeout параметр не указан, обратный вызов не вызывается.

navigator.geolocation.clearWatch

Остановить наблюдение за изменениями местоположения устройства, на которое ссылается watchID параметр.

navigator.geolocation.clearWatch(watchID);

Параметры

  • watchID: Идентификатор watchPosition интервала для удаления. (Строка)

Пример

// Options: watch for changes in position, and use the most
// accurate position acquisition method available.
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true });

// ...later on...

navigator.geolocation.clearWatch(watchID);

Position

Содержит Position координаты и метку времени, созданные API геолокации.

Свойства

  • coords: Набор географических координат. (Coordinates)

  • timestamp: Метка времени создания coords. (DOMTimeStamp)

Coordinates

Объект Coordinates прикреплен к объекту Position, который доступен для обратных вызовов функций в запросах для текущего местоположения. Он содержит набор свойств, описывающих географические координаты местоположения.

Свойства

  • latitude: Широта в десятичных градусах. (Число)

  • longitude: Долгота в десятичных градусах. (Число)

  • altitude: Высота местоположения в метрах над эллипсоидом. (Число)

  • accuracy: Уровень точности координат широты и долготы в метрах. (Число)

  • altitudeAccuracy: Уровень точности координаты высоты в метрах. (Число)

  • heading: Направление движения в градусах, отсчитываемое по часовой стрелке относительно истинного севера. (Число)

  • speed: Текущая скорость движения устройства в метрах в секунду. (Число)

Особенности Amazon Fire OS

altitudeAccuracy: Не поддерживается устройствами Android, возвращает null.

Особенности Android

altitudeAccuracy: Не поддерживается устройствами Android, возвращает null.

PositionError

Объект PositionError передается в geolocationError обратный вызов функции при возникновении ошибки с navigator.geolocation.

Свойства

  • code: Один из предопределенных кодов ошибок, перечисленных ниже.

  • message: Сообщение об ошибке, описывающее подробности возникшей ошибки.

Постоянные значения

  • PositionError.PERMISSION_DENIED
    • Возвращается, когда пользователи не разрешают приложению получать информацию о местоположении. Это зависит от платформы.
  • PositionError.POSITION_UNAVAILABLE
    • Возвращается, когда устройство не может получить местоположение. В общем случае это означает, что устройство не подключено к сети или не может получить спутниковый сигнал.
  • PositionError.TIMEOUT
    • Возвращается, когда устройство не может получить местоположение в течение времени, указанного в timeout, включенном в geolocationOptions. При использовании с navigator.geolocation.watchPosition, эта ошибка может многократно передаваться в geolocationError обратный вызов каждые timeout миллисекунд.

Пример: Получение погоды, поиск магазинов и просмотр фотографий близлежащих объектов с помощью Geolocation

Используйте этот плагин, чтобы помочь пользователям находить объекты рядом с ними, такие как предложения Groupon, дома на продажу, киносеансы, спортивные и развлекательные мероприятия и многое другое.

Вот несколько идей для начала работы. В приведенных ниже примерах мы покажем несколько основных способов добавления этих функций в ваше приложение.

  • Получение ваших координат.
  • Получение прогноза погоды.
  • Получение обновленных прогнозов погоды по мере движения.
  • Просмотр вашего местоположения на карте.
  • Поиск магазинов рядом с вами.
  • Просмотр фотографий объектов вокруг вас.

Получение ваших географических координат

function getWeatherLocation() {

    navigator.geolocation.getCurrentPosition
    (onWeatherSuccess, onWeatherError, { enableHighAccuracy: true });
}

Получение прогноза погоды

// Success callback for get geo coordinates

var onWeatherSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getWeather(Latitude, Longitude);
}

// Get weather by using coordinates

function getWeather(latitude, longitude) {

    // Get a free key at http://openweathermap.org/. Replace the "Your_Key_Here" string with that key.
    var OpenWeatherAppKey = "Your_Key_Here";

    var queryString =
      'http://api.openweathermap.org/data/2.5/weather?lat='
      + latitude + '&lon=' + longitude + '&appid=' + OpenWeatherAppKey + '&units=imperial';

    $.getJSON(queryString, function (results) {

        if (results.weather.length) {

            $.getJSON(queryString, function (results) {

                if (results.weather.length) {

                    $('#description').text(results.name);
                    $('#temp').text(results.main.temp);
                    $('#wind').text(results.wind.speed);
                    $('#humidity').text(results.main.humidity);
                    $('#visibility').text(results.weather[0].main);

                    var sunriseDate = new Date(results.sys.sunrise);
                    $('#sunrise').text(sunriseDate.toLocaleTimeString());

                    var sunsetDate = new Date(results.sys.sunrise);
                    $('#sunset').text(sunsetDate.toLocaleTimeString());
                }

            });
        }
    }).fail(function () {
        console.log("error getting location");
    });
}

// Error callback

function onWeatherError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

Получение обновленных прогнозов погоды по мере движения

// Watch your changing position

function watchWeatherPosition() {

    return navigator.geolocation.watchPosition
    (onWeatherWatchSuccess, onWeatherError, { enableHighAccuracy: true });
}

// Success callback for watching your changing position

var onWeatherWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        // Calls function we defined earlier.
        getWeather(updatedLatitude, updatedLongitude);
    }
}

Просмотр вашего местоположения на карте

У Bing и Google есть сервисы карт. Мы будем использовать Google. Вам понадобится ключ, но он бесплатный, если вы только пробуете.

Добавьте ссылку на службу карт.

<script src="https://maps.googleapis.com/maps/api/js?key=Your_API_Key"></script>

Затем добавьте код для его использования.

var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getMapLocation() {

    navigator.geolocation.getCurrentPosition
    (onMapSuccess, onMapError, { enableHighAccuracy: true });
}

// Success callback for get geo coordinates

var onMapSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getMap(Latitude, Longitude);

}

// Get map by using coordinates

function getMap(latitude, longitude) {

    var mapOptions = {
        center: new google.maps.LatLng(0, 0),
        zoom: 1,
        mapTypeId: google.maps.MapTypeId.ROADMAP
    };

    map = new google.maps.Map
    (document.getElementById("map"), mapOptions);


    var latLong = new google.maps.LatLng(latitude, longitude);

    var marker = new google.maps.Marker({
        position: latLong
    });

    marker.setMap(map);
    map.setZoom(15);
    map.setCenter(marker.getPosition());
}

// Success callback for watching your changing position

var onMapWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getMap(updatedLatitude, updatedLongitude);
    }
}

// Error callback

function onMapError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchMapPosition() {

    return navigator.geolocation.watchPosition
    (onMapWatchSuccess, onMapError, { enableHighAccuracy: true });
}

Поиск магазинов рядом с вами

Вы можете использовать тот же ключ Google для этого.

Добавьте ссылку на службу places.

<script src=
"https://maps.googleapis.com/maps/api/js?key=Your_API_Key&libraries=places">
</script>

Затем добавьте код для его использования.

var Map;
var Infowindow;
var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getPlacesLocation() {
    navigator.geolocation.getCurrentPosition
    (onPlacesSuccess, onPlacesError, { enableHighAccuracy: true });
}

// Success callback for get geo coordinates

var onPlacesSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getPlaces(Latitude, Longitude);

}

// Get places by using coordinates

function getPlaces(latitude, longitude) {

    var latLong = new google.maps.LatLng(latitude, longitude);

    var mapOptions = {

        center: new google.maps.LatLng(latitude, longitude),
        zoom: 15,
        mapTypeId: google.maps.MapTypeId.ROADMAP

    };

    Map = new google.maps.Map(document.getElementById("places"), mapOptions);

    Infowindow = new google.maps.InfoWindow();

    var service = new google.maps.places.PlacesService(Map);
    service.nearbySearch({

        location: latLong,
        radius: 500,
        type: ['store']
    }, foundStoresCallback);

}

// Success callback for watching your changing position

var onPlacesWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getPlaces(updatedLatitude, updatedLongitude);
    }
}

// Success callback for locating stores in the area

function foundStoresCallback(results, status) {

    if (status === google.maps.places.PlacesServiceStatus.OK) {

        for (var i = 0; i < results.length; i++) {

            createMarker(results[i]);

        }
    }
}

// Place a pin for each store on the map

function createMarker(place) {

    var placeLoc = place.geometry.location;

    var marker = new google.maps.Marker({
        map: Map,
        position: place.geometry.location
    });

    google.maps.event.addListener(marker, 'click', function () {

        Infowindow.setContent(place.name);
        Infowindow.open(Map, this);

    });
}

// Error callback

function onPlacesError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchPlacesPosition() {

    return navigator.geolocation.watchPosition
    (onPlacesWatchSuccess, onPlacesError, { enableHighAccuracy: true });
}

Просмотр фотографий объектов вокруг вас

Цифровые фотографии могут содержать геокоординаты, определяющие место съемки фотографии.

Используйте API Flickr, чтобы найти фотографии, сделанные людьми рядом с вами. Как и в службах Google, вам понадобится ключ, но он бесплатный, если вы просто хотите попробовать.

var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getPicturesLocation() {

    navigator.geolocation.getCurrentPosition
    (onPicturesSuccess, onPicturesError, { enableHighAccuracy: true });

}

// Success callback for get geo coordinates

var onPicturesSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getPictures(Latitude, Longitude);
}

// Get pictures by using coordinates

function getPictures(latitude, longitude) {

    $('#pictures').empty();

    var queryString =
    "https://api.flickr.com/services/rest/?method=flickr.photos.search&api_key=Your_API_Key&lat="
    + latitude + "&lon=" + longitude + "&format=json&jsoncallback=?";

    $.getJSON(queryString, function (results) {
        $.each(results.photos.photo, function (index, item) {

            var photoURL = "http://farm" + item.farm + ".static.flickr.com/" +
                item.server + "/" + item.id + "_" + item.secret + "_m.jpg";

            $('#pictures').append($("<img />").attr("src", photoURL));

           });
        }
    );
}

// Success callback for watching your changing position

var onPicturesWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getPictures(updatedLatitude, updatedLongitude);
    }
}

// Error callback

function onPicturesError(error) {

    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchPicturePosition() {

    return navigator.geolocation.watchPosition
    (onPicturesWatchSuccess, onPicturesError, { enableHighAccuracy: true });
}

© 2012, 2013, 2015 The Apache Software Foundation
Licensed under the Apache License 2.0.
https://cordova.apache.org/docs/en/6.x/reference/cordova-plugin-geolocation/index.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API