Разработка приложений в VK mini apps

Почему надо смотреть в сторону разработки приложений для работы в VK? У меня за спиной много лет фронтенд-разработки для массовых сервисов, и то, что сейчас предлагает разработчику социальная сеть «ВКонтакте» — быстрый и эффективный способ построить еще один канал коммуникации с действительно большой аудиторией. Ниже расскажу, в чем идея VK mini apps, какие технологии использовать при разработке приложения и на что стоит обратить внимание.



Первоначальная публикация статьи в блоге Mail.ru Cloud Solutions: https://mcs.mail.ru/blog/razrabotka-prilozhenij-v-vk-mini-apps

Платформа VK mini apps

«ВКонтакте» предоставляет сторонним разработчикам возможность писать веб-приложения и размещать их в каталоге приложений и/или продвигать внутри сети. Пользователям приложений не нужно скачивать отдельные нативные приложения из Google Play/App Store, функционал выбранного приложения доступен внутри пользовательской сессии основного приложения во «ВКонтакте» или через браузер, на сайте соцсети. В социальной сети есть подробная инструкция о том, как начать работу на платформе VK mini apps.

Инфраструктура приложения VK mini app

Приложение VK mini app представляет собой обычный веб-ресурс, располагаемый по определенному адресу. Его мы должны разместить в «Панели управления приложением» социальной сети.

«ВКонтакте» позволяет разместить три версии приложения:

