Native WebView App Template

Production-ready шаблон для создания WebView мобильных приложений

Универсальный шаблон нативных мобильных приложений на базе WebView с полным набором enterprise-функций. Проект включает Android и iOS версии, оптимизированные для быстрого ребрендинга под любой веб-сервис.

Текущая конфигурация (пример):

• URL: https://bxstore.ru
• User-Agent:
  BX_STORE_APP
• Package/Bundle ID:
  app.bxstore.ru

🚀 Быстрый старт

Требования

• Android: Android Studio, JDK 17+, Android SDK 29+
• iOS: macOS, Xcode 15+, CocoaPods
• Общее: ImageMagick (для генерации иконок)

Сборка и запуск

Android

iOS

✨ Основные возможности

🎯 Production-ready функционал

• ✅ Потоковая геолокация - event-driven обновления координат в реальном времени (без таймеров)
• ✅ Обработка ошибок сети - custom UI с автовосстановлением последней успешной страницы
• ✅ Модульная архитектура - разделение ответственности через сервисы (iOS) и callbacks (Android)
• ✅ Централизованная конфигурация -
  AppConfiguration
  enum (iOS), константы (Android)
• ✅ Персистентное хранилище - сохранение состояния через UserDefaults/SharedPreferences
• ✅ Полноэкранный WebView - нативный UI без видимых элементов браузера

🔧 Интеграции

• ✅ JavaScript Bridge - двустороннее взаимодействие между нативным кодом и веб-страницей
• ✅ Firebase Cloud Messaging - push-уведомления для Android и iOS
• ✅ SwipeRefreshLayout / Pull-to-refresh - ручное обновление страницы

🛠 Инструменты для ребрендинга

• ✅ update_app_config.sh - автоматизация изменения URL, User-Agent, Package ID
• ✅ generate_icons.sh - генерация иконок для всех разрешений из одного исходника

📋 Технические характеристики

Платформы

• Android: Минимум API 29 (Android 10.0), целевая API 35 (Android 15)
• iOS: Минимум iOS 17.0+

Разрешения

• Android:
  INTERNET
  ,
  ACCESS_FINE_LOCATION
  ,
  ACCESS_COARSE_LOCATION
  ,
  ACCESS_BACKGROUND_LOCATION
  ,
  POST_NOTIFICATIONS
• iOS: Location When In Use, Push Notifications

Архитектура геолокации

• Механизм: Event-driven потоковое обновление (не таймеры!)
• Точность: Высокая точность GPS
• Провайдеры:
  • Android: FusedLocationProviderClient + системный LocationManager (dual fallback)
  • iOS: CLLocationManager с делегатом
• Обновления: Моментально при изменении координат

Обработка ошибок сети

• Custom Error UI: Полноэкранное сообщение "Проблемы с интернет соединением"
• Кнопка "Обновить": Повторная попытка загрузки
• URL Persistence: Сохранение последнего успешного URL
• Автовосстановление: Загрузка сохранённой страницы при ошибке
• Защита от системных ошибок: Предотвращение показа стандартных страниц браузера

🌐 JavaScript API

Приложения предоставляют единый JavaScript API для взаимодействия с веб-страницей:

Глобальные переменные

События

Callback функции

Нативный API

🔧 Ребрендинг приложения

📝 Изменение названия приложения

Название приложения (отображаемое на экране устройства) настраивается в следующих файлах:

Android

Файл:

iOS

Файл:

Найдите и измените значение

INFOPLIST_KEY_CFBundleDisplayName = "Ваше Название";

Примечание: В

project.pbxproj

это значение встречается дважды — для Debug и Release сборок. Измените оба вхождения.

Автоматический способ (рекомендуется)

Используйте скрипт

Скрипт запросит:

1. Старый Application ID (например,
   app.bxstore.ru
   )
2. Новый Application ID (например,
   app.mycompany.com
   )
3. App Name для SharedPreferences (например,
   MyApp
   )
4. User-Agent (например,
   MY_CUSTOM_APP
   )
5. Домен (например,
   mycompany.com
   )

Что обновит скрипт:

iOS:

• ✅
  AppConfiguration.Network.baseURL
  - базовый URL приложения
• ✅
  AppConfiguration.Network.customUserAgent
  - User-Agent
• ✅
  CFBundleIdentifier
  в Info.plist - Bundle ID
• ✅
  NSExceptionDomains
  в Info.plist - домен для ATS

Android:

• ✅
  TARGET_URL
  константа в MainActivity - URL приложения
• ✅
  CUSTOM_USER_AGENT
  константа - User-Agent
• ✅
  PREFS_NAME
  константа - имя SharedPreferences
• ✅
  namespace
  в build.gradle
• ✅
  applicationId
  в build.gradle
• ✅
  package
  в AndroidManifest.xml
• ✅ Перемещение Java файлов в новый package
• ✅ Обновление package declarations во всех .java файлах
• ✅ Оба домена в network_security_config.xml (основной + www)

Ручная настройка (не рекомендуется)

🖼 Генерация иконок

Подготовка

1. Создайте квадратное изображение высокого разрешения (рекомендуется 2048x2048 px)
2. Сохраните как
   RESOURCES/ALL/ICO.png
3. Убедитесь, что установлен ImageMagick:
   brew install imagemagick

Запуск

Скрипт автоматически создаст:

• Android: все разрешения в
  ANDROID/app/src/main/res/mipmap-*
• iOS: все размеры в
  IOS/NeutralApp/Assets.xcassets/AppIcon.appiconset/

🔥 Firebase Cloud Messaging (Push-уведомления)

Настройка

1. Создайте проект в Firebase Console
2. Скачайте конфигурационные файлы:
   • Android:
     google-services.json
     →
     ANDROID/app/
   • iOS:
     GoogleService-Info.plist
     →
     IOS/NeutralApp/
3. Замените заглушки в проекте на реальные файлы
4. Пересоберите приложение

Реализация

Android

• Сервис:
  MyFirebaseMessagingService
  обрабатывает входящие уведомления
• FCM токен: Автоматически генерируется при запуске
• Конфигурация:
  ANDROID/app/google-services.json

iOS

• Инициализация: Firebase SDK в
  AppDelegate.swift
• FCM токен: Запрашивается при старте
• Background mode: Поддержка
  remote-notification
• Конфигурация:
  IOS/NeutralApp/GoogleService-Info.plist

🏗️ Архитектура кода

iOS - Модульная архитектура с сервисами

Файл:

Компоненты:

1. AppConfiguration

Централизованное хранение конфигурации приложения.

2. LocationService

Отвечает за получение и обработку геолокации с использованием делегата.

3. ErrorViewService

Управляет отображением custom error UI при проблемах с сетью.

4. URLStorageService

Персистентное хранение последнего успешного URL через UserDefaults.

5. JavaScriptBridge

Централизованная генерация JavaScript-кода для взаимодействия с WebView.

Преимущества:

• ✅ Чистая архитектура с разделением ответственности
• ✅ Легкая тестируемость через protocols и delegates
• ✅ Переиспользуемость компонентов
• ✅ Централизованная конфигурация

Android - Callback-based архитектура

Файлы:

Ключевые компоненты:

1. Константы конфигурации

2. Streaming Location Callback

Непрерывная передача координат без таймеров.

3. Error Layout Management

4. URL Persistence (SharedPreferences)

5. LocationManagerHelper (Dual Provider)

🔍 Отличия от базовых WebView-приложений

❌ Что НЕ используется (устаревшие подходы):

• Таймеры для обновления геолокации → Event-driven потоки
• Монолитный ViewController → Модульная архитектура
• Системные страницы ошибок → Custom error UI
• Отсутствие персистенции → UserDefaults/SharedPreferences

✅ Что реализовано (production best practices):

