API de Permissions en Android

Antes de usar cualquiera de las APIs de Home para Android, 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. Con la API de Permissions, el usuario puede, a través de su Cuenta de Google, otorgar a las apps de las APIs de Home acceso a los dispositivos de su casa.

Integra la API de Permissions

Antes de continuar, asegúrate de haber seguido los pasos en Inicializa la casa en Android. 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, así es como la app de ejemplo lo controla:

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 de 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 devuelve un PermissionsState de NOT_GRANTED o PERMISSIONS_STATE_UNAVAILABLE, deberás solicitar permisos. Si la verificación devuelve un PermissionsState de GRANTED, pero una llamada posterior a structures() no devuelve ninguna estructura, significa que el usuario revocó el acceso a la app a través de la página de configuración de Google Home app (GHA), por lo que 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ó los 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, ya 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 se pueden otorgar permisos variarán según si registraste tu app en Google Home Developer Console.

Se requiere el registro de Developer Console para publicar una app con las APIs de Home. No es necesario probar ni usar las APIs de Home.

Si una app no está registrada en Developer Console, estará en estado sin verificar. Se recomienda lo siguiente 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 para 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 sean compatibles con 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 Developer Console y se aprobó su acceso a uno o más tipos de dispositivos, y se completó la verificación de la marca para OAuth, estará en 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 quiere otorgarle 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 solo puede otorgar permiso a los tipos de dispositivos que se aprobaron en Developer Console.
   3. En el caso de los tipos de dispositivos sensibles que la app tiene acceso a administrar, el usuario puede restringir el acceso por dispositivo. Por ejemplo, si un usuario tiene tres cerraduras, puede otorgar acceso a solo una de ellas.

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 o automatizarlo.

Cambiar permisos

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

Para ello, se debe volver 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:

1. A través de la página Mi cuenta 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 haya estado usando en todas las plataformas (teléfonos) y estructuras.

   Se puede dirigir al usuario con un vínculo directo a la subpágina Apps y servicios de terceros con el siguiente esquema de URL:

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

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

Permisos de Ok Google

El comando okGoogle es un comando a nivel del dispositivo 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 estos casos.