cordova-plugin-geolocation

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

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

Для получения некоторых идей ознакомьтесь с примером внизу этой страницы или перейдите непосредственно к ссылке.

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

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

Этот плагин определяет глобальный 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/9.x/reference/cordova-plugin-geolocation/index.html