Google's beacon platform — это решение для работы с Bluetooth маячками. Платформа работает с разными маячками от разных производителей, предоставляя разработчикам единый, простой и гибкий инструмент.

Перед прочтением этой статьи я рекомендую ознакомиться с концепцией Physical Web о которой я рассказывал в своей прошлой статье: Концепция Physical web. Bluetooth маячки. Сравнение стандартов iBeacon, AltBeacon и Eddystone.

Google's beacon platform. Часть 1 — Proximity beacon API
Google's beacon platform. Часть 2 — Nearby meassages API

Google's beacon platform позволяет нам избежать необходимости физического контакта с маячками для их переконфигурирования, как и в случае с Physical Web, когда мы транслируем обычный URL(Eddystone-URL), мы можем лишь менять вложения которые привязаны к маячкам, тем самым управлять маячками удаленно. Данное решение так же позволяет мониторить все наши маячки удаленно. Как это реализовано я расскажу дальше.

Как видно из схемы, для администрирования маячков нам предоставляется Google Proximity Beacon API, с помощью которого мы можем регистрировать наши устройства в Google Beacons Registry. В нём хранится информация о зарегистрированных маячках. С клиентской стороны, для взаимодействия с устройствами предлагается использовать Nearby Messages API, Places API или что то ещё на ваше усмотрение.

Если коротко, при такой схеме работы маячки транслируют Advertisment ID (Eddystone-UID), к которому мы можем привязввать некие вложения (Attachments), о которых я подробно расскажу ниже. После того как мы обнаружили маячок нашим смартфоном или планшетом, мы делаем запрос по его Advertisment ID в Beacons Registry, а ответом получаем это самое вложение. Такой сценарий отлично подходит когда нам необходимо сделать не публичное приложение для специального или внутреннего использования. Или когда мы хотим добавить в уже имеющееся, популярное у пользователей, приложение возможность работы с маячками, например для навигации или получения каких то дополнительных данных.

Т.е. нам обязательно нужно приложение, а как же Physical Web???

Благодаря тому что некоторые маячки умеют рассылать сразу два типа пакетов одновременно, например, Eddystone-URL или Eddystone-UID, мы можем обеспечить наше приложение дополнительными метаданными, а пользователей без приложения, самим приложением!

Google Proximity Beacon API

Google Proximity Beacon API — это облачный сервис, который через REST интерфейс позволяет управлять маячками, а точнее связанными с ними данными.

Proximity Beacon API позволяет:

Регистрировать устройства
Присоединять вложения к маячкам
Мониторить устройства
Получать вложения от маячков

Перед использованием Proximity Beacon API, будет полезно понимать или ознакомиться со следующим:

Использование OAuth 2.0 для доступа к Google API
RESTfull web сервисы
JSON представление данных

Для работы с Proximity Beacon API необходимо выполнить 5 следующих шагов:

Создать или зайти в Google Account
Создать новый проект или выбрать существующий в консоли разработчика Google
Активировать Proximity Beacon API — в консоли разработчика Google нажмите Select a project и выберите проект который вы хотите использовать. В левом, боковом меню нажмите на API Мanager, затем найдите Proximity Beacon API и установите его статусу значение enabled
Получить OAuth 2.0 client ID
Получить API KEY. Крайне советую ознакомиться с Best practices for securely using API keys

Осторожно, gif! Пункты 1,2 и 3

Осторожно, gif! Пункт 4

Осторожно, gif! Пункт 5

Регистрация маячков

После включения и базовой настройки маячка на трансляцию сообщений, Proximity Beacon API может быть использован для его регистрации. К нему мы можем привязать дополнительные данные, которые помогут устройствам пользователей понять где они находятся. Запись в Google Beacons Registry может содержать следующие метаданные:

Advertised ID (обязательно)
Текущий статус — активный, не активный, выведенный из эксплуатации.
Стабильность — выражает ожидаемую стабильность размещения. (Стабильный, редко перемещаемый, часто перемещаемый, постоянно перемещающийся)
Широта и долгота — пара double представляющих значение в градусах. Должны соответствовать представлению WGS84, если не указано иное. Значения должны быть в пределах нормализованных диапазонов.
Увроень внутри здания — человеко читаемая строка, что бы указать на каком этаже расположен маячок.
Google Places API Place ID
Текстовое описание
Произвольные свойства, такие как пара ключ/значение

Подробнее о значениях метаданных вы можете прочитать здесь.

Это и есть те самые дополнительные метаданные о которых я говорил в начале статьи, они могут быть использованы нашим приложением для своих нужд или улучшения общего UX. Например, мы можем использовать Google Places API Place ID для Place Picker. Place Picker — это диалог, который отображает интерактивную карту ближайших мест, организаций, заведений и т.д. Пользователь можете получить информацию о каком то близлежащем месте или поделиться в соц.сетях информацией о том месте где сейчас находится. Place Picker являются частью Places API и доступен на обоих платформах Android и iOS.

Рассылаемый ID (Advertised ID) должын быть корректным Eddystone-UID идентификатором маячка (16 байт, содержащих 10 байт namespaceId и 6 байт instance Id). Значение ID должно быть base64 представлением данных.

Маячки представлены в виде ресурса beacon и могут быть зарегистрированы вызовом метода beacons.register.

