Как подключить рекламную монетизацию к приложениям для виртуальных ассистентов Салют

Для виртуальных ассистентов Салют можно создавать приложения с красивым интерфейсом и возможностью управлять ими разными способами: голосом, текстовыми сообщениями, касанием, жестами и пультом. Такие приложения называются 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/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% дохода от рекламной монетизации, без комиссии.