Геолокація - визначення місцезнаходження відвідувача
Забігаючи вперед, для тих, хто не бажає вникати в деталі,готовий приклад використання Geolocation API:
Geolocation API ґрунтується на новій властивості глобального об'єкта navigator - navigator.geolocation:
Вказівка атрибутів у третьому параметрі – справа добровільна:
- enableHighAccuracy. Значення true вказує браузеру спробувати отримати якомога точніше значення даних про місцезнаходження відвідувача сторінки сайту (широти, довготи та висоти); проте процес отримання даних може вимагати більше часу, а енергоспоживання комп'ютера може зрости. Значення false цього параметра зажадає браузеру звичайні дані про місцезнаходження, які можуть виявитися не дуже точними. Значення за промовчанням - false.
- timeout - задає тайм-аут, протягом якого мають бути отримані дані про місцезнаходження, у вигляді цілого числа в мілісекундах. Якщо вказати значення 0 або негативне значення, система має відразу видати дані про місцезнаходження; інакше виникне помилка. Якщо вказати значення Infinity (математична "плюс нескінченність"), на отримання даних про місцезнаходження буде відведено стільки часу, скільки потрібно. Стандартне значення - Infinity.
- maximumAge - задає тайм-аут, протягом якого отримані відомості про місцезнаходження будуть кешуватися системою (таймаут кешування). Тобто, якщо ми запитаємо відомості про місцезнаходження, а потім, поки таймують кешування ще не минув, зробимо це ще раз, система поверне нам кешовані відомості. Кешування даних про місцезнаходження дозволяє заощадити енергію батарей у портативних комп'ютерах. Значення цього таймауту вказується як цілого числа в мілісекундах. Якщо вказати значення 0 абонегативне значення, система взагалі не кешуватиме дані про місцезнаходження, а стане при кожному запиті отримувати їх заново. Якщо вказати значення Infinity, дані про місцезнаходження будуть зберігатися в кеші завжди, і саме вони будуть повертатися при запиті (наприклад, вам потрібно знати тільки місто користувача). Значення за промовчанням - 0 (тобто кешування вимкнено).
Браузер без дозволу користувача не передасть дані про твоє місцезнаходження на віддалений сервер. У різних браузерах таке питання до користувача може виглядати по-різному, наприклад, Firefox — це буде спливаюча панель у верхній частині вікна.
Функція, що викликається, отримує один параметр — об'єкт з двома властивостями: coords і timestamp. Timestamp - це дата і час, при яких було зроблено визначення місцезнаходження. Визначення цих властивостей відбувається асинхронно. Не можна заздалегідь передбачити, коли точно це станеться. Для користувача це може означати деяку затримку, тому що потрібно спочатку прочитати панель і переконається, що користувач дав дозвіл на визначення координат, потім може знадобитися час на підключення пристрою до супутника і так далі. Об'єкт coords має властивості latitude (широта) і longitude (довгота) - це і є інформація про фізичне становище на земній кулі. Властивості об'єкта наведені нижче:
| coords.latitude | double | десяткові градуси |
| coords.longitude | double | десяткові градуси |
| coords.altitude | double або null | метрів над референц-еліпсоїдом |
| coords.accuracy | double | метри |
| coords.altitudeAccuracy | double або null | метри |
| coords.heading | double або null | градус за годинниковою стрілкою щодо Північного полюса |
| coords.speed | double або null | метри/сек |
| timestamp | DOMTimeStamp | такий же як об'єкт Date() |
Гарантовано будуть лише три властивості: coords.latitude, coords.longitude і coords.accuracy. Працездатність інших залежить від використовуваного користувачем пристрою. Якщо ця властивість не підтримується – повернеться 0. Властивості heading та speed обчислюються на підставі зміни положення користувача, якщо, звичайно, це можливо.
Другий аргумент для функції getCurrentPosition() для виклику обробника помилок:
Функція обробки помилок з об'єктом PositionError, який має такі властивості:
| code | short | пронумеровані значення |
| message | DOMString | не призначений для кінцевих користувачів |
Властивість code набуває одного з наступних значень:
- PERMISSION_DENIED (1) - коли користувач не дозволяє визначення місця розташування;
- POSITION_UNAVAILABLE (2) - якщо перебої з мережею чи ні зв'язку з супутником;
- TIMEOUT (3) — якщо мережа працює погано і на обчислення координат користувача потрібно багато часу. Що означає «надто багато»? Про це розповім пізніше;
- UNKNOWN_ERROR (0) – будь-яка інша помилка.
Функція getCurrentPosition() має необов'язковий третій аргумент, об'єкт PositionOptions. Всі властивості є необов'язковими, ви можете задати будь-який, всі або жодні.
| enableHighAccuracy | boolean | false | Якщо true, то повільніше |
| timeout | long | Ні | У мілісекундах |
| maximumAge | long | 0 | У мілісекундах |
Властивість timeout це кількість мілісекунд, яку веб-додаток буде очікувати на отримання положення. Таймер не починає відлік, поки користувач не дозволить спробу обчислити його положення. Він стежить не за користувачем, а за мережею.
Властивість maximumAge дозволяє пристрою відповідати негайно із закешованої позиції. Наприклад, ви звертаєтеся до getCurrentPosition() вперше, користувач погоджується, і ваша функція успішно повертає положення обчислене рівно о 10:00. Рівно через хвилину, о 10:01 ви викликаєте getCurrentPosition() знову встановивши властивість maximumAge 75000.
Ви кажете, що вам необов'язково знати поточне положення користувача. Ви були б раді знати, де він був 75 секунд тому (75000 мілісекунд). Пристрій знає, де користувач був 60 секунд тому (60000 мілісекунд), оскільки він розрахував місце після першого виклику getCurrentPosition(). Тому пристрій не перераховуватиме поточне розташування користувача. Воно поверне ту ж інформацію, що і вперше: ту ж широту і довготу, ту саму точність і той самий час (10:00).
Перш ніж ви запитаєте розташування користувача, ви повинні подумати про те, яка точність вам потрібно, і встановити відповідне enableHighAccuracy. Якщо вам потрібно знайти місце ще раз, ви повинні подумати про те, яка стара інформація може стати в нагоді і встановити відповідне maximumAge. Якщо потрібно шукатилокацію постійно, то getCurrentPosition() не для вас, необхідно перейти на watchPosition().
Фукнція watchPosition() має таку ж структуру як і getCurrentPosition(). Вона містить дві функції, одна потрібна для успіху, друга для помилок, також може мати необов'язковий об'єкт PositionOptions, він має ті ж властивості, про які ви дізналися раніше. Різниця в тому, що ваша функція буде викликатися щоразу при зміні розташування користувача. Немає необхідності постійного опитування позиції, пристрій визначить оптимальний інтервал опитування і викличе функцію при зміні положення користувача. Ви можете використовувати цю можливість для оновлення видимих маркерів на карті, надання інструкції, куди йти далі або ще. Це повністю залежить від вас.
4. "Підписка" на отримання відомостей про місцезнаходження
Щоб виконати підписку на постійне отримання даних про місцезнаходження, слід скористатися методом watchPosition об'єкта Geolocation. Формат його виклику такий:
Цей метод приймає самі параметри, як і знайомий нам за параграфом 3 метод getCurrentPosition.
Метод watchPosition повертає особливу цілочисельну величину, яка називається ідентифікатором "підписки". Цей ідентифікатор слід зберегти в будь-якій змінній; згодом ми можемо використовувати його для скасування "підписки" на отримання даних про місцезнаходження. Втім, якщо ми не збираємося скасовувати "підписку", ідентифікатор, повернутий методом watchPosition, можна проігнорувати.
При першому виклику методу watchPosition відразу ж запуститься операція з отримання поточного розташування. Якщо вона увінчається успіхом, буде викликана функція, передана даному методу першим параметром, інакше - функція, передана другимпараметром. Як бачимо, все те саме, що й у випадку методу getCurrentPosition.
Виконану раніше "підписку" на отримання інформації про місцезнаходження можна скасувати. Для цього застосовується метод clearWatch об'єкта Geolocation. Як єдиний параметр він приймає ідентифікатор "підписки", яку потрібно скасувати. Результату він не повертає.