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

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