Как подключить рекламную монетизацию к приложениям для виртуальных ассистентов Салют
Для виртуальных ассистентов Салют можно создавать приложения с красивым интерфейсом и возможностью управлять ими разными способами: голосом, текстовыми сообщениями, касанием, жестами и пультом. Такие приложения называются Canvas App, они доступны пользователям на умных устройствах Sber и в мобильных приложениях Сбербанк Онлайн и Салют. Один из самых простых способов монетизации ваших Canvas App — реклама. Доступны два её вида:
Rewarded video — формат видеорекламы, когда пользователь получает награду за просмотр ролика. Наградой может быть внутриигровая валюта, дополнительные жизни, попытки, опыт и другие ресурсы в смартапе (навыке).
Fullscreen-баннеры — формат полноэкранной рекламы. Её можно демонстрировать между уровнями, экранами и логическими блоками смартапа.
Наша команда подготовила SDK для подключения и управления показом рекламы в ваших навыках. Давайте пройдём все шаги её подключения.
Передаю слово моему коллеге, руководителю группы разработки общих компонентов Василию Логиневскому.
Для начала уточним, что Canvas App — это веб-приложение, а значит все дальнейшие шаги мы будем делать в качестве веб-разработчика.
Первым делом нам необходимо подключить наше рекламное Ad SDK. Для этого достаточно прописать в HTML-страницу загрузку нашего скрипта:
<script src="https://cdn-app.sberdevices.ru/shared-static/0.0.0/js/@sberdevices/ad-sdk/ad-sdk.min.js"></script>
После загрузки в window
появится объект SberDevicesAdSDK
, и в дальнейшем мы будем работать с его методами.
Первый метод, который нам понадобится — это метод инициализации рекламного SDK:
window.SberDevicesAdSDK.init({ onError, onSuccess });
На самом деле, у нас есть не один, а целых три метода инициализации, и дальше мы рассмотрим их различия. Но все наши методы полагаются на работу сценария вашего навыка, поэтому рекламное SDK предполагает, что оно запущено в одном окне с ассистентом.
Если у вашего Canvas App не было до этого сценария, то он понадобится вам для корректной работы рекламного SDK. Мы реализовали базовый сценарий для быстрого подключения. Чтобы им воспользоваться, пропишите в качестве webhook следующий URL: https://smartapp-code.sberdevices.ru/chatadapter/chatapi/webhook/sber_nlp2/akvMhQEy:73931a63e07450a5260600c7f9f6e6d6a992578b
Если вы добавляете рекламу в существующий смартап, то скорее всего вы уже используете наш Assistant Client для отладки общения со сценарием. Если вы хотите создать навык с нуля, то сначала вам стоит обратиться к нашей документации: https://developers.sber.ru/docs/ru/salute/basics/canvasapp
И подключить Assistant Client: https://github.com/sberdevices/assistant-client#установка
Теперь на клиенте вы можете вызвать один из методов инициализации:
window.SberDevicesAdSDK.init();
window.SberDevicesAdSDK.initDev();
window.SberDevicesAdSDK.initWithAssistant();
Внутри все эти методы подписываются на события от сценария и ждут конкретной команды от него:
{
type: 'smart_app_data',
smart_app_data: {
type: 'sub',
payload: {...},
}
}
Все методы инициализации принимают два параметра: onError
и onSuccess
:
window.SberDevicesAdSDK.init({
onSuccess: () => { console.log('AdSDK inited'); },
onError: () => { console.error('something gone wrong!'); },
});
После получения команды от сценария происходит инициализация. Если всё прошло успешно, вызовется onSuccess
, а если произошла ошибка — onError
соответственно.
При этом стоит помнить, что если вы некорректно подключили сценарий, то никакой команды мы не получим, и onError
не вызовется. Поэтому для проверки, произошла ли инициализация, мы добавили дополнительный метод:
window.SberDevicesAdSDK.isInited(); // => true | false
Тестовые креативы
Уточним важный момент: при разработке и тестировании рекламу стоит запускать с тестовым креативом. Это значит, что мы не будем считать эту рекламу показанной пользователю. Для этого в любой метод инициализации передайте параметр test
:
window.SberDevicesAdSDK.init({
test: true,
onSuccess: () => { console.log('AdSDK inited'); },
onError: () => { console.error('something gone wrong!'); },
});
Вариации методов инициализации
Какой метод инициализации выбрать?
Если вы никак не взаимодействуете со сценарием и подключили наш готовый webhook, вам подойдут init
& initDev
.
Если у вас есть свой сценарий, написанный на любом из наших инструментов — SmartApp Code, Salute JS, SmartApp Framework, — вам подойдёт метод initWithAssistant
.
init & initDev
Метод init
предполагает запуск на устройстве, но вы, скорее всего, разрабатываете навык просто в браузере, поэтому для отладки мы предоставляем метод initDev
.
Этот метод предполагает два дополнительных параметра: token
и initPhrase
.
initPhrase
— фраза для запуска вашего смартапа. Она строится следующим образом: “Запусти” + “Активационное имя” ("Запусти мой апп"). Например, “Запусти Кубик Рубика”.
token
— токен для дебага, получить его можно в SmartApp Studio по инструкции.
Итого у вас получится примерно вот такой код запуска:
const IS_DEVELOPMENT = process.env.NODE_ENV === "development";
const DEV_TOKEN = process.env.DEV_TOKEN;
const DEV_PHRASE = process.env.DEV_PHRASE;
if (IS_DEVELOPMENT) {
window.SberDevicesAdSDK.initDev({ token: DEV_TOKEN, initPhrase: DEV_PHRASE, onSuccess, onError, test: true });
} else {
window.SberDevicesAdSDK.init({ onSuccess, onError });
}
Предполагается, что вы пользуетесь одним из современных сборщиков для web-приложений (например, webpack) и можете пробросить необходимые переменные окружения: NODE_ENV
, DEV_TOKEN
и DEV_PHRASE
.
В итоге методы init
и initDev
необходимо использовать в связке. Это необходимо, потому что при отладке в браузере Assistant Client подменяет собой транспортный слой ассистента, который всегда есть внутри вашего Canvas App, когда вы запускаете его на устройстве.
initWithAssistant()
Если у вас написан свой сценарий, то у вас где-то уже есть инстанс assistantClient
и вы с ним активно взаимодействуете. В таком случае вы можете инициализировать рекламное SDK следующим образом:
const assistant = initializeAssistant();
initWithAssistant({
assistant,
onSuccess,
onError,
});
При этом наше SDK всё ещё будет ждать команды от сценария с type: 'sub'
, о котором было рассказано выше. Это означает, что вам на сценарии необходимо предоставить такую команду. Давайте рассмотрим, что именно требуется предоставить в качестве payload. На самом деле, ничего слишком сложного, вот код создания такого payload c использованием: https://github.com/sberdevices/salutejs. Подробнее почитать про фреймворк Salute JS можно здесь.
const { payload } = req.request;
const userData = {
projectName: payload.projectName,
device: payload.device,
app_info: payload.app_info,
};
res.appendCommand({
type: "sub",
payload: {
sub: req.request.uuid.sub,
...userData,
},
});
Тот же код на SmartApp Code, но посылаем мы сообщение на событие RUN_APP
:
theme: /
state: RunApp
event!: RUN_APP
q!: * *start
script:
var ctx = $jsapi.context();
var req = ctx.request.rawRequest;
$response.replies = $response.replies || [];
$response.replies.push({
type: 'raw',
device: {},
body: {
items: [{
command: {
type: 'smart_app_data',
smart_app_data: {
type: 'sub',
payload: {
sub: req.uuid.sub,
projectName: req.payload.projectName,
device: req.payload.device,
app_info: req.payload.app_info,
}
}
}
}]
}
})
state: noMatch
event!: noMatch
Запуск рекламы
После успешной инициализации тем или иным способом мы можем приступить к запуску рекламы.
Напомним, что в смартапах поддерживается два формата рекламы:
Rewarded video — пользователь получает награду за просмотр видеоролика.
Fullscreen-баннеры — полноэкранная реклама, демонстрируется между уровнями, экранами и логическими блоками смартапа.
Для показа видео:
window.SberDevicesAdSDK.runVideoAd({
onSuccess: () => {},
onError: () => {},
});
Для запуска баннеров:
window.SberDevicesAdSDK.runBanner({
onSuccess: () => {},
onError: () => {},
});
При этом внутри всё общение с рекламной сетью и работу с интерфейсом рекламного плеера или баннеров мы берём на себя.
Рекомендации разработчикам
Показывайте рекламу не более 5 раз за сессию. (Кстати, рекламный баннер можно запустить не чаще чем раз в две минуты, иначе будет срабатывать
onError
.)
Предусмотрите отсутствие звуков во время проигрывания рекламы.
Убедитесь, что реклама не будет проигрываться в неподходящий момент, нарушая сценарий смартапа.
Ещё о подключении рекламной монетизации можно почитать здесь. Если у вас возникнут дополнительные вопросы, вы можете задать их в комментариях к этому посту или написать в Telegram-сообщество разработчиков SmartMarket: https://t.me/smartmarket_community.
Это лишь начало большого пути: мы планируем расширять список доступных поверхностей для смартапов с подключенной рекламной монетизацией, применять дополнительные инструменты для промотирования таких приложений, сделать процесс подключения ещё проще. Доход разработчиков навыков с монетизацией будет расти вместе с развитием рекламного инструментария.
Кстати, до конца апреля 2022 разработчики Canvas App будут получать 100% дохода от рекламной монетизации, без комиссии.