ym88659208ym87991671
Подключение донатов (beta) | Документация для разработчиков
Skip to main content

Подключение донатов (beta)

Обновлено 13 октября 2022

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

Чтобы поддержать разработчика, пользователь нажимает на кнопку «Поддержать смартап» и сканирует QR-код или переходит из мобильного приложения на страницу оплаты ЮMoney. Перевести деньги на ваш кошелек ЮMoney можно любым удобным способом. Вам придет оповещение о зачислении денег на электронный адрес, привязанный к кошельку ЮMoney.

Условия подключения

Подключить донаты можно, если:

  • вы публикуете смартап как физическое лицо (не ИП и не самозанятый),
  • у вас есть опубликованный Chat App или Canvas App (в том числе, HTML5-игра).
note

Вы можете настроить прием донатов на умных устройствах Sber и в мобильном приложении Салют.

Для подключения донатов:

  1. Создайте кошелек в ЮMoney.
  2. Отправьте заявку на подключение донатов.
  3. Настройте прием платежей.
  4. Добавьте кнопку «Поддержать смартап».
  5. Отправьте смартап на модерацию.

Создание кошелька

Чтобы получать донаты от пользователей смартапа, создайте кошелек ЮMoney и подтвердите личность.

Комиссия за полученные донаты не взимается.

note

Об условиях использования кошелька читайте на сайте ЮMoney.

Отправка заявки

Чтобы подключить донаты, отправьте заявку:

  1. Заполните и подпишите заявление на подключение донатов.
  2. Заполните шаблон письма.
  3. Отправьте письмо и скан подписанного заявления на адрес developer@sberdevices.ru.

В ответном письме вы получите идентификатор сервиса (service_id) и эксплуатационный токен. Используйте токен для проверки функциональности приема донатов.

Настройка платежей

Перед подключением

Для регистрации и инициации платежа используйте полученные ранее эксплуатационный токен (pay_api_key) и идентификатор сервиса (service_id).

  • Тип токена: Bearer
  • Имя заголовка: Authorization

Токен, service_id и адрес SmartPay добавьте в файл конфигурации chatbot.yaml.

injector:
pay_api_key: '***********'
url_smartpay: 'https://smartmarket.online.sberbank.ru/smartpay/v1/'
service_id: '##'

Для вызова функций подключите в файле chatbot.yaml следующие библиотеки:

scriptsPreLoad:
global:
- /jslib/moment.min.js
- /jslib/underscore.js
- /jsapi/common.js
- /jsapi/http.js

local:
- /jsapi/mail.js
- /jsapi/reactions.js
- /jsapi/payment.js

Регистрация платежа

Чтобы зарегистрировать платеж и получить invoice_id, необходимо отправить запрос POST /invoices.

При успешном выполнении запроса вы получите invoice_id — уникальный номер зарегистрированного заказа.

function createDonationOrderSample(context) {
var header = {
accept: 'application/json',
'Content-Type': 'application/json',
Authorization: 'Bearer ' + context.injector.pay_api_key, // эксплуатационный токен
};
var body = {
invoice: {
invoice_params: [
{
key: 'inapp_serviceparam_payment_instruments',
value: 'new',
},
],
order: {
order_id: generateUUID(),
order_number: '145', // любой
order_date: currentDate(),
service_id: context.injector.service_id, // идентификатор сервиса
amount: 200, // минимальная сумма для оплаты в ЮMoney - 2 руб
currency: 'RUB',
purpose: 'Поддержать суммой от:', // Отображается в платежном интерфейсе
description: 'Поддержка смартапа',
language: 'ru-RU',
tax_system: 0,
order_bundle: [
{
position_id: 1,
name: 'Поддержи разработчика!',
quantity: {
value: 1,
measure: 'ед.',
},
item_price: 200,
item_amount: 200,
currency: 'RUB',
item_code: 'com.smartapp.donation',
},
],
},
},
};
var url = context.injector.url_smartpay + 'invoices';
var response = $http.query(url, {
method: 'POST',
headers: header,
body: body,
});
$jsapi.log('| Donation Sample | create invoice:' + toPrettyString(response.data));
return response.data;

function generateUUID() {
var dt = new Date().getTime();
var uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
var r = (dt + Math.random() * 16) % 16 | 0;
dt = Math.floor(dt / 16);
return (c == 'x' ? r : (r & 0x3) | 0x8).toString(16);
});
return uuid;
}
}

Проведение платежа

Для умных устройств Sber оплата проводится с помощью встроенного интерфейса. Механизм одинаковый для Chat App и Canvas App. Подробнее читайте в разделе Прием платежей.

Выполните команду $reactions.pay в main.sc:

state: donationSample
a: Отсканируй QR-код
script:
// Получаем invoice_id
var response = createDonationOrderSample($context);
var invoice_id = response.invoice_id;
// Запускаем встроенный интерфейс оплаты
$reactions.pay(invoice_id);

