Руководство разработчика Cloud Anchors для Unity для iOS

Узнайте, как использовать Cloud Anchors в своих приложениях.

Предпосылки

Прежде чем продолжить, убедитесь, что вы понимаете основные концепции AR и как настроить сеанс ARCore .

Если вы новичок в Cloud Anchors, убедитесь, что вы понимаете, как работают привязки и Cloud Anchors .

Включите Cloud Anchors в своем приложении

Облачные привязки по умолчанию отключены в ARCore. Образец приложения поставляется с включенными Cloud Anchors только для демонстрационных целей. Прежде чем использовать Cloud Anchors в своем приложении, вы должны сначала включить ARCore API в новом или существующем проекте Google Cloud Platform. Эта служба отвечает за размещение, хранение и разрешение облачных привязок.

Вам также потребуется включить возможности Cloud Anchor в конфигурации сеанса AR вашего приложения, чтобы оно могло взаимодействовать с API ARCore:

  1. Включите возможности Cloud Anchor в конфигурации сеанса AR.
  2. Возобновите сеанс дополненной реальности.

Аутентифицируйте свое приложение с помощью ARCore API

Вы должны аутентифицировать API ARCore в своем приложении, чтобы оно могло размещать и разрешать облачные привязки. Приложения, которые размещают и разрешают Cloud Anchors со сроком жизни более 1 дня, должны использовать аутентификацию с помощью токена (подписанного JWT) .

Токен (подписанный JWT) аутентификация

Параметр токена аутентификации может содержать Cloud Anchor до 365 дней. Облачные привязки со сроком жизни более одного дня должны использовать этот метод. Чтобы сгенерировать токены для iOS, на вашем сервере должна быть конечная точка, удовлетворяющая следующим требованиям:

  • Ваш собственный механизм аутентификации должен защищать конечную точку.

  • Конечная точка должна каждый раз генерировать новый токен, чтобы:

    • Каждый пользователь получает уникальный токен.
    • Срок действия токенов не истекает сразу.

В настоящее время единственным поддерживаемым типом токена является подписанный JWT (то есть веб-токен JSON, подписанный учетной записью службы Google). См . официальный веб-сайт JWT для ознакомления с JWT.

Создайте учетную запись службы и ключ подписи

Выполните следующие действия, чтобы создать учетную запись службы Google и ключ подписи:

  1. В меню навигации консоли Google Cloud Platform выберите API и службы > Учетные данные .

  2. Выберите нужный проект, затем нажмите « Создать учетные данные » > « Учетная запись службы» .

  3. В разделе « Сведения об учетной записи службы » введите имя новой учетной записи, затем нажмите « Создать » .

  4. На странице Разрешения учетной записи службы перейдите к раскрывающемуся списку Выберите роль . Выберите «Учетные записи служб» > «Создание токена учетной записи службы» , затем нажмите «Продолжить ».

  5. На странице Предоставить пользователям доступ к этой учетной записи службы нажмите Готово . Вы вернетесь к API и сервисам > Учетные данные .

  6. На странице « Учетные данные » прокрутите вниз до раздела « Учетные записи служб » и щелкните имя только что созданной учетной записи.

  7. На странице сведений об учетной записи службы прокрутите вниз до раздела « Ключи » и выберите « Добавить ключ » > « Создать новый ключ ».

  8. Выберите JSON в качестве типа ключа и нажмите « Создать ». Это загружает файл JSON, содержащий закрытый ключ, на ваш компьютер. Сохраните загруженный файл ключа JSON в безопасном месте.

Создайте токены на своем сервере

Чтобы создать новые токены (JWT) на своем сервере, используйте стандартные библиотеки JWT и файл JSON, которые вы безопасно загрузили из своей новой учетной записи службы.

Создавайте токены на своем компьютере для разработки

Чтобы сгенерировать JWT на вашем компьютере для разработки, используйте следующую команду oauth2l :

oauth2l fetch --jwt --json $KEYFILE $AUDIENCE --cache ""

Указание пустого местоположения кэша с использованием флага --cache необходимо для обеспечения того, чтобы каждый раз создавался другой токен. Обязательно обрежьте результирующую строку, потому что лишние пробелы или символы новой строки заставят ARCore отклонить токен.

Подпишите токен

