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

Обновлено 14 февраля 2025

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

Донаты обрабатываются с помощью сервиса ЮMoney.

Оповещения о зачислении денег поступают на электронный адрес, привязанный к кошельку ЮMoney.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Настройка донатов в сценарии Code

В этом разделе описан способ подключения донатов в сценарии, созданном в Code.

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

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

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

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

injector:
    pay_api_key: '***********'
    url_smartpay: 'https://smartpay.devices.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

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

Чтобы провести платеж:

Создайте счет на оплату с помощью запроса POST /invoices.

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

Вы можете выполнить запрос с помощью JS-функции, которая вызывается в сценарии Code:

/src/scripts/donationUtils.js
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, // Идентификатор сервиса из раздела injector файла chatbot.yaml
                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',
                    },
                ],
            },
        },
    };
    // Адрес сервера для проведения оплаты из раздела injector файла chatbot.yaml
    var url = context.injector.url_smartpay + 'invoices';
    // Выполняем запрос с помощью сервиса $http и сохраняем ответ
    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;
    }
}

Пример получения номера счета в сценарии:

/src/main.sc
state: donationSample
script:
    //  Получаем invoice_id
    var response = createDonationOrderSample($context);
    var invoice_id = response.invoice_id

Получите платежную форму с помощью запроса POST /invoices/{invoice_id}

Примерный вид адреса платежной формы, полученной в ответ на запрос, в поле form_url:

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

Вы можете выполнить запрос с помощью JS-функции, которая вызывается в сценарии Code:

/src/scripts/donationUtils.js
function updateInvoiceWithPaymentWay(context, invoice_id) {
   var pay_api_key = context.injector.pay_api_key;
   // Заголовок запроса
   var header = {
       "accept": "application/json",
       "Content-Type": "application/json",
       "Authorization": "Bearer " + pay_api_key // Эксплуатационный токен
   };

   var device_surface = context.session.rawRequest.payload.device.surface.toUpperCase();
   var platform_type = context.session.rawRequest.payload.device.platformType.toUpperCase();
   var sub = context.session.rawRequest.uuid.sub;
   var body = {
       "user_id": {
           "encrypted_sub_id": sub,
           "user_channel": "B2C"
       },
       "code": "QR"
   };

   var url = context.injector.url_smartpay + "invoices/" + invoice_id;
   // Выполняем запрос с помощью сервиса $http и сохраняем ответ
   var response = $http.query(url, {
       method: "POST",
       headers: header,
       body: body
   });
 
   $jsapi.log("| Donation Sample | update invoice: " + response.data);
   return response.data
}

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

/src/main.sc
state: donationSample
script:
    //  Получаем invoice_id
    var response = createDonationOrderSample($context);
    var invoice_id = response.invoice_id

    //  Получаем адрес платежной формы
    response = updateInvoiceWithPaymentWay($context, invoice_id)
    var form_url = response.form_url;

В команде ассистенту передайте адрес платежной формы с помощью функции makeCommandForChatApp() (если у вас Chat App) или makeCommandForCanvasApp() (если у вас Canvas App).

Chat App
Canvas App

/src/scripts/donationUtils.js
function makeCommandForChatApp(context, form_url) {
    var items = [];
    var surfaces_for_url = ['COMPANION', 'SBOL'];
    //  Разделяем логику для StarOS и мобильных приложений
    if (surfaces_for_url.indexOf(getSurface(context)) > -1) 
    {
        // Формируем сообщение с ссылкой на страничку оплаты (ЮMoney)
        items.push({
            command: {
                type: 'action',
                action: {
                    type: 'deep_link', // Для запуска в мобильном приложении
                    deep_link: form_url,
                },
            },
        })
        
    } else {
        // Формируем команду нарисовать QR с ссылкой на страничку оплаты (ЮMoney)
        items.push({
            card: {
                type: "qr_code_card",
                data: form_url,
            },
        })
    }
    var reply = {
        type: 'raw',
        body: {
            items: items
        },
    };
    $jsapi.log('| Donation Sample | get reply: ' + reply);
    return reply;

    // Определяем поверхность
    function getSurface(context) {
        var device_surface = context.session.rawRequest.payload.device.surface.toUpperCase();
        $jsapi.log("| Donation Sample | device_surface: "+ toPrettyString(device_surface));
        return device_surface;
    }
}

/src/scripts/donationUtils.js
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;
}

Пример подключения донатов в сценарии в Code:

/src/main.sc
# Подключение файла, который содержит функции для проведения оплаты
require: scripts/donationUtils.js

theme: /

    state: donationSample
    script:
        //  Получаем invoice_id
        var response = createDonationOrderSample($context);
        var invoice_id = response.invoice_id
        //  Получаем адрес платежной формы
        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) или приходит карточка с QR-кодом, ведущим на страницу оплаты.

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

Для Canvas App

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

Для Chat App

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

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

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

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

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

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

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

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

Настройка донатов в сценарии Code﻿

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

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

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

Для Canvas App﻿

Для Chat App﻿

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

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