Spec-Zone.ru › Cordova 8

cordova-plugin-geolocation

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

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

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

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

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

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

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

  • Android
  • iOS
  • 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 обязательно нужно указать описание использования в info.plist при попытке доступа к данным, чувствительным к конфиденциальности. При запросе разрешения доступа пользователем это описание отобразится в диалоговом окне разрешения, но если вы не предоставили описание использования, приложение аварийно завершит работу, прежде чем отобразить диалог. Кроме того, Apple отклонит приложения, которые обращаются к частным данным, но не предоставляют описание использования.

Этот плагин требует следующего описания использования:

  • NSLocationWhenInUseUsageDescription описывает причину доступа приложения к местоположению пользователя.

Чтобы добавить эту запись в info.plist, можно использовать тег edit-config в config.xml следующим образом:

<edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
    <string>need location access to find things nearby</string>
</edit-config>

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

Особенности 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/8.x/reference/cordova-plugin-geolocation/index.html

Spec-Zone.ru

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