Для подписи JWT необходимо использовать алгоритм RS256 и следующие утверждения:

  • iss — адрес электронной почты сервисного аккаунта.
  • sub — адрес электронной почты сервисного аккаунта.
  • iat — время Unix, когда был сгенерирован токен, в секундах.
  • exp — iat + 3600 (1 час). Время Unix, когда истечет срок действия маркера, в секундах.
  • aud — аудитория. Должен быть установлен https://arcore.googleapis.com .

Нестандартные утверждения не требуются в полезной нагрузке JWT, хотя утверждение uid может оказаться полезным для идентификации соответствующего пользователя.

Если вы используете другой подход для создания своих JWT, например, используя Google API в среде, управляемой Google, обязательно подпишите свои JWT утверждениями в этом разделе. Прежде всего, убедитесь, что аудитория правильная.

Передайте токен в сеанс ARCore

Когда вы получите токен, передайте его в сеанс ARCore с помощью XPSession.SetAuthToken() :

// Set the token to use when authenticating with the ARCore Cloud Anchor service
// on the iOS platform.
// This should be called each time the application's token is refreshed.
XPSession.SetAuthToken(string authToken);

Обратите внимание на следующее при передаче токена в сеанс:

  • Если вы не передадите действительный токен перед попыткой размещения или разрешения привязки, вы получите ошибки аутентификации.
  • ARCore игнорирует токены, содержащие пробелы или специальные символы. ARCore также игнорирует все токены, если вы создаете сеанс с действительным ключом API. Если вы ранее использовали ключ API и он вам больше не нужен, мы рекомендуем удалить его в Google Developers Console и удалить из своего приложения после переноса пользователей на новейшую версию.
  • Токены обычно истекают через час. Если существует вероятность того, что срок действия вашего токена может истечь во время использования, получите новый токен и передайте его в API.

Аутентификация по ключу API

Используйте аутентификацию по ключу API для размещения и разрешения Cloud Anchors с TTL до 24 часов ( 1 день).

  • В Unity перейдите в Edit > Project Settings > ARCore Project Settings .
  • Добавьте свой ключ API в поле Ключи API Cloud Anchor .

Проверьте качество отображения характерных точек

FeatureMapQuality указывает качество характерных точек, видимых ARCore за несколько предшествующих секунд из данной позы камеры. Облачные привязки, размещенные с использованием функций более высокого качества, обычно разрешаются точнее.

Ценность Описание
Insufficient Качество характерных точек, идентифицированных по позе за несколько предыдущих секунд, низкое. Это состояние указывает на то, что ARCore, скорее всего, столкнется с большими трудностями при разрешении облачной привязки. Поощряйте пользователя перемещать устройство так, чтобы желаемое положение Cloud Anchor, которое он хочет разместить, можно было просматривать под разными углами.
Sufficient Качество характерных точек, идентифицированных по позе за несколько предыдущих секунд, вероятно, достаточно для ARCore, чтобы успешно разрешить облачную привязку, хотя точность полученной позы, вероятно, будет снижена. Поощряйте пользователя перемещать устройство так, чтобы желаемое положение Cloud Anchor, которое он хочет разместить, можно было просматривать под разными углами.
Good Качество характерных точек, идентифицированных по позе за несколько предыдущих секунд, вероятно, достаточно для того, чтобы ARCore успешно разрешил облачную привязку с высокой степенью точности.

Квоты API для запросов хоста и разрешения

API ARCore имеет следующие квоты на пропускную способность запроса:

Тип квоты Максимум Продолжительность Относится к
Количество анкеров неограниченный Н/Д проект
Якорные запросы хоста 30 минута IP-адрес и проект
Якорные запросы разрешения 300 минута IP-адрес и проект

Лучшие практики для хорошего пользовательского опыта

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

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

  • Держите камеру направленной на центр интереса и перемещайте устройство, чтобы отобразить окружающую среду под разными углами, сохраняя примерно одно и то же физическое расстояние. Делайте это до 30 секунд. Это поможет захватить больше визуальных данных и сделать разрешение более надежным.

  • При размещении и разрешении Cloud Anchors убедитесь, что в реальной среде достаточно освещения.

Политика устаревания

  • На приложения, созданные с помощью ARCore SDK 1.12.0 или более поздней версии , распространяется политика прекращения поддержки API Cloud Anchor .
  • Приложения, созданные с помощью ARCore SDK 1.11.0 или более ранней версии, не могут размещать или разрешать облачные привязки из-за того, что SDK использует более старый, устаревший API ARCore.

Что дальше