API de Permissions

Antes de usar cualquiera de las APIs de Home, la app debe tener permiso para acceder a los dispositivos de la casa del usuario, a los que se hace referencia en la API como la estructura.

Las APIs de Home usan OAuth 2.0 para otorgar acceso a los dispositivos de la estructura. OAuth permite que un usuario otorgue permiso a una app o un servicio sin tener que exponer sus credenciales de acceso. Con la API de Permissions, el usuario puede usar su Cuenta de Google para otorgar a las apps de las APIs de Home acceso a los dispositivos de su casa.

El uso de la API de Permissions implica varios pasos en tu app, Google Cloud y Google Home Developer Console:

1. Configura OAuth en Google Cloud
   1. Firma la app
   2. Configura la pantalla de consentimiento de OAuth
   3. Registra la app y crea credenciales
2. Cómo integrar la API de Permissions
   1. Verifica si tu app tiene permisos
   2. Solicita permisos
3. Otorga permisos
   1. Cambiar permisos
   2. Cómo revocar permisos

Configura OAuth en Google Cloud

Si ya tienes un cliente de OAuth verificado, puedes usarlo sin configurar uno nuevo. Para obtener más información, consulta Si tienes un cliente de OAuth existente.

Firma la app

1. Ejecuta la app en Android Studio para generar una clave de OAuth. Cuando ejecutas o depuras una app en Android Studio, se genera automáticamente una clave de OAuth destinada al desarrollo y la depuración. Consulta Android Studio: Firma tu compilación de depuración para obtener una explicación completa.

   Conecta tu dispositivo móvil a tu máquina local. Android Studio mostrará una lista de tus dispositivos conectados por número de modelo. Selecciona tu dispositivo de la lista y, luego, haz clic en Run project. Esto compila e instala la app de ejemplo en tu dispositivo móvil.

   Para obtener instrucciones más detalladas, consulta Cómo ejecutar apps en un dispositivo de hardware en el sitio para desarrolladores de Android.

   Ahora, detén la app en ejecución.

2. Para obtener la huella digital SHA-1 del certificado de OAuth, sigue las instrucciones detalladas en Configuración de OAuth 2.0 / Aplicaciones nativas / Android en el sitio de ayuda de la consola de Google Cloud.

Configura la pantalla de consentimiento de OAuth

1. En la consola de Google Cloud, ve al panel del selector de proyectos y selecciona el proyecto que deseas usar para crear credenciales de OAuth.
2. Ve a la página APIs y servicios y haz clic en Credenciales en el menú de navegación.

3. Si aún no configuraste la pantalla de consentimiento para este proyecto de Google Cloud, aparecerá el botón Configurar pantalla de consentimiento. En ese caso, configura la pantalla de consentimiento con el siguiente procedimiento. De lo contrario, continúa con la siguiente sección.

   1. Haz clic en Configurar pantalla de consentimiento. Se mostrará la página Pantalla de consentimiento de OAuth.
   2. Según tu caso de uso, selecciona Interno o Externo y, luego, haz clic en Crear. Se muestra el panel Pantalla de consentimiento de OAuth.
   3. Ingresa la información en la página de información de la app según las instrucciones en pantalla y, luego, haz clic en Guardar y continuar. Aparecerá el panel Scopes.
   4. No es necesario agregar ningún permiso, así que haz clic en Guardar y continuar. Se mostrará el panel Usuarios de prueba.
   5. Si quieres agregar usuarios para probar el acceso a tu app, haz clic en Agregar usuarios. Aparecerá el panel Agregar usuarios. Los usuarios de prueba tienen el privilegio de otorgar permisos en tu app.
   6. En el campo vacío, agrega una o más direcciones de correo electrónico de la Cuenta de Google y, luego, haz clic en Agregar.
   7. Haga clic en Guardar y continuar. Aparecerá el panel Resumen.
   8. Revisa la información de la pantalla de consentimiento de OAuth y, luego, haz clic en Volver al panel.

Consulta Configura tu pantalla de consentimiento de OAuth en el sitio de ayuda de la consola de Google Cloud para obtener todos los detalles.

