ДокументацияAPIСообществоСоздать приложение
Войти

Голоса

Пользователи мини-приложений могут обменивать свои голоса на виртуальные ценности, например внутреннюю валюту или дополнительные функции.

Событие VK Bridge

VKWebAppShowOrderBox

Платформы

Android | Mobile Web | Web

Для кого этот раздел

Этот раздел для разработчиков мини-приложений, которые хотят продавать пользователям виртуальные ценности за голоса. Если вы уже используете VK Bridge и знаете, что такое Платёжный API, переходите сразу к разделу Разработка.

Если вы разрабатываете игру, вам нужен раздел Игровые покупки.

Подготовка

Перед тем как приступить к разработке, подключите библиотеку VK Bridge.

Продажа виртуальных ценностей, а значит и оплата голосами запрещена в приложении ВКонтакте для iOS.

Разработка

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

Для этого приложение должно вызвать событие VKWebAppShowOrderBox.

JavaScriptbridge.send("VKWebAppShowOrderBox", {type:"item", item:"item_id_123"});

Разработчику не нужно самостоятельно создавать элементы интерфейса, достаточно передать ВКонтакте описание виртуальной ценности.

Событие VKWebAppShowOrderBox

В общем случае обмен информацией между приложением и ВКонтакте выглядит так:

  1. 1.
    Приложение вызывает событие VKWebAppShowOrderBox.
  2. 2.
    ВКонтакте отправляет приложению платёжное уведомление, описанное в разделе Получение информации о товаре. ВКонтакте ожидает в ответе описание виртуальной ценности либо код и описание ошибки.
  3. 3.
    ВКонтакте показывает пользователю диалоговое окно. Пользователь подтверждает оплату голосами.
  4. 4.
    ВКонтакте отправляет приложению платёжное уведомление, которое описано в разделе Изменение статуса заказа с идентификатором заказа order_id и ожидает в ответе идентификатор заказа order_id либо код и описание ошибки.
  5. 5.
    ВКонтакте переводит голоса пользователя на счёт приложения, как только получит order_id в ответ на платёжное уведомление.

Результирующие события

Когда ВКонтакте закрывает диалоговое окно, приложение получает результирующее событие VKWebAppShowOrderBoxResult или VKWebAppShowOrderBoxFailed.

JavaScript// Подписка на событие-результат. bridge.subscribe((e) => { if(e.type == ‘VKWebAppShowOrderBoxResult’) { console.log(e.data.status); }});

Порядок обработки ответов на уведомление об изменении статуса заказа сейчас зависит от платформы:

  • •
    Web. Приложение получает событие VKWebAppShowOrderBoxResult только после обработки ответа на уведомление. Если приложение отправляет код ошибки в ответе на платёжное уведомление, ВКонтакте отправляет событие VKWebAppShowOrderBoxFailed.
  • •
    Android и Mobile Web. Приложение всегда получает VKWebAppShowOrderBoxResult сразу, как только пользователь подтвердит оплату голосами. ВКонтакте ожидает ответ на уведомление, но не отправляет событие VKWebAppShowOrderBoxFailed, даже если приложение вернёт код ошибки.

На платёжное уведомление нужно отвечать в любом случае. На всех платформах голоса пользователя переводятся на счёт приложения только после обработки ответа.

Тестирование

Чтобы протестировать оплату голосами, добавьте тестировщиков платежей.

  • •
    Голоса за покупки в этом мини-приложении со счёта тестировщика не списываются, именно поэтому 1 голоса достаточно для любого количества покупок.
  • •
    У тестировщика приложения не списываются голоса за любые покупки в этом приложении (именно поэтому 1 голоса достаточно).
  • •
    Если операцию выполняет тестировщик, в поле notification_type платёжных уведомлений будут значения с постфиксом _test, например get_item_test, order_status_change_test.
  • •
    Для тестировщика окно покупки будет содержать дополнительные пояснения.

Если приложение ещё не прошло модерацию, работать с голосами можно только в тестовом режиме.

Модерация

Принимать оплату голосами можно только мини-приложениям, которые прошли процесс модерации. Подать заявку могут как приложения из каталога, так и вне него.

Чтобы подать заявку на попадание мини-приложения в каталог и подключение оплаты голосами, заполните заявку в блоке Модерация.

Чтобы подключить оплату голосами в мини-приложении без публикации его в каталоге, заполните заявку в блоке Модерация только для использования голосов.

В обоих случаях, как для подключения голосов, так и для публикации в каталоге, мини-приложение должно соответствовать правилам размещения сервисов на платформе VK Mini Apps.

FAQ

Обязательно ли размещать приложение в каталоге?

Нет. Оплата голосами будет работать только в приложениях, которые прошли модерацию, размещение в каталоге для этого не обязательно. Остальные могут вызывать событие VKWebAppShowOrderBox только в тестовом режиме.

Я хочу обменивать на голоса не виртуальные, а реальные товары. Можно?

Нет. Голоса можно обменять только на виртуальную ценность. Возможно, вам нужен магазин — в нём товары можно продавать за деньги.

Можно ли выводить голоса на счёт пользователя?

Нет. Единственный допустимый случай — возврат пользователю ранее внесённых им голосов.

Оплата голосами не будет работать в приложении ВКонтакте для iOS?

Не будет. Мы выполняем правила размещения приложений в App Store (пункты 3.1.3(b) и 3.2.1 (vi)). Использовать голоса в мини-приложениях можно в версии для компьютера, в мобильном браузере и в мобильном приложении для Android. Прежде чем вызвать событие VKWebAppShowOrderBox, вызовите VKWebAppGetClientVersion, чтобы получить информацию о том, на какой платформе открыто приложение.

Можно ли перенести виртуальную ценность из одного мини-приложения в другое?

Нет. Виртуальные ценности нельзя использовать за пределами конкретного мини-приложения. Поэтому, например, у пользователя не должно быть возможности купить игровую валюту в одном приложении, а потратить её в другом. Мини-приложения, нарушившие это правило, навсегда лишаются возможности продавать что-либо за голоса и не смогут попасть в каталог даже после устранения нарушения.

Могут ли пользователи передавать друг другу виртуальные ценности, купленные за голоса?

Да, но с двумя оговорками.

Во-первых, только внутри одного приложения. Любым мини-приложениям, как в каталоге, так и вне его, запрещается передавать виртуальные ценности, купленные за голоса, из одного приложения в другое. Мини-приложения, нарушившие это правило, навсегда лишаются возможности продавать что-либо за голоса и не смогут попасть в каталог даже после устранения нарушения.

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

Могут ли пользователи передавать друг другу голоса?

Нет, это невозможно в принципе.

Что такое платёжное уведомление?

Чтобы получать информацию от вашего приложения, сервер ВКонтакте отправляет платёжные уведомления на адрес обратного вызова. Платёжное уведомление — это POST-запрос, на который сервер ВКонтакте ожидает ответ.

Как узнать, на какой платформе открыто приложение?

Используйте событие VKWebAppGetClientVersion. Название платформы также передаётся в параметре vk_platform.

Пользователь поставил галочку «Автоматически проводить оплату». Что это значит?

В следующий раз голоса на счёт приложения попадут быстрее. Если этот пользователь вы и вы хотите отменить автоматическую оплату, откройте Настройки → Платёжные сервисы. В поле Оплата в играх выберите выключена.

Покупателю не хватило голосов и он заплатил рублями. Я получу рубли, а не голоса?

Нет. Действительно, если покупателю не хватает голосов, он может купить их тут же, не закрывая диалоговое окно покупки. Хоть покупатель и платит рублями, он покупает за рубли не виртуальную ценность, а голоса. Поэтому счёт приложения пополнится голосами, а не рублями.

Как превратить голоса в рубли?

Нужно заключить договор с ВКонтакте или действовать через агрегатора. Перед выводом средств нужно будет принять оферту (откройте Мои приложения → Редактировать → Платежи).