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

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

Сокращения, используемые в 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 навигации (см. описание метода).