Registra la app y crea credenciales

Para registrar la app para OAuth 2.0 y crear credenciales de OAuth, sigue las instrucciones que se proporcionan en Configura OAuth 2.0. Deberás indicar el tipo de app, que es app nativa/para Android.

Agrega la huella digital SHA-1 que obtuviste de la firma de la app al cliente de OAuth que configuraste en la consola de Google Cloud. Para ello, sigue las instrucciones que se indican en Configura aplicaciones nativas o de OAuth 2.0 en el sitio de ayuda de la consola de Google Cloud.

Con el dispositivo móvil conectado a la máquina local, selecciónalo en la lista y, luego, haz clic en Run project para ejecutarlo. Para obtener instrucciones más detalladas, consulta Cómo ejecutar apps en un dispositivo de hardware en el sitio para desarrolladores de Android.

Integra la API de Permissions

Los usuarios deben otorgar permisos a tu app para acceder a los dispositivos dentro de una estructura determinada. Para comenzar, asegúrate de haber inicializado las APIs de Home. La instancia de homeManager de ese paso se usa en todos los ejemplos de permisos que se muestran aquí.

Primero, registra un ActivityResultCaller con el SDK. Por ejemplo, la app de ejemplo lo controla de la siguiente manera:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

Verifica si tu app tiene permisos

Antes de solicitar permisos, te recomendamos que verifiques si el usuario de la app ya otorgó su consentimiento. Para ello, llama al método hasPermissions() de la instancia de Home para obtener un Flow de valores PermissionsState:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

Si la verificación muestra un PermissionsState de NOT_GRANTED o PERMISSIONS_STATE_UNAVAILABLE, deberás solicitar permisos. Si la verificación muestra un PermissionsState de GRANTED, pero una llamada posterior a structures() no muestra estructuras, el usuario revocó el acceso a la app a través de la página de configuración de Google Home app (GHA) y debes solicitar permisos. De lo contrario, el usuario ya debería tener acceso.

Solicita permisos

Se debe otorgar permiso a tu app para acceder a las estructuras y los dispositivos dentro de una estructura determinada.

Si el usuario aún no otorgó permisos, usa el método requestPermissions() de la instancia de Home para iniciar la IU de permisos y procesar el resultado:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

Para que la IU de permisos se inicie correctamente, debes haber configurado OAuth para tu app.

Otorgar permisos

Ahora deberías poder ejecutar tu app y hacer que un usuario otorgue permisos. El tipo de usuarios que pueden otorgar permisos y los tipos de dispositivos para los que están disponibles los permisos diferirán según si registraste tu app en Developer Console.

El registro de Developer Console es obligatorio para publicar una app con las APIs de Home. No es necesario para probar y usar las APIs de Home. Para obtener acceso a la función de registro de la consola, comunícate con tu Technical Account Manager (TAM) de Google.

Si una app no está registrada en Developer Console, estará en un estado no verificado. Se recomienda para probar el uso de las APIs de Home:

• Solo los usuarios registrados como usuarios de prueba en la consola de OAuth pueden otorgar permisos a la app. Hay un límite de 100 usuarios de prueba para una app no verificada.

• Una app no verificada tendrá acceso a dispositivos de cualquier tipo que admita OAuth para las APIs de Home (la lista de tipos de dispositivos en Developer Console). Se otorgará acceso a todos los dispositivos de una estructura.

Si una app está registrada en el Developer Console y se aprobó el acceso a uno o más tipos de dispositivos, y se completó la verificación de la marca para OAuth, estará en el estado verificada. Este estado es obligatorio para lanzar una app a producción:

• Ya no se aplican los límites de usuarios de prueba. Cualquier usuario puede otorgar permiso a la app.
• El usuario solo puede otorgar permiso a los tipos de dispositivos que se aprobaron en Developer Console.

Ahora que OAuth está configurado, la llamada de la app a requestPermissions() activa los siguientes diálogos:

