Spec-Zone.ru › Cordova 7

cordova-plugin-geolocation

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

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

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

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

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

Этот плагин определяет глобальный 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 });

geolocationOptions

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

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

Параметры

  • enableHighAccuracy: Подсказка о том, что приложение нуждается в наилучших результатах. По умолчанию устройство пытается получить Position с помощью методов, основанных на сети. Установка этого свойства в 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 миллисекунд.

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

Используйте этот плагин, чтобы помочь пользователям находить объекты рядом с ними, такие как предложения 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.

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

<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/7.x/reference/cordova-plugin-geolocation/index.html

Spec-Zone.ru

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