• для мобильных клиентов — то есть для открытия в нативном приложении «ВКонтакте»;
• десктопный вариант — vk.com в браузере;
• вариант для браузеров в мобильных телефонах (https://m.vk.com).

При размещении вы также можете включить «Режим разработки». Он позволяет пользователям «ВКонтакте», назначенным в качестве администраторов приложения, использовать для тестирования каждой из трех витрин отдельный адрес. То есть открывая приложение, обычный пользователь увидит то, что расположено по условном адресу yourapp.com, а администратор — test.yourapp.com.

Ваш веб-ресурс встраивается в приложение «ВКонтакте» через обычное WebView, при открытии с десктопа — через iFrame. Поэтому необходимо держать в уме, что часть функционала JavaScript может быть недоступна, необходимо тщательное тестирование.

После тестирования веб-приложения на разных устройствах его можно отправлять на модерацию, чтобы оно могло быть размещено в каталоге. Заявка на модерацию отправляется из «Панели управления приложением». Объявленный «ВКонтакте» срок модерации — 7 дней. Выкладки новых приложений (сервисов по терминологии «ВКонтакте») происходят раз в неделю по четвергам.

Есть подробная памятка о том, как создать правильное приложение. Рекомендую внимательно свериться с ней, прежде чем отдавать приложение на модерацию.

Разработка приложения VK mini app

Итак, приложение VK Mini Apps — это, по сути, обычное веб-приложение, которое встраивается в платформу посредством iFrame или WebView. Поэтому выбор технологий, на котором оно будет написано, за вами.

Однако для разработки фронтенда «ВКонтакте» рекомендует собственную библиотеку готовых компонентов VK UI, выполненную на React:

Это удобно — многие типовые компоненты уже готовы, осталось только встроить их в структуру вашей страницы или SPA.

Компоненты уже стилизованы согласно styleguide «ВКонтакте» — пользователю будет привычнее и удобнее работать с теми элементами управления и интерактивом, к которым он уже привык, находясь внутри социальной сети.

«ВКонтакте» не требует от разработчика следования какой бы то ни было жесткой архитектуре построения фронтенда — мы берем только то, что нужно, и модифицируем компоненты так, как нужно. Например, вы всегда сможете добавить глупому view-компоненту свой класс, свой обработчик событий, сделать вложенные компоненты любой глубины и так далее.
Существует достаточно подробная (правда, не совсем полная) документация по VKUI. Исходный код на GitHub: https://github.com/VKCOM/VKUI. Соответственно, максимально простая установка:

npm i —save-dev @vkontakte/vkui

Обязательно нужно поставить следующий метатег в head верстки страницы вашего приложения, иначе на устройствах с iOS будет неправильно отображаться нативная навигация «ВКонтакте»:

<meta content=»width=device-width, initial-scale=1, shrink-to-fit=no, user-scalable=no, viewport-fit=cover» name=»viewport» />

Далее нам нужно просто встроить React-приложение на страницу.

Параметры открытия приложения

«ВКонтакте» сам добавляет параметры запуска к адресной строке, по которой открывается ваше приложение. Их список следующий: vk_user_id, vk_app_id, vk_are_notifications_enabled, vk_language, vk_ref, vk_access_token_settings, vk_group_id, vk_viewer_group_role, vk_platform, vk_is_favorite, sign. То есть фрейм с вашим приложением откроется примерно с похожим адресом: youvkapp.ru/?vk_access_token_settings=notify&vk_app_id=888888&vk_are_notifications_enabled=1&vk_is_app_user=1&vk_is_favorite=1&vk_language=ru&vk_platform=desktop_web&vk_ref=other&vk_user_id=111111&sign=fsdfsdgfgfiuoitu8345u34j

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

Дополнительные параметры в этот список «ВКонтакте» на ноябрь 2019 года включать не планирует. Однако в url можно передать произвольный хэш, например: youvkapp.ru#custom_param

Роутинг

Если в приложении больше одного экрана (я думаю, это как раз ваш случай), нужен переход между экранами. За показ того или иного экрана отвечает state нашего React-приложения. Что касается организации View, то «ВКонтакте» предлагает два способа: смена активного компонента VKUI View и VKUI Panel.

Каждый View отвечает за свой пользовательский сценарий: основной, дополнительный, вызов справочников, страницы поиска и другие. Внутри View содержится свой набор Panel — это конкретные шаги (экраны) в пользовательском сценарии. Абстрактно это выглядит так:

import {Root, View, Panel} from ‘@vkontakte/vkui’;
<Root activeView={this.state.views.activeView}>
   <View id=»main» activePanel={this.state.views.main.activePanel}>
      <Panel id=»step-1″>
         …
      </Panel>
      <Panel id=»step-2″>
         …
      </Panel>
   </View>
   <View id=»search»>
      <Panel id=»search-panel»>
         …
      </Panel>
   </View>
   <View id=»info» activePanel={this.state.views.info.activePanel}>
      <Panel id=»oferta»>
         …
      </Panel>
      <Panel id=»conditions»>
         …
      </Panel>
      <Panel id=»about»>
         …
      </Panel>
   </View>
</Root>

В state в activePanel мы прописываем id того элемента, который нужно показать.

Верстка и компоненты

Теперь можно посмотреть типичную страницу внутри Panel, созданную с помощью компонентов VK UI.

Библиотека VK UI предоставляет практически полный набор компонентов, необходимых для построения интерактивного приложения: всевозможные элементы форм, попапы, стилизованные алерты, галереи, панели навигации, спиннеры, аватары, футеры и так далее.

import {
   Button,
   Div,
   FormLayout,
   Input,
   Panel,
   PanelHeader,
   PanelHeaderBack,
   Search,
   View
} from "@vkontakte/vkui";
import Icon36Done from "@vkontakte/icons/dist/36/done";
import CustomTextarea from "./YourComponents/CustomTextarea";

render() {
   return (
      <div>
         <PanelHeader
            left={<PanelHeaderBack onClick={() => {this.Actions.historyBack()}} />}
         >App Title</PanelHeader>
         <Icon36Done width={48} height={48} />
         <Div>
            <h1>This is the first page</h1>
            <p className="page-hint">You can do some interaction here</p>
         </Div>
         <FormLayout>
            <Input
               type="text"
               defaultValue=""
               placeholder="Enter your name"
               className="active"
            />
            <CustomTextarea
               name="textarea1"
               className="custom"
               disabled={this.state.blocks.textarea.disabled}
               value={this.state.userData.textarea}
            />
            <Button
               size="xl"
               level="secondary"
            >Submit</Button>
         </FormLayout>
         <Search
            value={this.state.search.text}
            onChange={this.onSearch}
         />
      </div>
   )
}

Как видно, появился ещё один пакет vkontakte:

npm i —save-dev @vkontakte/icons

Можно воспользоваться удобным менеджером по подбору нужной иконки.

Основное правило — правильно использовать компонент либо собственную верстку шапки. В правой части шапки нативное приложение «ВКонтакте» размещает кнопки управления.



Кастомный блок:

import {
   Textarea
} from «@vkontakte/vkui»;

export default class CustomTextarea extends React.Component {
   render() {
      return (
         <div className=»form-group custom_textarea»>
            <div className=»FormLayout__row-top»>Custom textarea is here</div>
               <Textarea
                  disabled={this.props.disabled}
                  name={name}
                  id={name}
                  onChange={(e) => this.bindData(e, this.props.name)}
                  value={this.props.value}
                  className={this.props.className}
               />
            </div>
         </div>
      );
   }
}

Стоит обратить внимание: «ВКонтакте» заявляет, что компоненты могут отображаться на десктопах не совсем адекватно. Однако их можно стилизовать, добавляя свои css-правила. Например, так была стилизована анимация переходов между панелями в одном приложении:

.desktop_web {
   .View__panel—prev {
      max-width: 458px !important;
      margin: 0 auto;
      left: calc(50% — 230px) !important;
      -webkit-animation: root-android-animation-hide-back 3s cubic-bezier(.4, 0, .2, 1);
      animation: root-android-animation-hide-back 3s cubic-bezier(.4, 0, .2, 1);
   }
   .View__panel—next {
      max-width: 460px !important;
      left: calc(50% — 230px) !important;
   }
}

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

Библиотека VK Connect

Библиотека VK Connect предоставляет доступ к широким возможностям как самой сети «ВКонтакте», так и к возможностям устройства, если мы работаем из-под мобильного приложения. Для ее подключения нужно установить пакет vkontakte/vk-connect: npm i —save-dev vkontakte/vk-connect.

Среди многочисленных возможностей VK Connect — сканирование QR-кода, получение геопозиции, вызов карточки контактов. Также есть широкие возможности по использованию возможностей соцсети: включение-выключение уведомлений, публикация записей на стене, авторизация сообщества, подписка на сообщения. Их нужно использовать с умом: например, существует ограничение на количество уведомлений — не более одного в сутки. Есть отдельные рекомендации по уведомлениям. Полный список возможностей представлен в документации.

Чтобы наше приложение вообще начало работу, нужно сначала выполнить инициализацию:

import connect from ‘@vkontakte/vk-connect’;
connect.send(«VKWebAppInit», {});

Все дальнейшее взаимодействие с библиотекой происходит похожим образом. Методом connect.send вызываем нужное действие и слушаем ответы. Для этого мы должны подписаться на события:

connect.subscribe((e) => {
   switch (e.detail.type) {
      case «VKWebAppGetUserInfoResult» :
         this.bindConnectUserData(e.detail.data);
         break;
   }
});

В объекте detail возвращается type — название типа события, ответ на которое мы ждем, и data — набор данных. В примере выше мы слушаем ответ на запрос connect.send(«VKWebAppGetUserInfo», {}), который должен вернуть данные о пользователе приложения: имя, пол, дату рождения, место проживания, ссылку на картинку аватара в соцсети.

«ВКонтакте» не гарантирует поддержку всех событий на всех устройствах (iOS, Android, Web), поэтому лучше делать проверку такой поддержки перед исполнением кода:

if (connect.supports(«VKWebAppGetUserInfo»)) …

VK Connect также обеспечивает поддержку запросов к API VK, если нужно что-то большее, чем может предоставить сама библиотека VK Connect:

connect.send(«VKWebAppCallAPIMethod», {«method»: «users.get», «request_id»: «your_unique_req_id», «params»: {«user_ids»: «1», «v»:»5.103″, «access_token»:»your_token»}});

VK Pay

VK Pay — это, по сути, удобный фронтенд для использования онлайн-сервиса оплаты с помощью Деньги Mail.Ru. Для вызова платежной формы достаточно открыть платежное окно с помощью вызова в библиотеке VK Connect:

connect.send(«VKWebAppOpenPayForm», {«app_id»: 888888, «action»: «pay-to-service», «params»: {}});

Таким образом, можно продавать ваши услуги и товары, используя внутреннее платежное средство в сети «ВКонтакте». Подробнее в официальной документации.