Программист Максим Слепов

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

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

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

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

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

• для мобильных клиентов — то есть для открытия в нативном приложении "ВКонтакте";
• десктопный вариант — https://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:

1. Это удобно — многие типовые компоненты уже готовы, осталось только встроить их в структуру вашей страницы или SPA.
2. Компоненты уже стилизованы согласно styleguide "ВКонтакте" — пользователю будет привычнее и удобнее работать с теми элементами управления и интерактивом, к которым он уже привык, находясь внутри социальной сети.
3. "ВКонтакте" не требует от разработчика следования какой бы то ни было жесткой архитектуре построения фронтенда — мы берем только то, что нужно, и модифицируем компоненты так, как нужно. Например, вы всегда сможете добавить глупому 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

То есть фрейм с вашим приложением откроется примерно с похожим адресом: https://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 можно передать произвольный хэш, например https://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>
    );
  }
}

Стоит обратить внимание: "ВКонтакте" заявляет, что компоненты могут отображаться на десктопах не совсем адекватно. Однако их можно стилизовать, добавляя свои 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 (npm i —save-dev @vkontakte/vk-connect) предоставляет доступ к широким возможностям как самой сети "ВКонтакте", так и к возможностям устройства, если мы работаем из-под мобильного приложения. Для ее подключения нужно установить пакет @vkontakte/vk-connect, используя npm.

Среди многочисленных возможностей 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": {}});

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