Первый чат на React Native с Talkentry: от установки до отправки сообщения

в 8:40, , рубрики: npm-пакет, ReactJS, talkentry, uikit

Для своих задач я искал открытую библиотеку чата на актуальном стеке React Native, которую можно развивать, не подстраивая приложение под накопленные ограничения чужого API. Меня интересовал не только готовый интерфейс: хотелось разделить состояние и отображение переписки, а также взаимодействие с API. Поэтому было решено создать собственную библиотеку для работы с чатами – Talkentry. Цель проекта: обеспечить общение пользователей внутри приложений, решить поставленные задачи и сделать библиотеку открытой для интеграций и вклада сторонних разработчиков.

Это первая статья о проекте, и начнём мы с воспроизводимого локального запуска. Возьмём специально подготовленный пример, поднимем API, откроем чат на Android-телефоне и проверим отправку сообщения. После этого разберём основные компоненты и границу между SDK и реальным backend. Предполагается поверхностное знакомство с компонентами библиотеки и получение среды для дальнейшей разработки.

Что будем запускать

Talkentry состоит из общего ядра и платформенных UI-пакетов; здесь нас интересует @talkentry/react-native с готовым экраном, провайдером сессии и хуками.(Документация React Native-пакета) Сервер сообщений, авторизация и постоянное offline-хранилище не входят в SDK: приложение подключает backend через контракт ChatAdapter. (Описание SDK)

Чтобы первый запуск не начинался с реализации backend контракта, воспользуемся отдельным репозиторием talkentry-example: в нём уже есть Expo-приложение, reference adapter, NestJS API и конфигурация PostgreSQL. Пакеты SDK устанавливаются из npm, поэтому клонировать исходники самой библиотеки рядом с примером не требуется. (Инструкция запуска примера)

Нужные ссылки собраны здесь. Не путайте исходники SDK с запускаемым приложением-примером:

Подготовка проекта к локальному запуску

В примере зафиксированы Node.js 24.22.1 и npm 11; для базы данных нужен Docker с Compose. Для выбранного здесь маршрута также подготовьте Android SDK и среду локальной сборки, описанную в руководстве Expo. (Локальная разработка с Expo) Будем использовать физический Android-телефон с разрешенной USB-отладкой и доступом к компьютеру по локальной сети.

Клонируем проект и установим зависимости из корня репозитория. Если используете nvm, перед установкой выполните nvm install и nvm use: они прочитают версию из .nvmrc.

Если собираетесь изучать или менять сам SDK, отдельно скачайте его исходники командой: git clone https://github.com/Talkentry/talkentry.git Для приведённого запуска это необязательный шаг: пример использует пакеты из npm, а не соседний checkout библиотеки.

Дальше из того же корня запускаем PostgreSQL и API. Эти команды предусмотрены скриптами примера; сервер работает на порту 3087. Не забудьте создать файл .env в каталоге ./server перед запуском.

npm run docker:up
npm run server

Не закрывайте терминал с сервером. В другом терминале проверьте его доступность:

curl --fail http://127.0.0.1:3087/health

В ответе проверяйте не только доступность HTTP: рабочее состояние обозначается полями status: “ok” и services.postgres: true; при ошибке базы обработчик возвращает status: “critical”. Если проверка не проходит, сначала разберитесь с журналом API, Docker и server/.env, а уже затем переходите к React Native.

Это локальный учебный сервер без пользовательской аутентификации: оба демонстрационных клиента работают с фиксированным user-1. Не публикуйте его в интернете и не используйте реальные переписки. Для первого запуска достаточно доверенной локальной сети и тестовых данных.

Запускаем React Native-приложение

В примере уже зафиксированы Expo, React Native и native-зависимости, поэтому первый запуск не будем совмещать с их ручным подбором. Для существующего приложения совместимость придётся проверить отдельно по peer dependencies выбранной версии пакета. (Манифест SDK 0.0.1)

Для воспроизводимого native-окружения выберем собственную development build. Expo описывает этот режим как приложение со своим набором native-модулей; одна только работа Metro не означает, что установленный клиент содержит всё необходимое. (Development builds в Expo)

