VK Mini Apps
VK Mini Apps – это платформа для создания мини-приложений, которые работают внутри ВКонтакте. На этой платформе можно создать продукт любого масштаба – от лендинга до сложного сервиса с множеством функций. Вы также можете перенести ваше веб-приложение на платформу, чтобы получить доступ к огромной аудитории VK Mini Apps и новым возможностям монетизации.
Как превратить веб-приложение в мини-приложение
В этой статье поделюсь пошаговой инструкцией о том, как превратить любое веб-приложение в сервис на примере планировщика задач.
Прежде всего, учитывайте, что мини-приложения на VK Mini Apps – это одностраничные веб-приложения, встраиваемые в платформу с помощью iFrame или WebView. Для разработки вам понадобятся знания JavaScript, HTML и CSS. Рекомендуется использовать UI-фреймворк, такой как React JS, который значительно упрощает процесс разработки.
Получение доступа к аудитории и монетизации
VK Mini Apps имеет огромную аудиторию, унаследованную от ВКонтакте. После прохождения модерации и попадания в каталог платформы, вы можете получить бесплатный трафик для своих приложений. Кроме того, если ваше приложение понравится пользователям, оно может быть отобрано для фичеринга и попасть в тематическую подборку на платформе, что существенно увеличит трафик.
Пример работы с мини-приложениями на VK Mini Apps
В этой статье я демонстрирую процесс превращения веб-приложения (написанного на React) в мини-приложение для VK Mini Apps с помощью планировщика задач. Для этого мы предоставляем готовое приложение-планировщик (TODO List), которое можно оформить как мини-приложение.
Полезные ссылки
- Документация по React JS
- Руководство для новичков по React JS
- Репозиторий приложения-планировщика (TODO List)
Следуйте инструкциям и начните создавать собственные мини-приложения на VK Mini Apps уже сегодня!
### Получение и настройка проекта
Сначала клонируйте репозиторий с готовым планировщиком и установите зависимости:
git clone <repository_url>
cd <repository_directory>
npm install
Структура демонстрационного приложения простая:
├── App
│ ├── App.jsx
│ ├── defaultData.json
│ ├── index.js
│ └── styles.css
├── TodoForm
│ ├── TodoForm.jsx
│ ├── index.js
│ └── styles.css
├── TodoItem
│ ├── TodoItem.jsx
│ ├── index.js
│ └── styles.css
└── index.jsx
### Главный компонент страницы (App.jsx):
Главный компонент страницы (App.jsx) содержит компоненты TodoForm и TodoItem.
### Компонент TodoForm:
Компонент TodoForm содержит форму создания новой задачи. Через обратный вызов сообщает о намерении добавить её в список.
### Компонент TodoItem:
Компонент TodoItem содержит отрисовку сущности одного элемента списка. Каждый такой элемент умеет через обратный вызов сообщать о намерениях.
### Интерфейс приложения:
Интерфейс приложения изображен на скриншоте. После выполнения всех шагов вы получите полноценное мини-приложение на платформе VK Mini Apps.
### VK Bridge
VK Bridge — библиотека для взаимодействия со средой ВКонтакте. Позволяет выполнение запросов к API ВКонтакте и получение информации о пользователе, устройстве и других данных.
Для установки библиотеки выполните команду:
npm install /vk-bridge
### VKWebAppInit и инициализация
Необходимо вызвать событие инициализации VKWebAppInit в начале кода. Это обязательный шаг для корректной работы мини-приложения.
Импортируйте модуль VK Bridge и инициализируйте мини-приложение.
### Проверка запуска мини-приложения
Для запуска мини-приложения выполните команду `npm run start`. Приложение будет доступно по адресу https://localhost:3000. Укажите этот адрес для iFrame мини-приложения и проверьте его работу.
Настройте https://localhost:3000 в настройках вашего приложения в портале разработчиков VK.
Откройте мини-приложение на десктопной и мобильной версиях: vk.com/appXXX и m.vk.com/appXXX, где XXX - ID вашего мини-приложения. Обязательно проверьте работу на мобильной версии, так как большинство пользователей открывают мини-приложения со смартфонов.
Пока не пробуйте открыть мини-приложение именно с мобильного устройства (ни в клиенте, ни по адресу m.vk.com/appXXX), наверняка оно находится в другой сети. Но даже если в той же самой, могут возникнуть проблемы из-за брандмауэра. Ниже я покажу, как настроить просмотр локального мини-приложения с удалённого устройства с помощью туннелирования.
Методы VK Bridge и запоминание состояния приложения
Вернёмся к разработке проекта.
Заметим, что любые изменения, внесённые в мини-приложение, теряются при повторном заходе в него. Решить эту проблему можно по-разному. Например, поднять свой бэкенд и подготовить методы для CRUD-операций с TODO-списком. Но в случае с мини-приложениями ВКонтакте можно обойтись клиентской разработкой.
Для этого рассмотрим несколько методов VK Bridge из секции Storage.
💡 Вы можете экспериментировать с любыми методами VK Bridge в песочнице.
Метод VKWebAppStorageSet позволяет закрепить за пользователем некую информацию в рамках конкретного мини-приложения, а метод VKWebAppStorageGet — получить её. У других пользователей не будет к ней доступа. Этого вполне достаточно, чтобы сделать механизм сохранения состояния списка задач.
Определите ключ STORAGE_KEY, по которому в VK Storage будет храниться JSON с актуальным состоянием. При монтировании корневого компонента запросите данные по этому ключу и актуализируйте состояние todos. Обратите внимание, что VK Storage умеет хранить только строковые данные, поэтому при записи состояние нужно сериализовать (JSON.stringify), а при чтении — десериализовать (JSON.parse).
У новых пользователей может выскочить ошибка парсинга, потому что значение в VK Storage — по умолчанию пустая строка. Чтобы этого не происходило, отлавливайте ошибку с помощью try-catch и показывайте пользователю приложение по умолчанию.
В качестве самостоятельного задания с помощью флага loaded отрисуйте особое состояние при загрузке списка задач.
Теперь разберёмся, как записывать данные в VK Storage. Для примера, не углубляясь в безопасную архитектуру, воспользуемся useEffect из React для изменения состояния todos. Только будьте осторожнее с генерацией сетевых запросов в useEffect в рабочих проектах: можно сгенерировать много избыточных параллельных запросов, наткнуться на flood control или поймать баги из-за гонки асинхронных операций. Предлагаю вам самостоятельно придумать более безопасный механизм отправки запросов. Например, воспользоваться троттлингом.
Сейчас у вас есть приложение, которое сохраняет список задач и их состояние между сессиями. Вы можете что-нибудь делать со списком, и после перезагрузки страницы изменения не потеряются.
🦥 Введите команду, чтобы посмотреть финальный результат этого шага:
git checkout tags/step-3
💡 Обратите внимание, что теперь веб-приложение не будет корректно работать в отдельной вкладке по адресу localhost:3000. Дело в том, что VK Bridge работает только внутри iFrame или WebView.
VKUI
Подключение стиля VKUI к вашему приложению VK Mini Apps
Наше приложение-планировщик пока что не может похвастаться качественным дизайном и отличается по стилю от экосистемы ВКонтакте. Кому-то это может показаться не таким уж и важным, но однородность вашего мини-приложения с экосистемой ВКонтакте — это не только очень важно, но и просто. Даже если вы намерены использовать необычный или уникальный дизайн, помните: пользователь будет интуитивно искать нужные ему кнопки именно там, где они расположены ВКонтакте — это дело привычки. А аудиторию лучше не путать, она любит, когда всё просто и понятно.
Чтобы поддерживать однородность стиля интерфейсов, ВКонтакте предлагает открытую библиотеку компонентов (VKUI) и иконок (VK Icons). С ними быстрее разрабатывать, нужно меньше кода.
VKUI – Библиотека React-компонентов
VKUI — это набор React-компонентов, которые адаптированы под мобильную (Android и iOS) и десктопную среду. Библиотека основана на дизайн-системе ВКонтакте и содержит готовые компоненты, которые будут нативно выглядеть на любом устройстве.
Подключение
- Ознакомьтесь с разделом Быстрый старт из документации VKUI и выполните описанные шаги.
- Сначала установите зависимости.
- Добавьте тег viewport для корректного отображения интерфейса на безрамочных смартфонах.
- Соберите базовый app shell для VKUI.
Пример кода
<View activePanel=main>
<Panel id=main>
<PanelHeader>Example</PanelHeader>
<Group>
<CellButton>Button</CellButton>
</Group>
</Panel>
</View>
Компоненты View и Panel помогут разобраться с навигацией между разными экранами.
Переход на VKUI
Теперь заменим старые компоненты нашего приложения на компоненты VKUI. Для этого в файле App.tsx:
import { View, Panel } from @vkontakte/vkui;
Результат будет семантичным кодом, не нагруженным особенностями реализации вёрстки. Продолжим рефакторинг в файлах TodoForm и TodoItem, используя компоненты VKUI, такие как Input, Button и Cell.
VK Tunnel
Для проверки работоспособности приложения на мобильных устройствах, VK рекомендует использовать VK Tunnel. Это утилита для VK Mini Apps, которая позволяет отладить локальное мини-приложение на мобильном устройстве до сборки и публикации проекта. Можно использовать VK Tunnel для демонстрации результатов коллегам и друзьям на разных устройствах.
Слева направо: Android — светлая и тёмная тема, iOS — тёмная тема.
git checkout tags/step-4
Сначала установите пакет VK Tunnel:
Затем в файл package.json добавьте такой скрипт:
"tunnel": "vk-tunnel –insecure=1 –http-protocol=https –ws-protocol=wss –host=0.0.0.0 –port=3000"
Создайте файл vk-tunnel-config.json, он будет отвечать за автоматическую подстановку туннель-адреса в URL для разработчика в настройках мини-приложения (вместо 123456 нужно поставить ID вашего мини-приложения):
Более подробная инструкция есть в документации.
Теперь убедитесь, что у вас запущен локальный сервер: npm run start. И после этого проверьте работу туннеля: npm run tunnel. В первый раз потребуется авторизоваться — следуйте инструкциям, которые появятся в консоли. После этого можно убедиться, что локальная версия мини-приложения запускается в официальном клиенте ВКонтакте на мобильном устройстве.
git checkout tags/step-5
Eruda
Обратите внимание, что в настройках мини-приложения есть возможность включить консоль Eruda. Это может быть полезно для отладки кода, например когда вы проверяете работу вашего мини-приложения не с компьютера, где есть доступ к инструментам разработчика, а с мобильного устройства.
Подробнее об инструментах отладки читайте на портале для разработчиков.
VK Mini Apps Deploy
К этому моменту вы уже отладили своё мини-приложение. Пора опубликовать его. Вы можете выбрать для этого любой хостинг и любой домен, как и для обычного веб-приложения. Главное, укажите правильный URL в настройках мини-приложения. Отметим, что не все начинающие разработчики умеют настраивать хостинг для статики. К тому же не всегда это можно сделать бесплатно, получив при этом высокую скорость доставки файлов. Поэтому ВКонтакте предоставляет инструмент, который берёт решение этих вопросов на себя — VK Mini Apps Deploy. Он позволяет опубликовать статику вашего фронтенд-приложения буквально одной командой. Это легко, бесплатно и быстро. ВКонтакте использует кеширование, сжатие и технологию CDN, чтобы доставлять статику до пользователей за максимально короткое время.
Установите пакет VK Mini Apps Deploy:
В файл package.json добавьте скрипты:
"predeploy": "npm run build", "deploy": "vk-miniapps-deploy"
Создайте файл vk-hosting-config.json, он будет отвечать за автоматическую подстановку адреса вашей статики в URL для пользователей в настройках мини-приложения (вместо 123456 нужно поставить ID вашего мини-приложения):
Документация и инструкции по использованию VK Mini Apps Deploy лежат здесь.
Теперь можно развернуть ваше мини-приложение: npm run deploy. Система попросит подтвердить публикацию собранной статики для пользователей мини-приложения. Также в первый раз может потребоваться авторизация. Следуйте инструкциям, которые появляются в консоли.
После этого проверьте в настройках мини-приложения, что оно всем доступно для просмотра. И убедитесь, что TODO List запускается на всех платформах не только у разработчиков, но и у внешних пользователей.
git checkout tags/step-6
Заключение
Поздравляю, вы портировали своё стороннее веб-приложение на платформу VK Mini Apps!
Кроме описанных в начале статьи преимуществ у VK Mini Apps есть и другие, часто неочевидные.
И напомню ещё раз про каталог — эта фича платформы способна кратно повысить доходность мини-приложений. Как в него попасть, мы расскажем в одной из новых статей.
Полезные материалы
P.S. Опытные разработчики, уже создававшие мини-приложения для VK Mini Apps, расскажите, что вам больше всего помогало на первых порах?