Используйте 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

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

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

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

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

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

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

Ваш собственный механизм авторизации должен защищать конечную точку.
Конечная точка должна каждый раз генерировать новый токен, например:
- Каждый пользователь получает уникальный токен.
- Срок действия токенов не истекает сразу.

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

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

В Google Cloud откройте страницу «Учетные данные».
Реквизиты для входа
Нажмите Создать учетные данные > Учетная запись службы .
В разделе «Сведения об учетной записи службы» введите имя новой учетной записи, затем нажмите «Создать» .
На странице «Разрешения учетной записи службы» перейдите в раскрывающийся список «Выберите роль» . Выберите «Учетные записи служб» > «Создание токенов учетных записей служб» , затем нажмите «Продолжить».
На странице Предоставить пользователям доступ к этой учетной записи службы нажмите Готово.
На странице «Учетные данные» найдите раздел «Учетные записи служб» и щелкните имя только что созданной учетной записи.
На странице сведений об учетной записи службы прокрутите вниз до раздела «Ключи» и выберите «Добавить ключ» > «Создать новый ключ» .
Выберите 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

Создайте сеанс, используя GARSession#sessionWithError: .

NSError *error = nil;
GARSession *garSession = [GARSession sessionWithError:&error];

Когда вы получите токен, передайте его в сеанс, используя setAuthToken: . В противном случае сеанс будет использовать самый последний действительный токен авторизации, который вы передали. Вызывайте этот метод каждый раз, когда вы обновляете свой токен:
```
[garSession setAuthToken: authToken]
```

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

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

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

API-ключ

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

При создании GARSession используйте GARSession#sessionWithAPIKey:bundleIdentifier:error: и вставьте свой ключ API:

self.garSession = [GARSession sessionWithAPIKey:@"your-api-key"
                               bundleIdentifier:nil
                                          error:&error];

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

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

Что дальше

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