Enterprise OTA updates

The Android Compatibility Definition Document (CDD) Updatable Software requires devices to implement the SystemUpdatePolicy class. SystemUpdatePolicy lets the device owner (DO) app, if present, control the installation of system updates.

Notify device owners

The over-the-air (OTA) client must notify device owner apps about incoming OTA updates using a system API. The OTA client must also include a timestamp recording when the OTA update first became available. OTA clients can call DevicePolicyManager.notifyPendingSystemUpdate(long updateReceivedTime, boolean isSecurityPatch) to notify device owner apps. If the OTA client doesn’t know if an update is a security patch, the OTA client can fall back to using DevicePolicyManager.notifyPendingSystemUpdate(long updateReceivedTime).

If an update isn’t currently available, the OTA client reports this by setting the updateReceivedTime argument to -1. We recommend sending notifications whenever the OTA client polls the OTA server, or when an OTA is pushed to the client. You can also send out notifications more frequently.

System update policy

Android 9 enhances the ability for device owners to control updates by allowing device owners to postpone OTA updates for up to 90 days. Focusing on dedicated device (previously called COSU) solutions, this feature lets owners pause the OS version running on devices over critical periods, such as holidays.

To comply with the CDD, the OTA client must implement behavioral policies. The DO can set the following policies, which must be respected by the device system update subsystems:

Device owners can also set freeze periods (in Android 9 or later) that freeze the OS version over critical periods, such as holidays or other busy times. The system doesn't install OTA updates during a freeze period. We recommend using SystemUpdatePolicy.InstallationOption (see following section), however the OTA client can also call SystemUpdatePolicy.getFreezePeriods() to check if the device is in a freeze period.

Implement installation options

Android 9 introduces an @SystemApi, SystemUpdatePolicy.InstallationOption, that is designed for the system update clients. SystemUpdatePolicy.InstallationOption serves as a wrapper class for the policies and freeze periods. An installation option tells clients how to act on incoming system updates and how long that action is valid for, given the current system update policy or any freeze period that might be set. An installation option can be one of the following:

  • TYPE_INSTALL_AUTOMATIC - Incoming system updates install immediately and without user intervention as soon as they become available. The device reboots automatically.
  • TYPE_POSTPONE - Incoming system updates can be delayed for a maximum of 30 days. Users cannot install an update manually. Device manufacturers can choose whether or not to block security patches.
  • TYPE_PAUSE - Incoming system updates can be delayed indefinitely until further notice. Users cannot install an update manually. TYPE_PAUSE delays all updates, including security patches.

System update clients can query SystemUpdatePolicy.InstallationOption using SystemUpdatePolicy.getInstallationOptionAt(long when), where when represents the time the installation option is being queried in number of milliseconds since Epoch. Using the SystemUpdatePolicy.getInstallationOptionAt(long when) method, system update clients can act on the returned option until the effective time lapses. After the returned option lapses, the client can make another query, using a new timestamp, for the most recent option.

The system update client must listen for DevicePolicyManager.ACTION_SYSTEM_UPDATE_POLICY_CHANGED broadcasts in case the whole policy is updated.

Validate the TYPE_PAUSE policy

You can manually validate the TYPE_PAUSE option works on an OTA system.

Policy TYPE_PAUSE is in effect

To validate a TYPE_PAUSE policy is working:

  1. Set an automatic policy and specify TYPE_PAUSE.
  2. While the system clock is in the pause period, push an OTA update.
  3. Verify the device does not take the OTA update and the user cannot manually install the update.
  4. If the device is an A/B device, reboot the device and verify the reboot did not trigger an auto-install of the update.

Policy TYPE_PAUSE is expired

To validate an expired TYPE_PAUSE policy is working:

  1. Set an automatic policy and specify TYPE_PAUSE.
  2. While the system clock is in the pause period, push an OTA update.
  3. Wait for the pause to period to expire.
  4. Verify the device automatically reboots and the OTA update is taken after the reboot.