Из нового терминала, оставив API работающим, выполните:

cd talkentry-example/apps/mobile
npx expo install expo-dev-client
npx expo run:android --device

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

npx expo start --dev-client

До разбора кода проверьте адрес API. В примере функция resolveTalkentryApiUrl() берёт адрес хоста из Expo и добавляет порт 3087; если адреса нет, она использует 10.0.2.2 на Android и localhost на остальных платформах. (Реализация определения адреса)

Браузер с открытым /health по LAN-адресу компьютера

Браузер с открытым /health по LAN-адресу компьютера

Откройте в браузере телефона http://<LAN_IP>:3087/health и проверьте те же поля состояния базы. Не подставляйте localhost и не считайте доступный Metro доказательством работоспособности API. Если запрос не проходит, проверьте общую сеть и firewall; при нестандартной сетевой схеме задайте доступный телефону baseUrl адаптера явно.

После установки откройте приложение и дождитесь истории. Затем отправьте сообщение с уникальным текстом, перезапустите приложение и найдите его снова: это отдельная проверка сохранения, а не только появления пузыря на экране.

Запущенный Talkentry, загруженная история чата demo

Запущенный Talkentry, загруженная история чата demo

Какие компоненты нужны для одного экрана

Полное демо содержит дополнительное оформление, обработчик копирования и выбор изображения; для текстового чата эти прикладные части можно временно убрать. (Исходный экран примера) Ниже минимальная версия, которой можно заменить apps/mobile/App.tsx внутри уже установленного проекта. Импорты адаптера и определения адреса остаются локальными: это файлы приложения-примера, а не скрытые экспорты npm-пакета.

import { Chat, TalkentryProvider } from '@talkentry/react-native';
import { KeyboardProvider } from 'react-native-keyboard-controller';
import {
  SafeAreaProvider,
  SafeAreaView,
} from 'react-native-safe-area-context';

import {
  appendNativeUpload,
  TalkentryServerAdapter,
} from '../../adapter/native';
import { resolveTalkentryApiUrl } from './apiUrl';

// Один экземпляр адаптера для этой демонстрационной сессии.
const adapter = new TalkentryServerAdapter({
  baseUrl: resolveTalkentryApiUrl(),
  appendUpload: appendNativeUpload,
});

export default function App() {
  return (
    <SafeAreaProvider>
      <KeyboardProvider>
        <SafeAreaView
          style={{ flex: 1 }}
          edges={['top', 'left', 'right']}
        >
          <TalkentryProvider
            adapter={adapter}
            chatId="demo"
            currentUserId="user-1"
            scopeKey="local-demo:user-1:session-1"
          >
            <Chat
              locale="en"
              messageListProps={{ isActive: true }}
            />
          </TalkentryProvider>
        </SafeAreaView>
      </KeyboardProvider>
    </SafeAreaProvider>
  );
}

В минимальном варианте компоненты выполняют разные задачи. Не нужно параллельно заводить массив сообщений в React state и вручную создавать вторую сессию для того же экрана:

  • Chat: готовый интерфейс списка сообщений и поля ввода. (Native guide)

  • TalkentryProvider: связывает дочерние компоненты с сессией и переданным адаптером. (Подключение SDK)

  • KeyboardProvider и SafeAreaProvider: рекомендованные внешние обёртки для native-экрана. (Требования интеграции)

  • TalkentryServerAdapter: реализация транспорта из example-проекта; это не обязательный backend всей библиотеки. (Адаптер примера)

У провайдера три идентификатора с разным назначением: chatId выбирает переписку, currentUserId задаёт текущего пользователя, а scopeKey участвует в идентичности сессии и должен меняться при смене tenant или сеанса авторизации. Это не механизм авторизации и не замена серверной проверке доступа. В демо ключ фиксирован намеренно; в настоящем приложении свяжите его с жизненным циклом входа пользователя.

