ym88659208ym87991671
Подключение донатов в приложение | Документация для разработчиков

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

Обновлено 20 декабря 2023

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Заполните и подпишите заявление на подключение донатов.
  2. Заполните шаблон письма.
  3. Отправьте письмо и скан подписанного заявления на адрес 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

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

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

  1. Создайте счет на оплату с помощью запроса 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
  2. Получите платежную форму с помощью запроса 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;
  3. В команде ассистенту передайте адрес платежной формы с помощью функции makeCommandForChatApp() (если у вас Chat App) или makeCommandForCanvasApp() (если у вас 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;
    }
    }

Пример подключения донатов в сценарии в 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

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

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

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

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

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

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

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

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.