• Streaming location updates - координаты в реальном времени
• Error recovery - автовосстановление с сохранением состояния
• Modular architecture - разделение ответственности
• Centralized configuration - единая точка настройки
• Persistent storage - сохранение последнего успешного URL

📱 Использование шаблона

Сценарий 1: Создание нового WebView-приложения

1. Клонируйте репозиторий
2. Подготовьте иконку
   RESOURCES/ALL/ICO.png
3. Запустите
   ./update_app_config.sh
   :
   • Старый ID:
     app.bxstore.ru
   • Новый ID:
     app.yourcompany.com
   • App Name:
     YourApp
   • User-Agent:
     YOUR_APP_AGENT
   • Домен:
     yourcompany.com
4. Запустите
   ./generate_icons.sh
5. Замените Firebase конфигурации
6. Соберите проект:
   ./START_ANDROID.sh
   или
   ./START_IOS.sh

Сценарий 2: Серия приложений для разных доменов

Сценарий 3: Кастомизация функционала

Модульная архитектура позволяет легко добавлять новые сервисы:

iOS: создайте новый сервис, например

Android: расширьте MainActivity или создайте helper

🛡️ Безопасность и конфиденциальность

Network Security

• Android:
  network_security_config.xml
  - контроль доступа к доменам
• iOS:
  NSAppTransportSecurity
  в Info.plist

Разрешения

• Location: Запрашивается только "When In Use" (не Always)
• Notifications: Опциональные push-уведомления
• Internet: Ограничено списком доверенных доменов

Data Persistence

• Минимальное хранение: Только последний успешный URL
• UserDefaults/SharedPreferences: Локальное хранение без облака
• No Analytics: Шаблон не содержит встроенной аналитики

🚢 Публикация в сторы

Google Play Store (Android)

1. Обновите конфигурацию через
   update_app_config.sh
2. Создайте keystore для подписи:

3. Настройте
   ANDROID/app/build.gradle
   :

4. Соберите release APK/AAB:

Apple App Store (iOS)

1. Откройте
   IOS/NeutralApp.xcworkspace
   в Xcode
2. Настройте Signing & Capabilities:
   • Team: ваш Apple Developer аккаунт
   • Bundle Identifier: обновлённый через скрипт
3. Архивируйте: Product → Archive
4. Загрузите в App Store Connect

🧪 Тестирование

Локальная разработка

Android с локальным сервером:

iOS с локальным сервером:

Обновите

Отладка JavaScript Bridge

В веб-коде добавьте:

В Android:

В iOS:

📚 Дополнительные ресурсы

Документация

• WKWebView - Apple
• Android WebView Guide
• Firebase Cloud Messaging

Полезные команды

Android:

iOS:

🤝 Поддержка и вклад

Известные ограничения

• iOS требует HTTPS для production (можно обойти в Info.plist для разработки)
• Android emulator может не поддерживать геолокацию (используйте реальное устройство)
• Push-уведомления требуют валидные Firebase конфигурации

Структура проекта

native-webviev-app/
├── ANDROID/              # Android проект (Gradle)
│   └── app/
│       ├── src/main/java/app/bxstore/ru/
│       │   ├── MainActivity.java
│       │   └── LocationManagerHelper.java
│       └── build.gradle
├── IOS/                  # iOS проект (Xcode + CocoaPods)
│   └── NeutralApp/
│       └── ViewController.swift
├── RESOURCES/
│   └── ALL/
│       └── ICO.png       # Исходная иконка
├── update_app_config.sh  # Скрипт ребрендинга
├── generate_icons.sh     # Генерация иконок
├── START_ANDROID.sh      # Быстрый запуск Android
├── START_IOS.sh          # Быстрый запуск iOS
└── README.md             # Данная документация

📄 Лицензия

Проект является универсальным шаблоном для коммерческого и некоммерческого использования.

Создано как production-ready шаблон для быстрого развёртывания WebView-приложений с enterprise-функционалом.