Экземпляр адаптера вынесен за компонент, чтобы оставаться стабильным между рендерами. Для приложения со сменой учётных записей выбирайте подходящий жизненный цикл, а не копируйте глобальный экземпляр без учёта авторизации.

isActive: true подходит для единственного открытого экрана; с навигацией передавайте реальную активность, чтобы скрытый чат не инициировал навигацию и прочтение. (Активность экрана) Локаль в примере оставлена en: именно она документирована в native API.

Что понадобится от реального backend

Провайдер не знает адресов вашего API и не превращает переданный currentUserId в подтверждённую identity: инфраструктура подключается через ChatAdapter. Для собственной интеграции стоит начать с такого разделения ответственности:

  • Приложение и адаптер: получить credentials, выполнить запросы и преобразовать ответы в контракт SDK.

  • Сервер: проверить пользователя и доступ к переписке, валидировать входные данные и сохранять сообщения.

  • История и события: согласовать пагинацию, идентификаторы, порядок обновлений и поведение после разрыва соединения.

  • Дополнительные функции: отдельно определить контракты вложений, прочтений и других возможностей, которые действительно нужны продукту.

Необязательно повторять NestJS, PostgreSQL и Socket.IO: это выбор reference-примера, а не обязательный стек SDK. (Server Adapter) Важно реализовать согласованный контракт, а не только вернуть подходящий JSON для первого экрана.

Первый чат на React Native с Talkentry: от установки до отправки сообщения - 3

Как проходят история и отправка

При старте сессия запрашивает последнюю страницу через loadLatest и подключает subscribe; более ранние сообщения загружаются через loadBefore. (Контракт истории) В reference adapter запросы идут по HTTP, а события приходят через Socket.IO. (Реализация транспорта)

Отправка оптимистическая: строка появляется локально до серверного подтверждения. (Поведение SDK) Сервер сохраняет сообщение и публикует события, а сессия согласует HTTP-ответ и realtime-эхо, связывая локальную и серверную записи через идентификаторы. (Отправка на сервере, контракт SDK) Порядок их получения клиентом не стоит считать фиксированным; появившийся пузырь сам по себе не подтверждает сохранение.

Первый чат на React Native с Talkentry: от установки до отправки сообщения - 4

После повторного соединения reference adapter передаёт history.invalidated, чтобы сессия не полагалась только на новые live-события. (Обработка reconnect) Ядро пытается восстановить состояние через журнал событий, если доступны курсор и loadEvents; иначе использует допустимую дозагрузку либо перезагрузку последней страницы. (Алгоритм восстановления) Это не обещание получить каждое пропущенное событие и не постоянная offline-очередь.

Первый чат на React Native с Talkentry: от установки до отправки сообщения - 5

Для ручной проверки откройте второй клиент, например web-демо командой npm run web из корня репозитория. Оба штатных клиента используют user-1, поэтому такой тест проверяет обмен событиями между клиентами, а не авторизацию двух разных участников. Дополнительно проверьте подгрузку истории, возврат после отключения сети и поведение списка при открытии клавиатуры; не считайте эти сценарии пройденными только потому, что приложение собралось.

Что дальше

Talkentry только начинает развиваться: API ещё может меняться, а поведение на устройствах и готовность production-интеграции требуют отдельной приёмки. Наш следующий ориентир: расширять функциональность и улучшать существующие сценарии с учётом реальных интеграций, а не объявлять библиотеку законченной после первого демо.

Если встретите проблему, пожалуйста, создайте issue в репозитории Talkentry. Приложите версии пакетов, модель устройства и ОС, шаги воспроизведения, ожидаемый и фактический результат; по возможности добавьте минимальный пример без персональных данных и секретов. Особенно полезна обратная связь о первом запуске, поведении чата и том, насколько удобно подключать собственный backend.

Спасибо за интерес к проекту и за любой будущий вклад: отчёт об ошибке, уточнение документации, предложение или код. Надеюсь, этот пример поможет начать собственную интеграцию, а обсуждение сделает библиотеку полезнее для других разработчиков.

Автор: Ale0d

Источник

Поделиться

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js