Создание интерактивного руководства по приложению

Команды поддержки часто испытывают трудности, когда им приходится работать с приложениями, которые они никогда не устанавливали. PDF-инструкции — плохое решение, потому что их никто не читает.

Я создал инструмент, который позволяет пользователям взаимодействовать с реальными скриншотами приложения прямо в браузере. Это создает ощущение использования настоящего телефона. Вы нажимаете на кнопку на скриншоте, и появляется следующий экран.

Как это работает

Для хранения изображений я использовал Firebase Storage, а для логики — чистый JavaScript. Я отказался от внешних библиотек, чтобы сохранить легкость приложения.

Секрет заключается в использовании процентных «хотспотов» (активных зон). Вместо фиксированных пикселей я определяю кликабельные области с помощью координат от 0 до 100. Это позволяет кнопкам оставаться на своих местах даже при изменении размера окна.

Система использует простой конечный автомат (state machine). Каждый экран содержит:

  • ID изображения
  • Список хотспотов
  • Целевой экран

Созданные мной инструменты

Измерять координаты на глаз — долго. Чтобы ускорить процесс, я разработал отдельный HTML-редактор.

  • Загрузите скриншот на canvas.
  • Перетащите мышь, чтобы нарисовать прямоугольник.
  • Редактор автоматически рассчитывает процентные координаты.
  • Привяжите область к другому экрану через выпадающий список.
  • Экспортируйте готовый объект прямо в свой код.

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

Ключевые технические уроки

  1. Безопасность Firebase: Не формируйте URL-адреса хранилища вручную. Используйте метод getDownloadURL из SDK. Он включает необходимый токен авторизации. Без него изображения не будут загружаться, при этом ошибка может не отобразиться.

  2. Исправление верстки: В макете с flex-direction: column задайте родителю явную высоту. Установите min-height: 0 для дочерних элементов. Это предотвратит схлопывание макета и проблемы с переполнением (overflow).

  3. Масштабирование: Используйте CSS-свойство transform: scale. Это позволяет изображению и хотспотам масштабироваться вместе, сохраняя пропорции независимо от размера экрана.

  4. Скорость: Поочередная загрузка URL-адресов создает задержки. Я реализовал кэширование в памяти и функцию фоновой предзагрузки. Все изображения загружаются параллельно при открытии модального окна. Благодаря этому навигация кажется мгновенной.

Результат

  • 20 экранов с полной навигацией.
  • 52 интерактивных хотспота.
  • Никаких полос прокрутки благодаря автомасштабированию.
  • Мгновенные переходы благодаря предзагрузке.

Source: https://dev.to/androve2k/building-an-interactive-app-guide-with-clickable-hotspots-on-real-screenshots-o9e