1. Se le solicita al usuario que seleccione la Cuenta de Google que desea usar.
2. Se le solicita al usuario que seleccione la estructura a la que desea otorgar acceso a la app.
   1. En el caso de una app no verificada, todos los tipos de dispositivos compatibles con las APIs de Home están disponibles para la app.
   2. En el caso de una app verificada, el usuario puede otorgar permiso solo a los tipos de dispositivos que se aprobaron en Developer Console.
   3. En el caso de los tipos de dispositivos sensibles a los que la app tiene acceso para administrar, el usuario puede restringir el acceso por dispositivo. Por ejemplo, si un usuario tiene tres candados, puede otorgar acceso a solo uno de ellos.

Una vez que se otorga el permiso, la app puede usar las APIs de Home para leer el estado de los dispositivos de la estructura y controlarlos. Si el usuario no otorga permiso a la app para un tipo de dispositivo en particular o un dispositivo sensible, la app no podrá usar las APIs de Home para acceder a él, controlarlo ni automatizarlo.

Cambiar permisos

Para otorgar permiso de acceso a dispositivos en una estructura diferente, se puede iniciar el selector de cuenta para permitir que el usuario elija la Cuenta de Google y la estructura a la que cambiar. Durante este proceso, se le volverá a mostrar al usuario la pantalla de consentimiento, incluso si ya se otorgó el consentimiento anteriormente.

Para ello, vuelve a llamar a requestPermissions() con la marca forceLaunch establecida en true:

homeManager.requestPermissions(forceLaunch=true)

Cómo revocar permisos

Los usuarios pueden revocar el acceso otorgado anteriormente de las siguientes maneras:

1. En la página MyAccounts de Google > Datos y privacidad > Apps y servicios de terceros. Esto revocará el token de OAuth que se emitió cuando se otorgó el consentimiento inicial y revocará el acceso a cualquier instancia de la app que el usuario estaba usando en todas las plataformas (teléfonos) y estructuras.

2. A través de la página GHA > Configuración > Apps conectadas. Si haces clic en settings en GHA, se te dirigirá a la página Configuración. Allí, haz clic en la tarjeta Apps vinculadas, que te llevará a una página similar a la pantalla de consentimiento. Desde esta página, el usuario puede quitar el acceso a la app. También puede usar esta misma página para cambiar a qué tipos de dispositivos o dispositivos sensibles específicos puede acceder la app.

3. A través de la página Apps vinculadas directamente en la Web.

Si tienes un cliente de OAuth existente

Si ya tienes un cliente de OAuth verificado para una app publicada, puedes usar tu cliente de OAuth existente para probar las APIs de Home.

No es necesario registrar Developer Console para probar y usar las APIs de Home. Sin embargo, aún necesitarás un registro de Developer Console aprobado para publicar tu app, incluso si tienes un cliente de OAuth verificado de otra integración.

Se aplican las siguientes consideraciones:

• Hay un límite de 100 usuarios cuando se usa un cliente de OAuth existente. Para obtener información sobre cómo agregar usuarios de prueba, consulta Configura la pantalla de consentimiento de OAuth. Independientemente de la verificación de OAuth, existe un límite de 100 usuarios que pueden otorgar permisos a tu aplicación impuesto por las APIs de Home. Esta limitación se quita cuando se completa el registro de Developer Console.

• ElDeveloper Consoleregistro debe enviarse para su aprobación cuando tengas todo listo para restringir las concesiones de tipo de dispositivo a través de OAuth en preparación para actualizar tu app con las APIs de Home.

En el caso de las apps de Google Cloud que aún tienen pendiente la verificación de OAuth, los usuarios no pueden completar el flujo de OAuth hasta que se complete la verificación. Los intentos de otorgar permisos fallarán con el siguiente error:

Access blocked: <Project Name> has not completed the Google verification process.

Permisos de OkGoogle

El comando okGoogle es un comando a nivel de la estructura y se puede usar para automatizar cualquier dispositivo de la estructura. Sin embargo, es posible que una app de las APIs de Home no tenga acceso a todos los dispositivos. En la siguiente tabla, se describe cómo se aplican los permisos en esos casos.