Первое Android-приложение из PWA через Capacitor

Это руководство относится только к существующему web/PWA-продукту. Для нового native, API, media, background или device-integrated приложения начинайте с универсального runbook и выбирайте Kotlin/Compose.

Предварительные условия

• PWA собирается командой npm run build.
• Production-бандл не зависит от dev server.
• Все ресурсы основного пользовательского сценария входят в бандл.
• Android Studio, SDK 36 и хотя бы одно устройство настроены.
• Выбран окончательный package name, например ru.example.arcade.runner.

1. Создайте рабочую ветку и baseline

Перед интеграцией убедитесь, что web-версия проходит существующие проверки:

npm ci
npm test
npm run build

Если проект пока не в Git, сначала создайте отдельный проектный репозиторий, а не общий репозиторий в домашнем каталоге.

2. Добавьте Capacitor

npm install @capacitor/core @capacitor/android
npm install --save-dev @capacitor/cli
npx cap init

При cap init задайте:

• app name — пользовательское название;
• app ID — постоянный reverse-domain identifier;
• webDir — каталог production-сборки, например dist.

Пример capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'ru.example.arcade.runner',
  appName: 'Arcade Runner',
  webDir: 'dist',
};

export default config;

Добавьте Android platform:

npx cap add android

3. Синхронизируйте web-бандл

После каждого изменения web-кода:

npm run build
npx cap sync android

cap sync копирует собранный web-бандл и обновляет нативные зависимости. Не редактируйте скопированные web-ассеты внутри android/ вручную.

4. Первый запуск

Из CLI:

npx cap run android

Или откройте проект в Android Studio:

npx cap open android

Выберите физическое устройство/AVD и запустите debug variant.

5. Настройте Android-поведение

Минимально проверьте:

• portrait/landscape согласно дизайну приложения;
• immersive/fullscreen без блокировки системной навигации;
• предсказуемое действие Back;
• сохранение пользовательского состояния до перехода в background;
• паузу активных timers/media в pause/visibilitychange;
• safe areas, вырезы и edge-to-edge;
• отсутствие случайных внешних ссылок внутри WebView;
• восстановление после уничтожения activity системой.

Нативные плагины добавляйте только при необходимости. Каждая зависимость может добавить permissions и повлиять на Data Safety.

6. Offline smoke-test

1. Установите debug APK.
2. Запустите игру один раз.
3. Принудительно остановите приложение.
4. Включите airplane mode.
5. Запустите приложение с launcher.
6. Пройдите основной пользовательский сценарий и перезапустите приложение.

Если первый запуск без сети не работает, найдите remote fonts, CDN, analytics, remote config или неупакованные ассеты.

7. Команды проекта

Рекомендуемые scripts:

{
  "scripts": {
    "build": "vite build",
    "android:sync": "npm run build && cap sync android",
    "android:run": "npm run android:sync && cap run android",
    "android:lint": "cd android && ./gradlew lint",
    "android:test": "cd android && ./gradlew test",
    "android:debug": "npm run android:sync && cd android && ./gradlew assembleDebug",
    "android:bundle": "npm run android:sync && cd android && ./gradlew bundleRelease"
  }
}

Замените vite build на фактическую команду проекта.

8. Release bundle

Android App Bundle собирается Gradle-задачей:

cd android
./gradlew bundleRelease

Обычно результат находится в android/app/build/outputs/bundle/release/. Неподписанный или неправильно подписанный AAB не загружайте в Play Console. Сборка AAB из CLI.