1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
<html devsite>
<head>
<title>Enterprise OTA Updates</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2018 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
{% include "_versions.html" %}
<p>
The
<a href="https://source.android.com/compatibility/android-cdd#11_updatable_software">Android
Compatibility Definition Document (CDD) Updatable Software</a>
requires devices to implement the
<a
href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html"
class="external"><code>SystemUpdatePolicy</code></a>
class. <code>SystemUpdatePolicy</code> lets the device owner (DO) app, if
present, control the installation of system updates.
</p>
<h2 id="notify-do">Notifying device owners</h2>
<p>
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
<code>DevicePolicyManager.notifyPendingSystemUpdate(long updateReceivedTime, boolean isSecurityPatch)</code>
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
<code>DevicePolicyManager.notifyPendingSystemUpdate(long updateReceivedTime)</code>.
</p>
<p>
If an update isn’t currently available, the OTA client reports this by
setting the <code>updateReceivedTime</code> argument to <code>-1</code>.
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.
</p>
<h2 id="system-update-policy">System update policy</h2>
<p>
Android {{ androidPVersionNumber }} enhances the ability for device
owners to
<a href="https://developer.android.com/work/dpc/system-updates">control
updates</a> 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.
</p>
<p>
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:
</p>
<ul>
<li>
<a
href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html#TYPE_INSTALL_AUTOMATIC"
class="external"><code>TYPE_INSTALL_AUTOMATIC</code></a>
</li>
<li>
<a
href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html#TYPE_INSTALL_WINDOWED"
class="external"><code>TYPE_INSTALL_WINDOWED</code></a>
</li>
<li>
<a
href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy.html#TYPE_POSTPONE"
class="external"><code>TYPE_POSTPONE</code></a>
</li>
</ul>
<p>
Device owners can also
<a href="https://developer.android.com/work/dpc/system-updates#freeze-periods">set
freeze periods</a> (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
<code>SystemUpdatePolicy.InstallationOption</code> (see
following section), however the OTA client can also call
<a href="https://developer.android.com/reference/android/app/admin/SystemUpdatePolicy#getFreezePeriods()"><code>SystemUpdatePolicy.getFreezePeriods()</code></a>
to check if the device is in a freeze period.
</p>
<h2 id="implementing-installation-options">
Implementing installation options
</h2>
<p>
Android {{ androidPVersionNumber }} introduces an @SystemApi,
<code>SystemUpdatePolicy.InstallationOption</code>, that is designed
for the system update clients.
<code>SystemUpdatePolicy.InstallationOption</code> 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:
</p>
<ul>
<li>
<code>TYPE_INSTALL_AUTOMATIC</code> - Incoming system updates install
immediately and without user intervention as soon as they become
available. The device reboots automatically.
</li>
<li>
<code>TYPE_POSTPONE</code> - 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.
</li>
<li>
<code>TYPE_PAUSE</code> - Incoming system updates can be delayed
indefinitely until further notice. Users cannot install an update
manually. <code>TYPE_PAUSE</code> delays all updates, including
security patches.
</li>
</ul>
<p>
System update clients can query
<code>SystemUpdatePolicy.InstallationOption</code> using
<code>SystemUpdatePolicy.getInstallationOptionAt(long <var>when</var>)</code>,
where <var>when</var> represents the time the installation option is
being queried in number of milliseconds since Epoch. Using the
<code>SystemUpdatePolicy.getInstallationOptionAt(long <var>when</var>)</code>
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.
</p>
<p>
The system update client must listen for
<code>DevicePolicyManager.ACTION_SYSTEM_UPDATE_POLICY_CHANGED</code>
broadcasts in case the whole policy is updated.
</p>
<h2 id="validating-the-type_pause-policy">
Validating the <code>TYPE_PAUSE</code> policy
</h2>
<p>
You can manually validate the <code>TYPE_PAUSE</code> option works
on an OTA system.
</p>
<h3 id="policy-type_pause-in-effect">
Policy <code>TYPE_PAUSE</code> is in effect
</h3>
<p>
To validate a <code>TYPE_PAUSE</code> policy is working:
</p>
<ol>
<li>
Set an automatic policy and specify <code>TYPE_PAUSE</code>.
</li>
<li>
While the system clock is in the pause period, push an OTA update.
</li>
<li>
Verify the device does not take the OTA update and the user
cannot manually install the update.
</li>
<li>
If the device is an A/B device, reboot the device and verify the
reboot did not trigger an auto-install of the update.
</li>
</ol>
<h3 id="policy-type_pause-is-expired">
Policy <code>TYPE_PAUSE</code> is expired
</h3>
<p>
To validate an expired <code>TYPE_PAUSE</code> policy is working:
</p>
<ol>
<li>
Set an automatic policy and specify <code>TYPE_PAUSE</code>.
</li>
<li>
While the system clock is in the pause period, push an OTA update.
</li>
<li>
Wait for the pause to period to expire.
</li>
<li>
Verify the device automatically reboots and the OTA update is
taken after the reboot.
</li>
</ol>
</body>
</html>
|
