Функции ARCore, такие как Geospatial API и Cloud Anchors, используют API ARCore, размещенный в Google Cloud. При использовании этих функций ваше приложение использует учетные данные для доступа к сервису ARCore API.
В этом кратком руководстве описано, как настроить ваше приложение для взаимодействия со службой API ARCore, размещенной в Google Cloud.
Создайте новый проект Google Cloud или используйте существующий проект.
If you have an existing project, select it.
Если у вас нет существующего проекта в Google Cloud, создайте его.
Включите API ARCore
Для использования API ARCore необходимо включить его в вашем проекте.
Set up an authorization method
Приложение 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
При использовании функции подписи приложений в Play Store , Google управляет ключом подписи вашего приложения и использует его для подписи ваших APK-файлов. Этот ключ следует использовать в качестве отпечатка подписи.
- На странице «Подписание приложений» в консоли Google Play прокрутите вниз до раздела «Сертификат ключа подписи приложения» .
- Используйте отпечаток сертификата SHA-1 .
Создание идентификаторов клиентов OAuth 2.0
Для каждого соответствующего ключа подписи, полученного на предыдущих шагах, создайте идентификатор клиента OAuth 2.0 в учетных данных вашего проекта Google Cloud.
В Google Cloud откройте страницу «Учетные данные».
Нажмите «Создать учетные данные» , затем выберите «Идентификатор клиента OAuth» в меню.
Заполните необходимые поля следующим образом:
- Тип приложения : выберите Android .
- Имя пакета : используйте имя пакета, указанное в вашем файле AndroidManifest.xml .
- Отпечаток сертификата SHA-1 : используйте отпечаток, полученный на предыдущих шагах.
Нажмите « Создать» .
Включите необходимые библиотеки
- Добавьте
com.google.android.gms:play-services-auth:16+в зависимости вашего приложения. Если вы используете минификацию кода , добавьте её в файл
build.gradleвашего приложения:buildTypes { release { ... proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } }Добавьте следующее в файл
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 Web Token . Токен должен быть подписан учетной записью сервиса Google.
Для генерации токенов для iOS на вашем сервере должна быть конечная точка, удовлетворяющая следующим требованиям:
Ваш собственный механизм авторизации должен обеспечивать защиту конечной точки.
Каждый раз конечная точка должна генерировать новый токен, при условии, что:
- Каждый пользователь получает уникальный токен.
- Токены не истекают мгновенно.
Создайте учетную запись службы и ключ подписи.
Выполните следующие шаги, чтобы создать учетную запись службы Google и ключ подписи:
- В Google Cloud откройте страницу «Учетные данные».
Реквизиты для входа - Нажмите «Создать учетные данные» > «Учетная запись службы» .
- В разделе «Сведения об учетной записи службы» введите имя для новой учетной записи, затем нажмите «Создать» .
- На странице разрешений служебной учетной записи перейдите к раскрывающемуся списку «Выберите роль» . Выберите «Служебные учетные записи» > «Создатель токенов служебных учетных записей» , затем нажмите «Продолжить».
- На странице доступа пользователей к этой учетной записи сервиса нажмите «Готово».
- На странице «Учетные данные» найдите раздел «Служебные учетные записи» и щелкните имя только что созданной учетной записи.
- На странице сведений об учетной записи службы прокрутите вниз до раздела «Ключи» и выберите «Добавить ключ» > «Создать новый ключ» .
Выберите 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 epoch, в секундах, когда был сгенерирован токен. -
exp—iat+3600(1 час). Время в формате Unix epoch, в секундах, когда истекает срок действия токена. -
aud— Аудитория. Необходимо установить значениеhttps://arcore.googleapis.com/.
Нестандартные утверждения в полезной нагрузке JWT не требуются, хотя утверждение uid может быть полезно для идентификации соответствующего пользователя.
Если вы используете другой подход для генерации JWT, например, API Google в среде, управляемой Google, обязательно подписывайте свои JWT с помощью утверждений, указанных в этом разделе. И самое главное, убедитесь, что целевая аудитория указана правильно.
Передайте токен в сессии ARCore.
- Убедитесь, что для параметра « Стратегия аутентификации iOS» установлено значение AuthenticationToken . В Unity перейдите в меню «Редактировать» > «Настройки проекта» > «Управление плагинами XR» > «Расширения ARCore» . В раскрывающемся меню «Стратегия аутентификации iOS» выберите параметр «Authentication Token» .
Получив токен, передайте его в сессию 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
- В Google Cloud откройте страницу «Учетные данные».
Реквизиты для входа - Нажмите «Создать учетные данные» , затем выберите «Ключ API» в меню.
В диалоговом окне создания ключа API отображается строка, соответствующая вашему вновь созданному ключу. В Unity перейдите в меню «Редактировать» > «Настройки проекта» > «Управление плагинами XR» > «Расширения ARCore» . Для каждой целевой платформы (Android, iOS) в раскрывающемся меню «Стратегия аутентификации» выберите пункт «Ключ API» . Затем вставьте свой ключ API в соответствующие поля.
- Ознакомьтесь с документацией по ограничениям, связанным с ключами API , чтобы обеспечить безопасность своего ключа API.
Ваше приложение теперь настроено на использование ключей API.
Что дальше?
После настройки авторизации ознакомьтесь со следующими функциями ARCore, которые её используют: