Перейти к содержанию

Мобильный клиент

Общие сведения

Для разработки мобильного клиента используется среда выполнения кросс-платформенных приложений Capacitor, что даёт возможность использовать единый стек технологий (JavaScript/TypeScript, HTML, CSS). Приложение интегрировано с нативными API мобильных устройств под управлением iOS и Android (файловая система, камера, биометрия, push-уведомления), а также использует существующую веб-логику и компоненты лёгкого клиента.

Сборка мобильного приложения для Android

Note

Проверено с Gradle 8.x и Java Development Kit 21

Установка окружения

Требуется установить Android Studio.

Сборка

Для запуска сборки нужно использовать:

Windows: ../../build-mobile-client-android.bat

Linux/MacOS: ../../build-mobile-client-android.sh

После выполнения скрипта файлы сборки .apk и .aab будут находиться в папке android/app/build/outputs.

Сборка мобильного приложения для iOS

Note

Проверено на актуальных версиях Xcode и соответствующих инструментах сборки.

Установка окружения

Потребуется MacOS с установленным Xcode.

Сборка

Для запуска сборки нужно использовать:

../../build-mobile-client-ios.sh

После выполнения скрипта файлы сборки .xcarchive и .ipa будут находиться в папке ios/App/build.

Debug-сборка для локального тестирования

Note

По умолчанию используется релизная сборка, которая исключает библиотеку jcesarmobile-ssl-skip.

Important

Использование jcesarmobile-ssl-skip допускается только для локального тестирования. В релизной сборке эта библиотека должна быть исключена, иначе приложение не пройдет публикацию в Google Play.

Чтобы собрать приложение для локального тестирования в режиме debug с использованием библиотеки jcesarmobile-ssl-skip, нужно отредактировать соответствующий скрипт:

  • ../../build-mobile-client-android.bat — при сборке приложения Android на Windows;
  • ../../build-mobile-client-android.sh— при сборке приложения Android на Linux/MacOS;
  • ../../build-mobile-client-ios.sh — при сборке приложения iOS.

Требуется заменить строку 

call npm run cap:sync:release
на 
call npm run cap:sync:debug

В результате будет собрана версия приложения с поддержкой обхода SSL-проверки.

Запуск приложения с hot-reload

Для запуска dev приложения с hot-reload:

  • в index.hml в window.__HOT_RELOAD__ установить значение true.
  • в webpack.dev.config.js установить значение переменной publicPath без localhost, например 192.168.1.6:3000.
  • в capacitor.config добавить настройку server с url к dev серверу.
  • в app-local-server.json добавить к настройке "AllowedCorsOrigins" адрес dev сервера, например http://192.168.1.6:3000.
  • для запуска сервера в студии нужно добавить аргументы командной строки в настройках запуска, например --urls http://192.168.1.6:5000.

Изменение стартовой страницы в мобильном приложении

  • требуется собрать проект mobile-start-page, для этого необходимо перейти в папку проекта, выполнив команду cd ./mobileTools/mobile-start-page/.
  • выполнить npm i.
  • выполнить npm run build.
  • перейти в Tessa.Web.Server используя команду cd ../.., затем, собрать и запустить приложение npx cap run android.

Атрибуты

Зарезервированные атрибуты для html шаблонов, используемых в мобильном приложении

  1. data-placeholder - атрибут, используемый для замены дочернего узла на узел, указанный в файле с мета-информацией. Для этого атрибута важно указывать значение, так как это значение будет использовано как ключ, под которым хранится новое значение.

    Example

    <b data-placeholder="BundlePush_HeaderTitle">Ошибка</b>. Текст Ошибка узла b будет заменен на новый узел, который хранится в файле с мета-информации под ключом BundlePush_HeaderTitle.

  2. data-bundlepush-error-message - атрибут, используемый для замены дочернего узла на узел, указанный в файле с мета-информацией. Значение атрибута не используется, так как ключ для поиска в файле с мета-информацией формируется в зависимости от ошибки.

  3. data-open-url-in-browser - указывает, что нажатие на узел с этим атрибутом требует открытия некой ссылки в браузере. Данный атрибут требуется использовать только вместе с атрибутом href. Значение атрибута не используется.

  4. data-send-app-log-files - указывает, что нажатие на узел с этим атрибутом приведет к поднятию системного окна по отправке файлов (логов приложения) в стороннее приложение. Значение атрибута не используется.

  5. data-close-view - указывает, что нажатие на узел с этим атрибутом приведет к закрытию webView, отображающий данный html-код. Значение атрибута не используется.

Приоритеты атрибутов

У одних и тех же узлов могут быть указаны несколько кастомных атрибутов, которые требуют разной обработки. Во избежание путаницы установлены некоторые приоритеты для атрибутов:

  1. data-send-app-log-files (наивысший приоритет).
  2. data-open-url-in-browser(средний приоритет).
  3. data-close-view (наименьший приоритет).

Example

<b data-open-url-in-browser="true" href="https:\\..." data-send-app-log-files="true">Ошибка</b>. Так как присутствует атрибут data-send-app-log-files, то нажатие на узел b приведет к отправке логов приложения, другие атрибуты будут игнорироваться.

Deep link имеет следующую структуру:

  • обрабатываем ссылку следующего ввида - {schema}://OpenURL?Domain={Base64Domain}&Pathname={Base64Pathname};
  • schema - схема приложения должна иметь вид tessamobile;
  • Base64Domain - это URL вида https://moblie-dev-win/tessa/web в формате base64;
  • Base64Pathname - это строка вида /card/6ad668c5-a9a0-4bec-8326-fdea7d23a4ef в формате base64.

Linux

  • Для работы mobile client c сервером на linux, нужно настроить CORS, для этого необходимо внести изменения в файл app.json. Если была произведена установка согласно документации по стандартному пути и папки не переименовывались, то файл будет расположен по следующему пути /home/{user}/tessa/web/app.json, где user - имя учетной записи.
    В файле необходимо указать следующие параметры: "CookiesSameSite": "None", "AllowedCorsOrigins": ["capacitor://localhost", "https://localhost"]. Если же нет возможности подключиться через localhost к серверу, то нужно добавить адрес сервера к вышеуказанному списку. Например, "https://*.ngrok-free.app", "capacitor://*.ngrok-free.app".

Рекомендуемые настройки и расширения VSCode

  • .vscode/settings.json.sample рекомендуемые базовые настройки для VSCode.
  • .vscode/extensions.json рекомендуемые расширения для VSCode.

Скрипты

  • npm run start - запускает webpack-dev-server с hot-reload.

Для правильной работы веб-сервис должен быть запущен с флагом DevelopmentHot: 

cd "C:\Tessa\web"
$Env:ASPNETCORE_ENVIRONMENT = "DevelopmentHot"
./Tessa.Web.Server.exe

Чтобы подключиться с устройства, веб-сервис должен быть запущен с дополнительными настройками: 

cd "C:\Tessa\web"
$Env:ASPNETCORE_ENVIRONMENT = "DevelopmentHot"
$Env:WEBPACK_PUBLIC_PATH = "//192.168.1.1:3000"
./Tessa.Web.Server.exe http://192.168.1.1:5000

Для запуска по другому порту:

npm run start '--' --port 9000

cd "C:\Tessa\web"
$Env:ASPNETCORE_ENVIRONMENT = "DevelopmentHot"
$Env:WEBPACK_PUBLIC_PATH = "//0.0.0.0:9000"
./Tessa.Web.Server.exe

  • npm run start:refresh - запускает webpack-dev-server с react-refresh.

  • npm run build - сборка бандла в прод режиме. В бандле будет только код платформы и платформенные расширения.

  • npm run sdk-build - сборка расширений типового проекта. После сборки расширения будут в wwwroot/extensions.

  • npm run type-check - проверка корректности типизации.

  • npm run lint-check - проверка линтером для @tessa пакетов.

  • npm run test-check - запуск тестов для @tessa пакетов.

  • npm run analyze - запуск анализатора бандла (для проверки в какой чанк какой модуль попал).

Back to top