Разработка

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

Время чтения 9 минут

Автор: Максим Слепов

22 ноября 2019

Платформа 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:

Это удобно — многие типовые компоненты уже готовы, осталось только встроить их в структуру вашей страницы или 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

То есть фрейм с вашим приложением откроется примерно с похожим адресом:

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>
      </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 — это, по сути, удобный фронтенд для использования онлайн-сервиса оплаты с помощью Деньги VK. Для вызова платежной формы достаточно открыть платежное окно с помощью вызова в библиотеке VK Connect:

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

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

Что еще почитать:

cloud-native облачные платформы разработка приложений vkontakte