EnvironmentClient

interface EnvironmentClient

Cliente para acceder a las APIs relacionadas con el entorno.

Usa EnvironmentClientFactory para crear una instancia.

Resumen

Funciones públicas
suspend Environment

Devuelve el objeto Environment.
ListenableFuture<Environment>

Devuelve el objeto Environment.
suspend PrepareEnvironmentResponse
prepareEnvironment(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
)

Prepara el dispositivo asegurándose de que la app de Android Device Policy esté instalada y lista.
ListenableFuture<PrepareEnvironmentResponse>
prepareEnvironmentAsync(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
)

Prepara el dispositivo asegurándose de que la app de Android Device Policy esté instalada y lista.

Funciones públicas

getEnvironment

suspend fun getEnvironment(request: GetEnvironmentRequest): Environment

Devuelve el objeto Environment. Ayuda a la persona que llama a saber si el entorno está listo o no.

Arroja
com.google.android.managementapi.common.exceptions.InvalidArgumentException

Si los roles solicitados no son válidos
com.google.android.managementapi.common.exceptions.InternalException

Si la llamada falló debido a un error interno.
com.google.android.managementapi.common.exceptions.ApiLevelException

Si el nivel de API del SDK del dispositivo no es suficiente para ciertos roles solicitados (esto puede ser adicional a un requisito general de nivel de API mínimo para la llamada en sí) {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} requiere el nivel de API 23 o superior. Cualquier otro rol requiere el nivel de API 28 o superior.

getEnvironmentAsync

fun getEnvironmentAsync(request: GetEnvironmentRequest): ListenableFuture<Environment>

Devuelve el objeto Environment. Ayuda a la persona que llama a saber si el entorno está listo o no.

Muestra
ListenableFuture<Environment>

Un ListenableFuture que contiene el resultado. Puede ser:

  • Un futuro exitoso que contiene un Environment, en caso de éxito.

  • Es un futuro con errores que contiene un InvalidArgumentException si los roles solicitados no son válidos.

  • Es un futuro fallido que contiene un InternalException si la llamada falló debido a un error interno.
Arroja
com.google.android.managementapi.common.exceptions.ApiLevelException

Si el nivel de API del SDK del dispositivo no es suficiente para ciertos roles solicitados (esto puede ser adicional a un requisito general de nivel de API mínimo para la llamada en sí) {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} requiere el nivel de API 23 o superior. Cualquier otro rol requiere el nivel de API 28 o superior.

prepareEnvironment

suspend fun prepareEnvironment(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
): PrepareEnvironmentResponse

Prepara el dispositivo asegurándose de que la app de Android Device Policy esté instalada y lista.

El comportamiento depende del contexto:

  • Flujo de confianza del dispositivo: Si no está instalada la app de Android Device Policy, se le solicita al usuario que la instale. Si la app ya está instalada, se actualizará de forma silenciosa.

  • Flujo de inscripción del dispositivo: Instala silenciosamente la app de Android Device Policy si aún no está instalada y se asegura de que esté lista para usarse, sin interacción del usuario.

Parámetros
notificationServiceComponentName: ComponentName?

Es el ComponentName del servicio que extiende NotificationReceiverService. Si se proporciona, debe ser un componente válido que pertenezca a la app que realiza la llamada y que se haya exportado en el manifiesto. Para recibir notificaciones sobre los eventos de preparación del entorno, debes hacer lo siguiente:

  1. Implementa la interfaz EnvironmentListener en tu app.

  2. Proporciona una implementación para controlar los eventos recibidos.

  3. Extiende NotificationReceiverService y proporciona una instancia de EnvironmentListener.

  4. Agrega la clase NotificationReceiverService extendida a tu archivo AndroidManifest.xml y asegúrate de que se exporte.

Por ejemplo:

class MyEnvironmentListener : EnvironmentListener {
  override fun onEnvironmentEvent(event: EnvironmentEvent) {
    // Handle the environment event.
  }
}

class MyNotificationReceiverService : NotificationReceiverService() {
  override fun getPrepareEnvironmentListener(): EnvironmentListener? {
    return MyEnvironmentListener()
  }
}
Muestra
PrepareEnvironmentResponse

PrepareEnvironmentResponse que contiene detalles sobre el estado final de la preparación del entorno.
Arroja
com.google.android.managementapi.common.exceptions.InvalidArgumentException

Si:

  • [notificationServiceComponentName] no es un componente válido que pertenece a la app que realiza la llamada o no se exportó en el manifiesto.
  • Los roles solicitados incluyen {@code Role.RoleType.DEVICE_POLICY_CONTROLLER}, y no se proporciona {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} o no extiende {@code android.app.admin.DeviceAdminReceiver}.
  • Los roles solicitados no son válidos.
java.lang.SecurityException

Si el llamador no está autorizado para llamar a esta API.
com.google.android.managementapi.environment.GooglePlayServicesAppNotUpdatedException

Si los Servicios de Google Play no están actualizados
com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateUnrecoverableException

Si la Política de Dispositivos Android no se instala o actualiza, y el error es irrecuperable.
com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateRecoverableException

Si la app de Política de Dispositivos Android no se instala o actualiza, y el error se puede recuperar (p.ej., la solicitud falló debido a problemas de red transitorios), se puede volver a intentar la solicitud.
com.google.android.managementapi.environment.AndroidDevicePolicyInstallConsentDeclinedException

Si el usuario rechaza la instalación de la app de Android Device Policy
com.google.android.managementapi.environment.AndroidDevicePolicyInstallConsentDismissedException

Si el usuario descarta la pantalla de consentimiento para la instalación.
com.google.android.managementapi.common.exceptions.InternalException

Si la llamada falló debido a un error interno.
com.google.android.managementapi.environment.PlayStoreUpdateUnrecoverableException

Si falló la actualización de Play Store.
com.google.android.managementapi.common.exceptions.ApiLevelException

Si el nivel de API del SDK del dispositivo no es suficiente para ciertos roles solicitados (esto puede ser adicional a un requisito general de nivel de API mínimo para la llamada en sí).{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} requiere el nivel de API 23 o superior. Cualquier otro rol requiere el nivel de API 28 o superior.

prepareEnvironmentAsync

fun prepareEnvironmentAsync(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
): ListenableFuture<PrepareEnvironmentResponse>

Prepara el dispositivo asegurándose de que la app de Android Device Policy esté instalada y lista.

El comportamiento depende del contexto:

  • Flujo de confianza del dispositivo: Si no está instalada la app de Android Device Policy, se le solicita al usuario que la instale. Si la app ya está instalada, se actualizará de forma silenciosa.

  • Flujo de inscripción del dispositivo: Instala silenciosamente la app de Android Device Policy si aún no está instalada y se asegura de que esté lista para usarse, sin interacción del usuario.

Parámetros
notificationServiceComponentName: ComponentName?

Es el ComponentName del servicio que extiende NotificationReceiverService. Si se proporciona, debe ser un componente válido que pertenezca a la app que realiza la llamada y que se haya exportado en el manifiesto. Para recibir notificaciones sobre los eventos de preparación del entorno, debes hacer lo siguiente:

  1. Implementa la interfaz EnvironmentListener en tu app.

  2. Proporciona una implementación para controlar los eventos recibidos.

  3. Extiende NotificationReceiverService y proporciona una instancia de EnvironmentListener.

  4. Agrega la clase NotificationReceiverService extendida a tu archivo AndroidManifest.xml y asegúrate de que se exporte.

Por ejemplo:

class MyEnvironmentListener : EnvironmentListener {
  override fun onEnvironmentEvent(event: EnvironmentEvent) {
    // Handle the environment event.
  }
}

class MyNotificationReceiverService : NotificationReceiverService() {
  override fun getPrepareEnvironmentListener(): EnvironmentListener? {
    return MyEnvironmentListener()
  }
}
Muestra
ListenableFuture<PrepareEnvironmentResponse>

Un ListenableFuture que contiene el resultado. Puede ser

  • Un objeto Future exitoso que contiene un objeto PrepareEnvironmentResponse con detalles sobre el estado final de la preparación del entorno.

  • Un futuro fallido que contiene un InvalidArgumentException si se cumple alguna de las siguientes condiciones:

    • [notificationServiceComponentName] no es un componente válido que pertenece a la app que realiza la llamada o no se exportó en el manifiesto.
    • Los roles solicitados no son válidos.
    • Los roles solicitados incluyen {@code Role.RoleType.DEVICE_POLICY_CONTROLLER}, y no se proporciona {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} o no extiende {@code android.app.admin.DeviceAdminReceiver}.

  • Es un futuro fallido que encapsula un SecurityException si el llamador no está autorizado para llamar a esta API.

  • Es un futuro fallido que encapsula un GooglePlayServicesAppNotUpdatedException si los Servicios de Google Play no están actualizados.

  • Es un futuro con errores que contiene un AndroidDevicePolicyInstallOrUpdateUnrecoverableException si Android Device Policy no se puede instalar o actualizar, y el error es irrecuperable.

  • Es un futuro fallido que encapsula un AndroidDevicePolicyInstallOrUpdateRecoverableException si la app de Política de dispositivos Android no se instala o actualiza, y el error es recuperable (p.ej., la solicitud falló debido a problemas de red transitorios), por lo que se puede volver a intentar la solicitud.

  • Es un futuro con errores que encapsula un AndroidDevicePolicyInstallConsentDeclinedException si el usuario rechaza la instalación de la app de Android Device Policy.

  • Es un futuro fallido que encapsula un AndroidDevicePolicyInstallConsentDismissedException si el usuario descarta la pantalla de consentimiento de instalación.

  • Es un futuro fallido que contiene un InternalException si la llamada falló debido a un error interno.

  • Es un futuro fallido que encapsula un PlayStoreUpdateUnrecoverableException si falló la actualización de Play Store.
Arroja
com.google.android.managementapi.common.exceptions.ApiLevelException

Si el nivel de API del SDK del dispositivo no es suficiente para ciertos roles solicitados {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} requiere el nivel de API 23 o superior. Cualquier otro rol requiere el nivel de API 28 o superior.