О других методах вы можете посмотреть здесь.

Маячок может быть зарегистрирован одновременно только в одном проекте в Google Developers Console. Попытка зарегистрировать маячок повторно или в другом проекте приведет к ошибке. Как только маячок зарегистрирован, его поле AdvertisedID не может быть изменено.

Поэтому обязательно настройте ваши маячки соответствующим образом перед регистрацией.

Пример показывает как зарегистрировать Eddystone маячок в определенном месте:

HTTP method:
POST

Request URL:
https://proximitybeacon.googleapis.com/v1beta1/beacons:register

Request body:

{
  "advertisedId": {
    "type": "EDDYSTONE",
    "id": "Fr4Z98nSoW0hgAAAAAAAAg=="
  },
  "status": "ACTIVE",
  "placeId": "ChIJTxax6NoSkFQRWPvFXI1LypQ",
  "latLng": {
    "latitude": "47.6693771",
    "longitude": "-122.1966037"
  },
  "indoorLevel": {
    "name": "1"
  },
  "expectedStability": "STABLE",
  "description": "An example beacon.",
  "properties": {
    "position": "entryway"
  }
}

Response:
Если всё прошло удачно, ответом будет статус код: 200 ОК. Тело ответа содержит JSON представление маячка, содержащее значение beacon.beaconName, которое может использоваться как ссылка для управления маячком.

Отмена регистрации

После того, как маяк был зарегистрирован, он не может быть просто удален из Google Beacons Registry. Есть два варианта как можно перевести маячок в режим офлайн:

Вызвать beacons.deactivate для того что бы временно удалить маячок из нашего проекта. После деактивации, API не будет возвращать ни привязанные данные, ни информацию по маячку. Для того что вернуть маяк в рабочее состояние нужно вызвать beacons.activate
Вызвать beacons.decommission что бы навсегда деактивировать beacon ID из нашего проекта. Вы больше не сможете использовать ID с которым он был ранее зарегистрирован. Но вы можете легко назначить маячку новый ID и перерегистрировать маячок с новым ID

Добавление вложений маячкам

После того как маячок был зарегистрирован, он готов к следующему шагу.

К маячкам можно привязывать произвольные данные, называемые вложениями(Attachments). Они представляют из себя блобы, хранимые в Google’s scalable cloud. В настоящее время, вложения доступны только для проекта в котором они были созданы, вы не сможете использовать их в другом проекте.

При создании вложения вам нужно заполнить два поля:

namespacedType — строка состоящая из идентификатора пространства имён, косой черты и типа данных.
Нпирмер: surreptitious-banjo-145/string
data — base64 представление типа данных определенного в поле namespacedType. Например: aGVsbG8gd29ybGQh

Что бы выяснить какие пространства имён имён связанны с вашим проектом можно вызвать namespaces.list.

Вложения могут быть длиной до 1024 байт. Вы можете использовать любой string который имеет значение для вашего приложения, например, ID для автобусной остановки или раположения магазина, структурированные данные, такие как JSON, или ссылка на внешнюю базу данных.

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

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

Пример показывает как присоединить данные (строка **aGVsbG8gd29ybGQh**) к маячку:

HTTP method:
POST
Request URL:
https://proximitybeacon.googleapis.com/v1beta1/beacons/beaconName/attachments
Request body:

{
  "namespacedType":"surreptitious-banjo-145/my-attachment-type",
  "data":"aGVsbG8gd29ybGQh"
}

Response:
Если всё прошло удачно, ответом будет статус код: 200 ОК.

Тело ответа содержит JSON представление вложения, содержащее значение BeaconAttachment.attachment_name, которое может использоваться как ссылка для управления вложениями.

Мониторинг

После того как мы развернули наши маячки, что бы убедиться что они работают должным образом их необходимо мониторить. Кадры Eddystone-TLM позволяют маячкам сообщать свой статус устройствам, которые их обнаруживают, но если маячков много, а площадь на которой они развернуты достаточно велика, то самостоятельный обход маячков со специальным приложением для мониторинга может быть проблемой. Выход из ситуации есть. Мы можем периодически подсовывать пользователю кадры Eddystone-TLM, которые через него будут передаваться нам в Google’s beacon platform. Чередование кадров мониторинга с кадрами, которые непосредственно предназначенными для устройств пользователей (например, Eddystone-UID) происходит через равные интервалы времени установленные при инициализации маячков.

В случае если маячок установлен в месте где он не будет часто использоваться, рекомендуется чаще чередовать Eddystone-TLM кадры с целевыми, что бы максимизировать вероятность получения пользователем такого кадра.

В кадре Eddystone-TLM передаются следующие данные:

Уровень заряда батарейки
Количество переданных кадров
Количество времени с момента активации
Свою температуру

На основе этих данных Google's beacon platform может предоставить следующую информацию:

Прогнозируемое время разряда батарейки
Перемещение маячка (если есть акселерометр)
Необычно низкий уровень обнаружения

Вы можете отслеживать статус маячков с помощью ресурса beacons.diagnostics.

В следующей части...

Я расскажу как добавить возможность взаимодействовать с маячками на клиентской стороне (Android и iOS) c помощью Google Nearby Messages API.

Примеры сервисных приложений для Android и iOS использующих Proximity Beacon API на GitHub