Что скрыто за реализацией Setup Wizard на любом Android-устройстве? Как получается, что системное приложение появляется один раз при первом запуске, а потом исчезает? Можно ли сразу накатить свой Setup Wizard на устройство и точно ли нужно писать свою реализацию этапа настройки блокировки экрана?
Меня зовут Олеся Шилова, я инженер-программист в отделе разработки приложений в YADRO. Вместе с коллегами разрабатываю системные приложения операционной системы kvadraOS. Недавно я работала над «Мастером настройки» и сегодня хочу рассказать, как это приложение работает в AOSP и с какими подводными камнями можно столкнуться при его создании. Заодно покажу примеры конфигурации.
Статья будет полезна тем, кто работает с Android-фреймворком и системными приложениями: поможет не допустить ошибок и сократить время на реализацию проекта.
Как «живет» Setup Wizard
Если человека встречают по одежке, то устройство — по Setup Wizard (он же «Мастер настройки»). Это первое приложение, с которым взаимодействует пользователь, и важный системный компонент, ведь от него зависит правильная инициализация устройства.
И сразу разочарую. Нельзя просто так взять и написать свой Setup Wizard, накатить его на устройство и заменить текущее приложение. Система все предусмотрела.
Ваш «Мастер настройки» должен находиться по адресу system/priv-app и работать под системным идентификатором пользователя. Главное, чтобы он работал как привилегированное приложение, подписанное платформенным ключом. А signature protected permissions находились в priv-app permissions white list — документация тут. Почему так?
Обычно при обращении к тому или иному системному сервису для настройки — языку, теме, навигационной настройке, строке состояния (status bar) — нужно обладать специальными разрешениями (permissions). Без них настроить язык или, например, заблокировать строку состояния не получится.
Жизненный цикл «Мастера настройки» — это последовательность состояний и переходов, которые определяют, как и когда запускается приложение, как оно функционирует и когда завершает работу.
Ключевые точки цикла:
Запуск устройства. Когда ActivityManagerService готов, systemReady запускает приоритетную home activity. Какую активность выбрать, решает PackageManagerService в зависимости от состояния системы. При первом запуске система считает устройство ненастроенным. Ниже расскажу, как она это определяет.
Запуск приложения. «Мастер настройки» помечен как home activity с высшим приоритетом, поэтому запускается именно он, а не ваш домашний экран.
Процесс настройки. Приложение запущено, и пользователь поочередно проходит через этапы настройки темы, языка, Wi-Fi и так далее.
Завершение настройки. «Мастер» фиксирует, что устройство настроено и блокирует себя через
PackageManager. Без специальных системных флагов и блокировки приложение запускалось бы повторно — например, когда пользователь перезагружает устройство или несанкционированно запускает приложение.Запуск домашнего экрана. Система запускает обычный домашний экран — он идет следующим по приоритету после «Мастера настройки».
Теперь предлагаю пробежаться по основным этапам создания Setup Wizard и посмотреть, какие могут быть тонкости.
Создавая Setup Wizard
Шаг 1. Настройка манифеста
Любое Android-приложение начинается с конфигурации в AndroidManifest.xml. На что здесь обратить внимание?
У основной активности «Мастера настройки» не должна стоять категория Launch. После завершения процесса настройки пользователю не нужно видеть Setup Wizard в системе. Eсли выставить Launch, «Мастер настройки» будет висеть в списке приложений.
Вместо этого основная intent-категория будет android.intent.category.HOME. По сути, «Мастер настройки» — это home-приложение: то, что пользователь видит в первую очередь после запуска устройства. Соответственно, нам нужно повысить для него приоритет активности. Если мы этого не сделаем, пользователь вместо Setup Wizard сразу увидит обычный домашний экран с обоями и списком приложений.
Пример конфигурации:
<application
…
android:taskAffinity="com.android.wizard"
android:theme="@style/Theme.MySetupWizard">
<activity
android:name=".MainActivity"
android:exported="true"
android:excludeFromRecents="true"
android:theme="@style/Theme.MySetupWizard">
<intent-filter android:priority="1">
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.HOME" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.SETUP_WIZARD" />
</intent-filter>
</activity>
</application>Что мы здесь видим:
taskAffinity="com.android.wizard"— позволяет «Мастеру настройки» работать в той же задаче, что и системный wizard (если он есть).android.intent.category.HOME– «Мастер настройки» определяется как home-приложение. При первом запуске система запускает наиболее доступный и приоритетный home screen. По дефолту у нас запускается обычный домашний экран, который по умолчанию имеет приоритет «0», но для «Мастера настройки» мы устанавливаемandroid:priority «1», чтобы он запустился первым.
android:category.SETUP_WIZARD— система Android распознает это приложение как часть процесса начальной настройки устройства. Подробное описание этой категории тут.android:excludeFromRecents="true"— благодаря этому параметру «Мастер настройки» не отображается в недавно открытых приложениях. Соответственно, если его не выставить, пользователь увидит Setup Wizard в списке с недавними приложениями.
Шаг 2. Менеджер для «Мастера настройки»
Теперь нам нужно создать класс менеджера, который будет отвечать за управление состоянием «Мастера настройки»: проверять состояние настройки системы и завершать работу приложения.
Файл SetupWizardManager.kt:
internal class SetupWizardManager(
val context: Context,
) {
private var statusBarManager: StatusBarManager =
context.getSystemService(StatusBarManager::class.java) as StatusBarManager
// 1
fun isSetupNotRequired(): Boolean = WizardManagerHelper.isUserSetupComplete(context)
// 2
fun setDisabledForSetup(enable: Boolean) {
statusBarManager.setDisabledForSetup(enable) // hidden/system API
}
// 3
fun finishSetup() {
setDisabledForSetup(false) // Включаем строку состояния
disableSelf() // Блокируем свой основной компонент, чтобы приложение не запускалось повторно
// Выставляем флаги, что устройство и пользователь настроены.
// В многопользовательском режиме Settings.Global.DEVICE_PROVISIONED = 1 уже будет активирован
Settings.Global.putInt(
context.contentResolver,
Settings.Global.DEVICE_PROVISIONED,
1,
)
Settings.Secure.putInt(
context.contentResolver,
Settings.Secure.USER_SETUP_COMPLETE,
1,
)
}
private fun disableSelf() {
context.packageManager.setComponentEnabledSetting(
ComponentName(context, MainActivity::class.java), // Наш основной компонент
PackageManager.COMPONENT_ENABLED_STATE_DISABLED,
PackageManager.DONT_KILL_APP,
)
}
}
1. Проверить состояния настройки системы — ключевые флаги:
Settings.Global.DEVICE_PROVISIONED— указывает, настроено ли устройство.Settings.Secure.USER_SETUP_COMPLETE— указывает, завершена ли настройка для конкретного пользователя.
Как это работает? При запуске устройства система проверяет эти значения. Если DEVICE_PROVISIONED = 0 или USER_SETUP_COMPLETE = 0, запускается «Мастер настройки» как приоритетный домашний экран. Когда наше приложение завершает свою работу, оно устанавливает для этих флагов значения «1» — это дает сигнал системе, что пользователь настроен и устройство готово к полноценному использованию. Если неправильно выставить флаги по состоянию системы — DEVICE_PROVISIONED, USER_SETUP_COMPLETE — системные приложения будут работать некорректно или вообще не откроются, так как почти в каждом системном приложении есть проверка на состояние этих флагов: Launcher, SystemUI, System Settings и так далее.
2. Отключить строку состояния (status bar) через StatusBarManager.setDisabledForSetup(). Это нужно, чтобы пользователь не смог выйти из процесса настройки, применять панель быстрых настроек или просматривать уведомления. Так мы гарантируем, что пользователь завершит все обязательные этапы настройки.
3. Завершить «Мастер настройки». Здесь нужно выставить флаги о готовности системы и разблокировать строку состояния. Также «Мастер настройки» должен заблокировать свою основную активность через PackageManager, чтобы предотвратить повторный запуск. После завершения он не будет отображаться, если устройство не будет сброшено до заводских настроек. Это очистит параметры и повторно включит пакет.
В своей основной активности мы спрашиваем у менеджера, нужно ли нам настраивать пользователя. Если пользователь уже настроен (USER_SETUP_COMPLETE = 1) — активность финишируется. Если нет, запускается процесс настройки. Это нужно, если кто-то за нас уже настроил систему — например, какое-либо приложение-админ для корпоративных устройств.
На этом же шаге можно определить тип пользователя: это владелец, вторичный пользователь или гость? Это позволит нам показывать пользователю разный набор этапов настройки или кастомизировать приложение так, как мы хотим.
Файл MainActivity.kt:
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
val wizardManager = SetupWizardManager(this)
val userManager = getSystemService(USER_SERVICE) as UserManager
// Проверяем настроен ли уже пользователь
if (wizardManager.isSetupNotRequired()) {
wizardManager.finishSetup()
return
}
wizardManager.setDisabledForSetup(true)
setContent {
MySetupWizardTheme {
Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
// Используем UserManager, чтобы узнать тип пользователя
if (userManager.isManagedProfile) {
WelcomeScreen(
name = "Work User",
modifier = Modifier.padding(innerPadding),
onClick = {
wizardManager.finishSetup()
}
)
} else {
WelcomeScreen(
name = "System User",
modifier = Modifier.padding(innerPadding),
onClick = {
wizardManager.finishSetup()
}
)
}
}
}
}
}
}
@Composable
fun WelcomeScreen(name: String,
modifier: Modifier = Modifier,
onClick: () -> Unit) {
Column(
modifier = Modifier.fillMaxSize(),
verticalArrangement = Arrangement.Center,
horizontalAlignment = Alignment.CenterHorizontally,
) {
Text(
text = "Welcome $name!",
modifier = modifier
)
Button(
onClick = onClick,
content = {
Text(
text = "Finish setup",
)
}
)
}
}
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
MySetupWizardTheme {
WelcomeScreen("Android", onClick = {})
}
}
Шаг 3. Реализация настроек
Setup Wizard может включать в себя один или более этапов настройки: выбор языка, таймзоны, темы, Wi-Fi, мобильной сети, блокировки экрана, навигации и так далее. Можно реализовать все, что хотите, — набор неограничен. И да, нет никакой необходимости писать свою реализацию настройки Wi-Fi или блокировки экрана — это уже есть в AOSP. Об этом я еще скажу ниже.
Многие производители кастомных AOSP используют для этого мастер-скрипт — это XML-файл с тегами, который парсится в коде, достает из него шаги и превращает их в actions:
Мы видим, что каждый шаг скрипта представлен тегом WizardAction, где ID — уникальный идентификатор. Содержимое может представлять собой URI Intent или другой URI скрипта.
Следующий action определяется тегом result. Пример: когда пользователь нажимает на кнопку «Пропустить», результат будет «1», он ведет к action google_services. По сути, это следующий экран с настройкой Google Account. В теге wizard:action может стоять любой полноценный стандартный action — например,com.google.android.setupwizard.LOCK_SCREEN.
В классах эти скрипты парсятся и превращаются в запуск той или иной настройки в сценарии Setup Wizard. Пример реализации можно посмотреть на GitHub.
Для многих этапов настройки — например, настройки языка, темы или навигации (жесты, кнопки) — чаще всего нужно использовать системное API и специальные разрешения. Пример:
<uses-permission android:name="android.permission.SET_TIME"
tools:ignore="ProtectedPermissions" />
<uses-permission android:name="android.permission.SET_TIME_ZONE"
tools:ignore="ProtectedPermissions" />
<uses-permission android:name="android.permission.STATUS_BAR"
tools:ignore="ProtectedPermissions" />
<uses-permission android:name="android.permission.MODIFY_DAY_NIGHT_MODE"
tools:ignore="ProtectedPermissions" /> Мастер-скрипт — это классика, но использовать его необязательно. Вместо этого можно сделать список строк из actions или из экранов в Navigation Compose. Здесь нет ограничений.
Шаг 4. Завершение мастера настройки
В конце всех шагов по настройке устройства мы обязательно завершаем мастер настройки через функцию finishSetup(). Метод приводила выше, здесь продублирую функцию менеджера:
// 3
fun finishSetup() {
setDisabledForSetup(false) // Включаем строку состояния
disableSelf() // Блокируем свой основной компонент, чтобы никто не смог его повторно запустить
// Выставляем флаги, что устройство и пользователь настроены.
// В многопользовательском режиме Settings.Global.DEVICE_PROVISIONED = 1 уже будет активирован
Settings.Global.putInt(
context.contentResolver,
Settings.Global.DEVICE_PROVISIONED,
1,
)
Settings.Secure.putInt(
context.contentResolver,
Settings.Secure.USER_SETUP_COMPLETE,
1,
)
}
private fun disableSelf() {
context.packageManager.setComponentEnabledSetting(
ComponentName(context, MainActivity::class.java), // Наш главный компонент
PackageManager.COMPONENT_ENABLED_STATE_DISABLED,
PackageManager.DONT_KILL_APP,
)
}
}
Системное окружение AOSP для «Мастера настройки»
System Settings
Некоторые настройки в цикле Setup Wizard необязательно реализовывать с нуля — обычно это касается более сложных структурно. Например, Wi-Fi-настройка или настройка экрана блокировки — это целые пакеты классов и работы с безопасностью. Поэтому лучше не изобретать велосипед заново, а использовать существующее решение.
Для этого используются System Settings — здесь уже предусмотрена работа с Setup Wizard. В приложении «Настройки» есть множество классов, которые Setup Wizard может использовать напрямую через intent. Такие классы в манифесте «Системных настроек» начинаются как Setup*.java. Они расширяют базовый класс, который показывается в самих «Системных Настройках». Например, класс SetupChooseLockGeneric расширяет ChooseLockGeneric, который является экраном выбора блокировки в приложении «Настройки». Реализацию SetupChooseLockGeneric можно посмотреть тут.
В пакете com.android.settings таких классов насчитывается около 15 штук: для блокировки экрана, настройки отпечатка пальцев, экран специальных возможностей и так далее.
Библиотеки Android Framework
Setup Compatibility Library (platform/external/setupcompat) — это библиотека, которая обеспечивает совместимость между различными версиями Android и реализациями «Мастера настройки» и включает в себя набор инструментов.
Основные возможности:
WizardManagerHelper— утилита для работы с wizard-менеджером системы. Проверка завершения настройки:WizardManagerHelper.isUserSetupComplete(context). Получение метаданных wizard:WizardManagerHelper.getWizardScriptUri(intent). Определение типа запуска:WizardManagerHelper.isInitialSetupWizard(intent).API для блокировки строки состояния.
Совместимость версий: абстракция над различиями в API разных версий Android.
Роль в жизненном цикле: SetupCompat обеспечивает корректную работу «Мастера настройки» на разных версиях Android, предоставляет унифицированный интерфейс для взаимодействия с системными компонентами wizard.
Setup Design Library (platform/external/setupdesign) — это библиотека компонентов UI, специально разработанных для «Мастера Настройки».
Основные компоненты:
GlifLayout: основной контейнер для экранов настройки.GlifHeaderLayout: заголовки с иконками и текстом.StickyHeaderListView: списки с закрепленными заголовками.Палитра цветов: стандартные цвета для «Мастеров настройки».
SetupDesign не влияет напрямую на жизненный цикл, но обеспечивает единый стиль и пользовательский опыт. Это важно для восприятия «Мастера настройки» как системного компонента.
Дефолтная реализация «Мастера настройки»
В AOSP есть дефолтная реализация мастера настройки: она также включает в себя настройку устройства с MDM. Этот пакет называется Provision и находится в системных приложениях AOSP.
Отмечу, что в системе можно оставить только дефолтный «Мастер настройки» — его достаточно для корректной работы системы. То есть делать свой Setup Wizard во что бы то ни стало необязательно. Но производители кастомной AOSP все-таки переопределяют пакет com.android.provision своим Setup Wizard — так все приложения выглядят как часть одной системы и у пользователя складывается позитивный опыт от взаимодействия с устройством.
Понимание компонентов и их взаимодействия друг с другом поможет не допустить банальных ошибок и быстро создать «Мастер настройки», который корректно интегрируется с системой и не будет срабатывать при каждой перезагрузке.