Для запуска платежей в мобильном приложении Салют необходимо инициировать платеж с помощью QR-кода:

function updateInvoiceWithPaymentWay(context, invoice_id) {
var header = {
accept: 'application/json',
'Content-Type': 'application/json',
Authorization: 'Bearer ' + context.injector.pay_api_key, // эксплуатационный токен
};
var device_surface = context.session.rawRequest.payload.device.surface.toUpperCase();
var platform_type = context.session.rawRequest.payload.device.platformType.toUpperCase();
var return_url = getReturnUrl(device_surface, platform_type);
var sub = context.session.rawRequest.uuid.sub;
var body = {
user_id: {
encrypted_sub_id: sub,
user_channel: 'B2C',
},
code: 'QR',
return_url: return_url,
};
var url = context.injector.url_smartpay + 'invoices/' + invoice_id;
var response = $http.query(url, {
method: 'POST',
headers: header,
body: body,
});
$jsapi.log('| Donation Sample | update invoice: ' + response.data);
return response.data;

function getReturnUrl(device_surface, platform_type) {
var return_url = '';
if (device_surface === 'COMPANION') {
return_url = 'https://sberdevices.ru/virtual-assistant/fallback';
} else if (device_surface === 'SBOL') {
if (platform_type === 'IOS') {
return_url =
'https://sberbankonline.onelink.me/46WQ?pid=superapp&c=superapp&is_retargeting=true&af_dp=sberbankonline%3A%2F%2Fvoiceassistant';
} else {
return_url =
'https://sberbank-online.onelink.me/q4HS?pid=superapp&c=superapp&is_retargeting=true&af_dp=android-app%3A%2F%2Fru.sberbankmobile%2Fandroid-app%2Fru.sberbankmobile%2Fassistant%2Flauncher';
}
} else {
return_url = 'https://sberdevices.ru/payment/success';
}
$jsapi.log('| Donation Sample | ' + [return_url, platform_type, device_surface].join(', '));
return return_url;
}
}

Примерный вид полученного return_url:

https://smartmarkettestift.online.sberbank.ru/smartpay/v1/payment-form?payment_uid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx-xxxxxxxx

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


В Chat App:

function makeCommandForChatApp(context, form_url) {
var reply = {
type: 'raw',
body: {
items: [
{
command: {
type: 'action',
action: {
type: 'deep_link', // для запуска в мобильном приложении Салют
deep_link: form_url,
},
},
},
],
},
};
$jsapi.log('| Donation Sample | get reply: ' + reply);
return reply;
}

В Canvas App:

function makeCommandForCanvasApp(context, form_url) {
var reply = {
type: 'raw',
body: {
items: [
{
command: {
type: 'smart_app_data',
action: {
type: 'deep_link', // для запуска в мобильном приложении Салют
deep_link: form_url,
},
},
},
],
},
};
$jsapi.log('| Donation Sample | get reply: ' + reply);
return reply;
}

Далее отправьте данное сообщение через ассистента в main.sc:

state: donationSample
a: Отсканируй QR-код
script:
// Получаем invoice_id
var response = createDonationOrderSample($context);
var invoice_id = response.invoice_id
// Запускаем встроенный интерфейс оплаты
$reactions.pay(invoice_id)

// Получаем url
response = updateInvoiceWithPaymentWay($context, invoice_id)
var form_url = response.form_url;

// Отправляем команду ассистенту на открытие страницы оплаты (ЮMoney)
var reply = makeCommandForChatApp($context, form_url); // или makeCommandForCanvasApp
$response.replies = $response.replies || [];
$response.replies.push(reply);

Пользователю в браузере открывается страницы оплаты (ЮMoney).

Добавление кнопки

Для Canvas App

Добавьте в смартап кнопку, аналогичную макету:

Для Chat App

Добавьте в сценарий саджест «Поддержать смартап».

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

Рекомендации

  • Показывайте кнопку не чаще, чем один раз за сессию, чтобы не отвлекать пользователей.
  • Проанализируйте, на каком моменте сценария большинство пользователей покидают смартап. Разместите кнопку за один шаг до этого, чтобы охватить максимальную аудиторию.
  • Не показывайте кнопку до того, как закончится логический этап сценария, например, пока не завершится текущий уровень игры. Иначе, скорее всего, пользователь захочет узнать, что будет дальше, и пропустит шаг с отправкой донатов.

Модерация смартапа

  1. Авторизуйтесь в Studio и отправьте смартап на модерацию.
  2. Укажите в инструкции для тестирования, что вы добавили кнопку «Поддержать смартап».
  3. После модерации опубликуйте смартап.

Теперь вы можете получать донаты от пользователей.

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней