Утилита для удобной работы веб-приложения внутри нативного приложения

• Как использовать Библиотеку описано здесь.
• Про особенности навигации в WV окружении NA можно прочитать здесь.
• Схематичное client-server взаимодействие внутри библиотеки описано здесь.

Сокращения, используемые в readme и комментариях

• BBtn (BackButton) — Кнопка «Назад» в нативной части экрана, которая может работать, как «Назад» в браузере.
• B2N (BridgeToNative) — сокращенное название данной Библиотеки.
• NA (Native application) — нативное приложение, для WebView которого написана эта библиотека.
• WA (Web application) — любое веб-приложение, которое открывается внутри WebView.
• WV (WebView) — область на экране нативного приложения, которая умеет отображать веб-контент.

Зачем это нужно

WV NA окружение отличается от браузерного, есть определенные сложности при работе внутри.

Вот несколько особенностей:

• Экран с WV содержит как UI-элементы NA, так и область для отрисовки веб-контента;
• WA может через специальный интерфейс и с помощью перехода по специальным ссылкам влиять на поведение NA;
• Поведение WV модулей NA в iOS и WV модулей NA в Android отличается во многих сценариях;
• Пользователи используют разные версии NA (особенно в iOS), разные версии NA имеют свои особенности.

Данная Библиотека:

• умеет собирать данные о NA, внутри которого она запущена;
• учитывает вышеуказанные «особенности»;
• предоставляет единый интрефейс для работы внутри NA разных версий, разных ОС.

Структура Библиотеки

Состоит из двух частей:

• серверная часть:
  • необходима, чтобы распарсить запрос от NA и сохранить данные в cookie для клиентской части;
  • реализована на Node.js;
    • стараемся поддерживать совместимость с различными Node.js фреймворками и веб-серверами;
    • обработку запросов с WV на других ЯП/технологиях придётся делать руками 🙂 (см. логику src/server/prepare-native-app-details-for-client.ts)
• клиентская часть:
  • предоставляет методы для работы WA внутри WB NA.

На клиентской стороне потребителям Библиотеки нужно использовать только экземпляр класса BridgeToNative. Класс проксирует все публичные методы Библиотеки из внутренних сервисов.

Проксируемые публичные методы не описаны по месту их реализации, описание находится в классе BridgeToNative (чтобы не повторяться). А все приватные методы описаны (если есть необходимость) в месте их реализации.

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

Установите:

npm i @alfalab/bridge-to-native

Используйте функции Библиотеки на стороне сервера (на примере Express)

import { isWebviewEnv, prepareNativeAppDetailsForClient } from '@alfalab/bridge-to-native/server';

//...

app.get('/my-ssr-route', (req, res) => {
    // B2N проверит, что запрос пришёл из WV окружения.
    // Можно не использовать, если обработчик обслуживает запросы только из WV.
    const isWebview = isWebviewEnv(req);

    if (isWebview) {
        // B2N соберёт из запроса детали о NA и установит cookie для клиента.
        prepareNativeAppDetailsForClient(req, (headerKey, headerValue) => {
            res.set({
                headerKey: headerValue,
            });
        });
    }

    // Что-то делаем ещё и отправляем ответ клиенту...
});

Инициализируйте основной класс B2N в клиентском коде

import { BridgeToNative } from '@alfalab/bridge-to-native/client';

// Лучше использовать один экземпляр-синглтон.
window.b2n = new BridgeToNative();

// ...

Используйте методы Библиотеки в клиентском коде

// ...
window.b2n.setTitle('Заголовок для верхней панели NA');
// ...
window.b2n.openInBrowser('https://ya.ru');
// ...

Навигация

NA при открытии экрана c WV вместе с областью для веб-контента отображает свои UI-элементы. Один из которых — кнопка «Назад» (BBtn), которая может работать, как «Назад» в Браузере. Чтобы синхронизировать работу BBtn с историей браузера, необходимо для навигации а рамках WA использовать следующие методы B2N:

• navigateClientSide
• navigateServerSide
• goBack
• goBackAFewStepsClientSide
• reload

Каждый метод содержит JSDoc c описанием назначения и ограничений.

Пример

// Только что открылось WV, находимся на /page-1,
// Если нажать BBtn, экран с WV будет закрыт.

window.b2n.navigateClientSide('/page-2');

// Находимся на /page-2,
// Если нажать на BBtn, она сработает как «Назад» в браузере, вернув на `/page-1`.

window.b2n.navigateClientSide('/page-3');

// Находимся на /page-3,
// Если нажать на BBtn, она сработает как «Назад» в браузере, вернув на `/page-2`.

window.b2n.goBack();

// Вернулись на /page-2,
// Если нажать на BBtn, она сработает как «Назад» в браузере, вернув на `/page-1`.

window.b2n.goBack();

// Вернулись на /page-1,
// Если нажать BBtn, экран с WV будет закрыт.

Проблематика server-side навигации в контексте работы WV NA

1. Особенности WV NA заставляют WA хранить состояние синхронизации с NA. При использовании server-side навигации это состояние теряется.

2. Также при переходе server-side навигацией целевое WA может быть недоступно по какой-либо причине. NA никак не обрабатывает такие ошибки, а веб в этот момент ничего не контролирует.

Что предлагает Библиотека

Из-за «второго пункта» использовать server-side навигацию не рекомендуется. Переход к другому WA лучше делать через открытие нового WV (см. метод openInNewWebview). Хотя делать это тоже нужно осторожно, т.к. каждое открытое WV утилизирует ресурсы устройства.

Также B2N предоставляет метод navigateServerSide для server-side навигации. Правда есть ограничения (см. описание метода). При этом «Второй пункт» не решить на стороне веба, надо иметь его ввиду.

Метод goBackAFewStepsClientSide нельзя использовать в контексте server-side навигации (см. описание метода).

При navigateServerSide библиотека переиспользует уже существующий query device_app_version, чтобы целевое WA могло восстановить appVersion даже если на следующем HTML-запросе не будет заголовка app-version. Исторически этот query приходит из iOS, но B2N сознательно не вводит для этого отдельный B2N-специфичный параметр и использует его как transport-поле и для Android.

Процесс релиза

Для выпуска новой версии библиотеки в npm необходимо создать GitHub Release. При этом нужно:

1. Указать тег, который отражает тип изменения: major, minor или patch.
2. Заполнить changelog в формате Markdown, описав изменения в разделах: FEATURES, BUGFIXES, BREAKING_CHANGES. Не используйте заголовки первого уровня при описании изменений, так как они используются для основных заголовков версии

После публикации GitHub Release автоматически запускается workflow, который:

• Обновляет версию в package.json согласно тегу.
• Обновляет CHANGELOG.md.
• Создает релизный Pull Request с этими изменениями со специальным тегом release

После мержа релизного PR запустится следующий workflow, который:

• Опубликует версию в npm
• Добавит архив с актуальными ассетами в созданный релиз. Таким образом ассеты с актуальным CHANGELOG.md будут лежать в архиве release-x.y.z.zip

---

Для выпуска beta-версии достаточно добавить в сообщение коммита строку deploy_beta. Выпущенная beta-версия будет автоматически опубликована с тегом beta. Выпущенную бета-версию можно посмотреть в разделе Actions в соответствующем workflow.