Usa la API de ARCore en Google Cloud

Selecciona la plataforma:

Las funciones de ARCore, como la API de Geospatial y Cloud Anchors, usan la API de ARCore alojada en Google Cloud. Cuando se usan estas funciones, tu aplicación usa credenciales para acceder al servicio de la API de ARCore.

En esta guía de inicio rápido, se describe cómo configurar tu aplicación para que pueda comunicarse con el servicio de la API de ARCore alojado en Google Cloud.

Crea un proyecto de Google Cloud nuevo o usa uno existente

Si ya tienes un proyecto, selecciónalo.

Ir al selector de proyectos

Si no tienes un proyecto de Google Cloud existente, crea uno.

Crear un nuevo proyecto

Habilita la API de ARCore

Para usar la API de ARCore, debes habilitarla en tu proyecto.

Habilita la API de ARCore

Configura un método de autorización

Una aplicación para iOS puede comunicarse con la API de ARCore mediante dos métodos de autorización diferentes: la autorización sin clave, que es el método recomendado, y la autorización de la clave de API:

  • La autorización sin clave usa un token firmado para controlar el acceso a la API. Este método requiere que un servidor de tu propiedad firme los tokens y controle el acceso a la API.
  • Una clave de API es una string que identifica un proyecto de Google Cloud. Por lo general, las claves de API no se consideran seguras, ya que los clientes suelen acceder a ellas. Considera usar la autorización de tokens para comunicarte con la API de ARCore.

Sin llave

ARCore admite la autorización de llamadas a la API en iOS mediante un (token web JSON). El token debe estar firmado por una cuenta de servicio de Google.

Si quieres generar tokens para iOS, debes tener un extremo en tu servidor que cumpla con los siguientes requisitos:

  • Tu propio mecanismo de autorización debe proteger el extremo.

  • El extremo debe generar un token nuevo cada vez, de modo que ocurra lo siguiente:

    • Cada usuario obtiene un token único.
    • Los tokens no vencen de inmediato.

Crea una cuenta de servicio y una clave de firma

Sigue estos pasos para crear una cuenta de servicio de Google y una clave de firma:

  1. En Google Cloud, abre la página Credenciales.
    Credenciales
  2. Haz clic en Crear credenciales > Cuenta de servicio.
  3. En Detalles de la cuenta de servicio, escribe un nombre para la cuenta nueva y, luego, haz clic en Crear.
  4. En la página Permisos de la cuenta de servicio, ve al menú desplegable Selecciona un rol. Selecciona Cuentas de servicio > Creador de tokens de cuentas de servicio y, luego, haz clic en Continuar.
  5. En la página Otorgar a usuarios acceso a esta cuenta de servicio, haz clic en Listo.
  6. En la página Credenciales, busca la sección Cuentas de servicio y haz clic en el nombre de la cuenta que acabas de crear.
  7. En la página Detalles de la cuenta de servicio, desplázate hacia abajo hasta la sección Claves y selecciona Agregar clave > Crear clave nueva.

  8. Selecciona JSON como el tipo de clave y haz clic en Crear.

    Esta acción descarga un archivo JSON que contiene la clave privada en tu máquina. Almacena el archivo de claves JSON descargado en una ubicación segura.

Crea tokens en tu servidor

Para crear tokens nuevos (JWT) en tu servidor, usa las bibliotecas JWT estándar y el archivo JSON que descargaste de manera segura desde tu nueva cuenta de servicio.

Crea tokens en tu máquina de desarrollo

Para generar JWT en tu máquina de desarrollo, usa el siguiente comando oauth2l:

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

Es necesario especificar una ubicación de caché vacía con la marca --cache para garantizar que se produzca un token diferente cada vez. Asegúrate de cortar la cadena resultante. Los espacios adicionales o los caracteres de salto de línea harán que la API rechace el token.

Firma el token

Debes usar el algoritmo RS256 y las siguientes reclamaciones para firmar el JWT:

  • iss: Es la dirección de correo electrónico de la cuenta de servicio.
  • sub: Es la dirección de correo electrónico de la cuenta de servicio.
  • iat: Es el tiempo Unix de la época en la que se generó el token, en segundos.
  • exp: iat + 3600 (1 hora). El tiempo Unix epoch cuando vence el token, en segundos.
  • aud: El público. Se debe configurar en https://arcore.googleapis.com/.

Las reclamaciones no estándar no son obligatorias en la carga útil de JWT, aunque la reclamación uid puede resultarte útil para identificar al usuario correspondiente.

Si usas un enfoque diferente para generar tus JWT, como usar una API de Google en un entorno administrado por Google, asegúrate de firmar tus JWT con las reclamaciones de esta sección. Sobre todo, asegúrate de que el público sea correcto.

Pasa el token en la sesión de ARCore

  1. Crea una sesión con GARSession#sessionWithError:.

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

  2. Cuando obtengas un token, pásalo a la sesión con setAuthToken:. De lo contrario, la sesión usará el token de autorización válido más reciente que hayas pasado. Llama a este método cada vez que actualices tu token:

    [garSession setAuthToken: authToken]

La app ya está configurada para usar la autenticación sin clave.

Ten en cuenta lo siguiente cuando pases un token a la sesión:

  • Si usaste una clave de API para crear la sesión, ARCore ignorará el token y registrará un error.

    Si ya no necesitas la clave de API, bórrala en Google Developers Console y quítala de tu app.

  • ARCore ignora los tokens que contienen espacios o caracteres especiales.

  • Por lo general, los tokens vencen después de una hora. Si existe la posibilidad de que tu token venza mientras está en uso, obtén uno nuevo y pásalo a la API.

Clave de API

  1. En Google Cloud, abre la página Credenciales.
    Credenciales
  2. Haz clic en Crear credenciales y, luego, selecciona Clave de API en el menú.
    En el cuadro de diálogo Se creó la clave de API, se muestra la string de la clave nueva.

  3. Cuando crees un GARSession, usa GARSession#sessionWithAPIKey:bundleIdentifier:error: y, luego, inserta tu clave de API:

    self.garSession = [GARSession sessionWithAPIKey:@"your-api-key"
                               bundleIdentifier:nil
                                          error:&error];
  4. Revisa la documentación sobre las restricciones de la clave de API para protegerla.

Tu app ya está configurada para usar claves de API.

Próximos pasos

Con la autorización configurada, consulta las siguientes funciones de ARCore que la usan: