EnvironmentClient

interface EnvironmentClient

Client to access environment related apis.

Use EnvironmentClientFactory to create an instance.

Summary

Public functions
suspend Environment

Returns the Environment.
ListenableFuture<Environment>

Returns the Environment.
suspend PrepareEnvironmentResponse
prepareEnvironment(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
)

Prepares the device environment.
ListenableFuture<PrepareEnvironmentResponse>
prepareEnvironmentAsync(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
)

Prepares the device environment.

Public functions

getEnvironment

suspend fun getEnvironment(request: GetEnvironmentRequest): Environment

Returns the Environment. It helps the caller to know if environment is ready or not.

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

If the requested roles are not valid.
com.google.android.managementapi.common.exceptions.InternalException

If call failed due to an internal error.
com.google.android.managementapi.common.exceptions.ApiLevelException

If the device's SDK API level is insufficient for certain requested roles (this may be in addition to a general minimum API level requirement for the call itself). {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} requires API level 23 or above. Any other roles require API level 28 or above.

getEnvironmentAsync

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

Returns the Environment. It helps the caller to know if environment is ready or not.

Returns
ListenableFuture<Environment>

A ListenableFuture wrapping the result. This can be:

  • A successful future wrapping a Environment, in case of success.

  • A failed future wrapping a

  • A failed future wrapping a InvalidArgumentException, if the requested roles are not valid.

  • A failed future wrapping a InternalException, if call failed due to an internal error.
Throws
com.google.android.managementapi.common.exceptions.ApiLevelException

If the device's SDK API level is insufficient for certain requested roles (this may be in addition to a general minimum API level requirement for the call itself). {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} requires API level 23 or above. Any other roles require API level 28 or above.

prepareEnvironment

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

Prepares the device environment.

Prompts the user to install the necessary Android Device Policy application. Proceeds with installation if user accepts the prompt. After successful installation, it performs operations to make sure that the Android Device Policy app is ready.

Parameters
notificationServiceComponentName: ComponentName?

The ComponentName of the service extending NotificationReceiverService. If provided, it must be a valid component belonging to the calling app, and exported in the manifest. To get notified of Environment preparation events, you need to:

  1. Implement the EnvironmentListener interface in your app.

  2. Provide an implementation for how to handle the received events.

  3. Extend NotificationReceiverService and provide an EnvironmentListener instance.

  4. Add the extended NotificationReceiverService class to your AndroidManifest.xml and ensure that it is exported.

For example:

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

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

PrepareEnvironmentResponse containing details about the final status of the environment preparation.
Throws
com.google.android.managementapi.common.exceptions.InvalidArgumentException

If:

  • [notificationServiceComponentName] is not a valid component belonging to the calling app or not exported in the manifest.
  • The requested roles includes {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} and the {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} is not provided or does not extend {@code android.app.admin.DeviceAdminReceiver}.
  • The requested roles are not valid.
java.lang.SecurityException

If the caller is not authorized to call this API.

com.google.android.managementapi.environment.exception.GooglePlayServicesAppNotUpdatedException If Google Play Services is not up-to-date.

com.google.android.managementapi.environment.exception.AndroidDevicePolicyInstallOrUpdateUnrecoverableException If Android Device Policy fails to install or update and the error is unrecoverable.

com.google.android.managementapi.environment.exception.AndroidDevicePolicyInstallOrUpdateRecoverableException If Android Device Policy app fails to install or update and the error is recoverable (e.g. request failed due to transient network issues), so the request can be retried.

com.google.android.managementapi.environment.exception.AndroidDevicePolicyInstallConsentDeclinedException If the user declines to install Android Device Policy app.

com.google.android.managementapi.environment.exception.AndroidDevicePolicyInstallConsentDismissedException If the user dismisses the installation consent screen.
com.google.android.managementapi.common.exceptions.InternalException

If call failed due to an internal error.

com.google.android.managementapi.environment.exception.PlayStoreUpdateUnrecoverableException If the Play Store update failed.
com.google.android.managementapi.common.exceptions.ApiLevelException

If the device's SDK API level is insufficient for certain requested roles (this may be in addition to a general minimum API level requirement for the call itself).{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} requires API level 23 or above. Any other roles require API level 28 or above.

prepareEnvironmentAsync

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

Prepares the device environment.

Prompts the user to install the necessary Android Device Policy application. Proceeds with installation if user accepts the prompt. After successful installation, it performs operations to make sure that the Android Device Policy app is ready.

Parameters
notificationServiceComponentName: ComponentName?

The ComponentName of the service extending NotificationReceiverService. If provided, it must be a valid component belonging to the calling app, and exported in the manifest. To get notified of environment preparation events, you need to:

  1. Implement the EnvironmentListener interface in your app.

  2. Provide an implementation for how to handle the received events.

  3. Extend NotificationReceiverService and provide an EnvironmentListener instance.

  4. Add the extended NotificationReceiverService class to your AndroidManifest.xml and ensure that it is exported.

For example:

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

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

A ListenableFuture wrapping the result. This can be

  • A successful future wrapping a PrepareEnvironmentResponse containing details about the final status of the environment preparation.

  • A failed future wrapping a InvalidArgumentException if:

    • [notificationServiceComponentName] is not a valid component belonging to the calling app or not exported in the manifest.
    • The requested roles are not valid.
  • The requested roles includes {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} and the {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} is not provided or does not extend {@code android.app.admin.DeviceAdminReceiver}.

  • A failed future wrapping a

  • A failed future wrapping a SecurityException, if the caller is not authorized to call this API.

  • A failed future wrapping a GooglePlayServicesAppNotUpdatedException if Google Play Services is not up-to-date.

  • A failed future wrapping a AndroidDevicePolicyInstallOrUpdateUnrecoverableException if Android Device Policy fails to install or update and the error is unrecoverable.

  • A failed future wrapping a AndroidDevicePolicyInstallOrUpdateRecoverableException if Android Device Policy app fails to install or update and the error is recoverable (e.g. request failed due to transient network issues), so the request can be retried.

  • A failed future wrapping a AndroidDevicePolicyInstallConsentDeclinedException if the user declines to install Android Device Policy app.

  • A failed future wrapping a AndroidDevicePolicyInstallConsentDismissedException if the user dismisses the installation consent screen.

  • A failed future wrapping a InternalException, if call failed due to an internal error.

  • A failed future wrapping a PlayStoreUpdateUnrecoverableException if the Play Store update failed.

    		•
    Throws
    com.google.android.managementapi.common.exceptions.ApiLevelException

    If the device's SDK API level is insufficient for certain requested roles. {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} requires API level 23 or above. Any other roles require API level 28 or above.