Configura tu app para la API de Ambient

Para comenzar a usar la API de Ambient, habilita la API en la Consola de API de Google y configura un ID de cliente de OAuth 2.0. La API de Ambient usa OAuth 2.0 para aplicaciones de TV y dispositivos de entrada limitada.

Tu aplicación interactúa con la API de Ambient en nombre de un usuario de la API de Ambient. El usuario autoriza estas solicitudes a la API con el protocolo OAuth 2.0.

El ID de cliente de OAuth 2.0 permite que los usuarios de tu aplicación accedan, se autentiquen y, por lo tanto, usen la API de Ambient. La API de Ambient no admite cuentas de servicio. Para usar estas APIs, los usuarios deben haber accedido a una Cuenta de Google válida.

Cómo configurar tu app

Primero, habilita la API y, luego, solicita un ID de cliente de OAuth 2.0.

Habilita la API

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

Ve a la Consola de API de Google.
En la barra de menú, selecciona un proyecto o crea uno nuevo.
Para abrir una de las APIs de Google Fotos, en el menú de navegación, selecciona APIs y servicios > Biblioteca.
Busca "API de Ambient". Selecciona la API de Ambient y haz clic en Habilitar.

Solicita un ID de cliente de OAuth 2.0

Sigue estos pasos para solicitar un ID de cliente de OAuth y configurarlo para tu aplicación. La API de Ambient usa OAuth 2.0 para aplicaciones de dispositivos de TV y de entrada limitada.

Ve a la Consola de API de Google y selecciona tu proyecto.
En el menú, selecciona APIs y servicios > Credenciales.
En la página Credenciales, haz clic en Crear credenciales > ID de cliente de OAuth.

Nota: Si estás configurando un proyecto nuevo, es posible que se te solicite configurar la pantalla de consentimiento de tu proyecto.
Selecciona el Tipo de aplicación. En este ejemplo, el tipo de aplicación es TVs y dispositivos de entrada limitada.
Proporciona un nombre para tu cliente de OAuth 2.0 y haz clic en Crear.
En el diálogo del cliente de OAuth resultante, copia lo siguiente:
- ID de cliente
- Secreto del cliente

Tu app puede acceder a las APIs de Google habilitadas con estos valores.

Para que puedas lanzar una aplicación pública que acceda a la API de Ambient, Google debe revisarla. Cuando pruebes la app, aparecerá un mensaje que indica que no está verificada en la pantalla hasta que se verifique.

Después de configurar tu app, estará todo listo para comenzar. Puedes explorar los siguientes recursos o leer sobre el flujo de autenticación optimizado de la API de Ambient.

Cómo cambiar tu ID de cliente

Solo se puede acceder a los recursos creados a través de cualquiera de las APIs de Google Fotos o modificarlos con el ID de cliente original que se usó para crearlos. Por ejemplo, si creas un session en la API de Picker con un ID de cliente específico y, luego, cambias ese ID de cliente en tu app, esta perderá el acceso a cualquier recurso de la API creado con el ID de cliente anterior.

Planifica cuidadosamente y elige el tipo de ID de cliente correcto para la API de Fotos que estás usando. Solo cambia tu ID de cliente si es absolutamente necesario para evitar problemas de acceso.

Flujo de autenticación optimizado para la API de Ambient

El flujo de autenticación estándar de la API de Ambient requiere que los usuarios escaneen 2 códigos QR:

Primero, acceder a su Cuenta de Google (si aún no lo hizo).
Un segundo que vincula al dispositivo ambiente recién creado en su cuenta de Google Fotos, en el que puede seleccionar los elementos multimedia que se mostrarán.

El flujo optimizado te permite proporcionar un solo código QR a tus usuarios pasando el parámetro state adicional con tu llamada de autenticación inicial.

Cuando solicites códigos de dispositivo y de usuario como parte de OAuth para dispositivos de entrada limitados, incluye el parámetro state adicional con tu solicitud. Agrega lo siguiente al parámetro state:

Parámetros

Parámetros
`requestId`	`string` Es obligatorio. Es un identificador único proporcionado por el cliente para esta solicitud. Se usa para mitigar la duplicación de recursos en caso de una falla de red. Este ID debe tener el formato de una cadena de UUID (versión 4) y cumplir con los siguientes requisitos: No debe contener información de identificación sensible sobre el usuario. Debe contener 32 caracteres hexadecimales divididos en cinco grupos separados por guiones, en el formato “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” (o 8-4-4-4-12).
`displayName`	`string` Opcional. Es un nombre visible definido por el usuario para este dispositivo. Los usuarios podrán verlo en la configuración de la app de Google Fotos, pero solo podrán editarlo a través de esta API. Los nombres visibles válidos deben tener entre 1 y 100 caracteres (inclusive).

