Используйте API ARCore в Google Cloud

Выберите платформу:

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

В этом кратком руководстве описывается, как настроить приложение, чтобы оно могло взаимодействовать со службой API ARCore, размещенной в Google Cloud.

Создайте новый проект Google Cloud или используйте существующий проект.

Если у вас есть существующий проект, выберите его.

Перейти к выбору проектов

Если у вас нет существующего проекта Google Cloud, создайте его.

Создать новый проект

Включите API ARCore

Чтобы использовать API ARCore, вы должны включить его в своем проекте.

Включите API ARCore

Настройте метод авторизации

Приложение Unity может взаимодействовать с API ARCore, используя два разных метода авторизации: авторизация без ключа (рекомендуемый метод) и авторизация по ключу API:

  • В Android авторизация без ключа использует комбинацию имени пакета приложения и отпечатка ключа подписи для авторизации вашего приложения.

    В iOS для авторизации без ключа используется токен, подписанный для управления доступом к API. Для этого метода требуется, чтобы принадлежащий вам сервер подписывал токены и управлял доступом к API.

  • Ключ API — это строка, идентифицирующая проект Google Cloud. Ключи API обычно не считаются безопасными, поскольку они обычно доступны клиентам. Рассмотрите возможность использования авторизации без ключа для связи с API ARCore.

Бесключевой доступ

Чтобы авторизовать свое приложение с помощью аутентификации без ключа , создайте идентификаторы клиентов OAuth 2.0.

Определить отпечатки ключей подписи

Идентификатор клиента OAuth 2.0 использует отпечаток ключа подписи вашего приложения для идентификации вашего приложения.

Как получить отпечаток подписи отладки

При запуске или отладке проекта инструменты Android SDK автоматически подписывают ваше приложение с помощью созданного сертификата отладки.

Используйте следующую команду, чтобы получить отпечаток сертификата отладки.

Мак/Линукс
keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore
Окна
keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

Утилита keytool предложит вам ввести пароль для хранилища ключей. Пароль по умолчанию для хранилища ключей отладки — android . Затем утилита keytool печатает отпечаток пальца на терминале. Например:

   Certificate fingerprint: SHA1: <strong>DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Как получить отпечаток пальца подписи из хранилища ключей

Если у вас есть файл хранилища ключей, используйте утилиту keytool для определения отпечатка пальца.

keytool -list -v -alias your-key-name -keystore path-to-production-keystore

Затем утилита keytool печатает отпечаток пальца на терминале. Например:

   Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Как получить ключ подписи вашего приложения от Play App Signing

При использовании подписи приложений Google Google управляет ключом подписи вашего приложения и использует его для подписи ваших APK. Этот ключ следует использовать для подписи отпечатка пальца.

  1. На странице подписи приложений в консоли Google Play прокрутите до пункта Сертификат ключа подписи приложения .
  2. Используйте отпечаток сертификата SHA-1 .

Создайте идентификаторы клиентов OAuth 2.0.

Для каждого применимого ключа подписи из предыдущих шагов создайте идентификатор клиента OAuth 2.0 в учетных данных вашего проекта Google Cloud.

  • В Google Cloud откройте страницу «Учетные данные».

    Реквизиты для входа

  • Нажмите «Создать учетные данные» , затем выберите в меню идентификатор клиента OAuth .

  • Заполните необходимые поля следующим образом:

    • Тип приложения : выберите Android .
    • Имя пакета : используйте имя пакета, объявленное в AndroidManifest.xml .
    • Отпечаток сертификата SHA-1 : используйте отпечаток пальца, полученный на предыдущих шагах.

  • Нажмите Создать .

Включить необходимые библиотеки

  1. Включите com.google.android.gms:play-services-auth:16+ в зависимости вашего приложения.

  2. Если вы используете минификацию кода , добавьте ее в файл build.gradle вашего приложения:

    buildTypes {
  release {
    ...
    proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
  }
}

  3. Добавьте следующее в файл proguard-rules.pro вашего приложения:

    -keep class com.google.android.gms.common.** { *; }
-keep class com.google.android.gms.location.** { *; }
-keep class com.google.android.gms.auth.** { *; }
-keep class com.google.android.gms.tasks.** { *; }

Теперь ваше приложение настроено на использование аутентификации без ключа.

Бесключевой доступ

ARCore поддерживает авторизацию вызовов API в iOS с помощью ( веб-токена JSON ). Токен должен быть подписан учетной записью службы Google.

Чтобы генерировать токены для iOS, на вашем сервере должна быть конечная точка, удовлетворяющая следующим требованиям:

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

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

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

Создайте сервисную учетную запись и ключ подписи.

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

  1. В Google Cloud откройте страницу «Учетные данные».
    Реквизиты для входа
  2. Нажмите Создать учетные данные > Учетная запись службы .
  3. В разделе «Сведения об учетной записи службы » введите имя новой учетной записи, затем нажмите «Создать» .
  4. На странице «Разрешения учетной записи службы» перейдите в раскрывающийся список «Выберите роль» . Выберите «Учетные записи служб» > «Создание токенов учетных записей служб» , затем нажмите «Продолжить».
  5. На странице Предоставить пользователям доступ к этой учетной записи службы нажмите Готово.
  6. На странице «Учетные данные» найдите раздел «Учетные записи служб» и щелкните имя только что созданной учетной записи.
  7. На странице сведений об учетной записи службы прокрутите вниз до раздела «Ключи» и выберите «Добавить ключ» > «Создать новый ключ» .

  8. Выберите JSON в качестве типа ключа и нажмите «Создать» .

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

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

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

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

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

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

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

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

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

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

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

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

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

  1. Убедитесь, что для стратегии аутентификации iOS установлено значение AuthenticationToken . В Unity выберите «Правка» > «Настройки проекта» > «Управление плагинами XR» > «Расширения ARCore ». В раскрывающемся меню «Стратегия аутентификации iOS» выберите параметр «Токен аутентификации» .

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

    // Designate the token to authorize ARCore API calls
// on the iOS platform. This should be called each time the application's token is refreshed.
ARAnchorManager.SetAuthToken(authToken);

Теперь ваше приложение настроено на использование аутентификации без ключа.

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

  • Если вы использовали ключ API для создания сеанса, ARCore проигнорирует токен и зарегистрирует ошибку.

    Если вам больше не нужен ключ API, удалите его в консоли разработчиков Google и из своего приложения.

  • ARCore игнорирует токены, содержащие пробелы или специальные символы.

  • Срок действия токенов обычно истекает через один час. Если существует вероятность того, что срок действия вашего токена истечет во время использования, получите новый токен и передайте его API.

API-ключ

  1. В Google Cloud откройте страницу «Учетные данные».
    Реквизиты для входа
  2. Нажмите «Создать учетные данные» , затем выберите «Ключ API» в меню.
    В диалоговом окне создания ключа API отображается строка для вашего вновь созданного ключа.

  3. В Unity выберите «Правка» > «Настройки проекта» > «Управление плагинами XR» > «Расширения ARCore ». Для каждой целевой платформы (Android, iOS) в раскрывающемся меню «Стратегия аутентификации» выберите параметр «Ключ API» . Затем вставьте свой ключ API в поля ключа API.

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

Теперь ваше приложение настроено на использование ключей API.

Что дальше

После настройки авторизации проверьте следующие функции ARCore, которые ее используют: