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

Выберите платформу: Android Unity (AR Foundation) iOS

Функции 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.

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

Чтобы авторизовать свое приложение с помощью аутентификации без ключа , создайте идентификаторы клиентов 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 в безопасном месте.

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

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

Чтобы создать новые токены (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.

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

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

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

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

Что дальше

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

• Геопространственный API
• API облачной привязки