requestId

string

Es obligatorio. Es un identificador único proporcionado por el cliente para esta solicitud. Se usa para mitigar la duplicación de recursos en caso de una falla de red.

Este ID debe tener el formato de una cadena de UUID (versión 4) y cumplir con los siguientes requisitos:

No debe contener información de identificación sensible sobre el usuario.
Debe contener 32 caracteres hexadecimales divididos en cinco grupos separados por guiones, en el formato “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” (o 8-4-4-4-12).

displayName

string

Opcional. Es un nombre visible definido por el usuario para este dispositivo.

Los usuarios podrán verlo en la configuración de la app de Google Fotos, pero solo podrán editarlo a través de esta API.

Los nombres visibles válidos deben tener entre 1 y 100 caracteres (inclusive).

Por ejemplo, observa el siguiente bloque de código:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

Una respuesta correcta incluirá un user_code y un verification_url, que le mostrarás al usuario (lo más probable es que sea como un código QR) para que pueda navegar allí en un dispositivo diferente. Si incluyes el parámetro state, cuando llames más adelante a createDevice con la API de Ambient, puedes omitir la presentación de settingsUri en un segundo código QR, ya que el último paso del flujo de OAuth redireccionará automáticamente a esta ubicación.

Para obtener detalles completos, incluimos una explicación más detallada. También puedes revisar el código en nuestra app de ejemplo para ver un ejemplo del uso del parámetro state como parte de OAuth para dispositivos de entrada limitados con la API de Ambient.

Detalles sobre el flujo de autenticación optimizado

Para comprender por completo el flujo de OAuth optimizado para la API de Ambient, es útil comprender el flujo de OAuth 2.0 para aplicaciones de TV y dispositivos de entrada limitada, así como el flujo estándar de la API de Ambient. Estos son los pasos para cada flujo.

OAuth 2.0 para aplicaciones de dispositivos de TV y de entrada limitada:

Tu aplicación envía una solicitud al servidor de autorización de Google que identifica los permisos a los que tu aplicación solicitará acceso.
El servidor responde con varios datos que se usan en pasos posteriores, como un código de dispositivo y un código de usuario.
Muestras información que el usuario puede ingresar en un dispositivo independiente para autorizar tu app.
Tu aplicación comienza a sondear el servidor de autorización de Google para determinar si el usuario autorizó tu app.
El usuario cambia a un dispositivo con capacidades de entrada más ricas, inicia un navegador web, navega a la URL que se muestra en el paso 3 y, luego, ingresa un código que también se muestra en el paso 3. Luego, el usuario puede otorgar (o denegar) el acceso a tu aplicación.
La siguiente respuesta a tu solicitud de sondeo contiene los tokens que necesita tu app para autorizar solicitudes en nombre del usuario. (Si el usuario rechazó el acceso a tu aplicación, la respuesta no contiene tokens).

Flujo de la API de Ambient:

Busca un token de OAuth existente y actualízalo o solicita uno nuevo.
Después de obtener un token de OAuth, crea un dispositivo nuevo.
Muestra el settingsUri al usuario y comienza a sondear el dispositivo hasta que mediaSourcesSet muestre el valor verdadero.
El usuario navega a settingsUri y selecciona las fotos que quiere compartir con tu aplicación.
Una vez que mediaSourcesSet muestre un valor verdadero, recupera la lista de mediaItems.
Ahora puedes comenzar la presentación de diapositivas o cualquier otra experiencia ambiente.

Ambos flujos incluyen un paso en el que le muestras una URL al usuario, y este navega allí en su dispositivo de entrada más rico. Si incluyes el parámetro state en tu llamada inicial de OAuth, puedes evitar la segunda URL que debes mostrar.

Esto funciona porque el último paso del flujo de OAuth 2.0 para TV y aplicaciones de dispositivos con entrada limitada suele redireccionar al usuario a una página que dice "Ahora puedes volver a tu dispositivo". Si incluyes el parámetro de estado, el último paso del flujo ahora intentará redireccionarte a settingsUri. Tu app seguirá recibiendo un token de OAuth. Debes usar este token para llamar a createDevice con el mismo requestId. Una vez que se haya creado un dispositivo con el mismo ID, el flujo de OAuth inicial redireccionará correctamente al usuario a la página correcta en el dispositivo enriquecido dentro de la app de Fotos.

Recuerda los siguientes puntos:

De todas formas, es una buena idea mostrar el settingsUri en caso de que haya algún problema con la autenticación.
Puedes usar settingsUri en otros casos, por ejemplo, cuando un usuario quiere actualizar su selección de fotos.