ym88659208ym87991671
Подключение SmartAds | Документация для разработчиков
Skip to main content

Подключение SmartAds

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

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

  1. Подключите библиотеки SberDevices Ad SDK и настройте вебхук.
  2. Подключите сценарий для обработки рекламного запроса.
  3. Реализуйте запуск рекламы.

Подключение библиотек

Подключите в код смартапа следующие библиотеки:

  • модуль Assistant Client для общения с ассистентом. Два способа подключения описаны в разделе Установка;
  • Ad SDK для работы с рекламой. После установки библиотеки становится доступен объект window.SberDevicesAdSDK — он понадобится для запуска рекламы. Для подключения добавьте тег script в head или в body:
<script src="https://cdn-app.sberdevices.ru/shared-static/0.0.0/js/@sberdevices/ad-sdk/ad-sdk.min.js"></script>

Подключение сценария

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

Вы можете подключить готовый сценарий или создать собственный.


Готовый сценарий

Чтобы подключить готовый сценарий:

  1. Откройте в Studio свой проект.
  2. В настройках смартапа выберите в поле Webhook значение SmartApp API и скопируйте следующий url:
https://smartapp-code.sberdevices.ru/chatadapter/chatapi/webhook/sber_nlp2/akvMhQEy:73931a63e07450a5260600c7f9f6e6d6a992578b

Свой сценарий

Для создания собственного сценария используйте инструменты Studio. Вы можете использовать пример для SmartApp API.

Ваш сценарий должен собирать следующие данные:

  • sub — уникальный идентификатор пользователя в пространстве,
  • projectNameидентификатор проекта,
  • device — объект с информацией о текущем устройстве,
  • app_info — объект с информацией о смартапе.

Инициализация кода

note

Для корректной инициализации кода необходимо подключить Assistant Client (см. раздел Установка) до инициализации SberDevices Ad SDK.

В SberDevices Ad SDK есть несколько вариантов инициализации.


Если в смартапе нет голосового управления

Для инициализации без голосового управления, например, если вы подключаете готовый сценарий, используйте метод window.SberDevicesAdSDK.init();.

window.SberDevicesAdSDK.init({ onError, onSuccess, test });
  • onSuccess - функция вызывается после успешной инициализации. После этого можно запускать рекламу.
  • onError - функция вызывается если при инициализации произойдет ошибка.
  • test - параметр для тестирования рекламы. При значении true в смартапе запускается тестовая реклама. Для опубликованных смартапов параметр должен отсутствовать или принимать значение false.

Пример использования метода можно посмотреть в демо-проекте.


Если необходима отладка в браузере

Для отладки в браузере используйте метод window.SberDevicesAdSDK.initDev();.

window.SberDevicesAdSDK.initDev({ token, initPhrase, onSuccess, onError, test });
  • token — токен для отладки, который можно получить в Studio.
  • initPhrase — фраза для запуска смартапа. Фраза должна начинаться со слова «запусти», например, «запусти Кубик Рубика».
  • onSuccess - функция вызывается после успешной инициализации. После этого можно запускать рекламу.
  • onError - функция вызывается, если при инициализации происходит ошибка.
  • test - параметр для тестирования рекламы. При значении true в смартапе запускается тестовая реклама. Для опубликованных смартапов параметр должен отсутствовать или принимать значение false.

В зависимости от окружения запускайте метод window.SberDevicesAdSDK.init(); или window.SberDevicesAdSDK.initDev();, например:

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 });
} else {
window.SberDevicesAdSDK.init({ onSuccess, onError, test });
}

Если необходима смена персонажей или управление голосом

Если вы хотите контролировать создание assistantClient самостоятельно и, например, подписаться на смену персонажей, то создайте инстанс assistantClient и передайте его в метод window.SberDevicesAdSDK.initWithAssistant();.

Пример создания assistantClient можно посмотреть в документации.

import { createAssistant } from '@salutejs/client';

const assistant = createAssistant(); // для отладки в браузере используйте "const assistant = createSmartappDebugger();"

initWithAssistant(
{
assistant,
onSuccess,
onError,
},
test,
);
  • assistant - инстанс ассистента.
  • onSuccess - функция вызывается после успешной инициализации. После этого можно запускать рекламу.
  • onError - функция вызывается, если при инициализации происходит ошибка.
  • test - параметр для тестирования рекламы. При значении true в смартапе запускается тестовая реклама. Для опубликованных смартапов параметр должен отсутствовать или принимать значение false.

Пример использования метода можно посмотреть в демо-проекте.

Проверка инициализации

Для проверки инициализации используйте метод window.SberDevicesAdSDK.isInited():

window.SberDevicesAdSDK.isInited()

В ответе возвращается true, если инициализация пройдена, и false, если нет.

Получение доступа к ассистенту

Если вы инициализировали код методом window.SberDevicesAdSDK.init();, то чтобы получить экземпляр assistantClient, используйте метод window.SberDevicesAdSDK.getAssistantRef():

const assistantRef = window.SberDevicesAdSDK.getAssistantRef();

const assistant = assistantRef.current;

Если инициализация кода пройдена, в поле current появится экземпляр assistantClient.

Запуск рекламы

danger

При старте рекламы фоновый звук в смартапе должен быть отключен. После окончания рекламы звук можно вернуть.

Запуск Rewarded video

Прежде чем отображать пользователю кнопку просмотра рекламы, вы можете проверить, есть ли в рекламной сети подходящие ролики, и предзагрузить их. Для этого используйте метод preloadVideoAd():

preloadVideoAd({
onSuccess: () => {}, // Вызовется при успешной загрузке данных
onError: (error) => {}, // Вызовется во время ошибки при загрузке данных
onEmptyResponse: () => {}, // Вызовется в случае, если рекламная сеть отдала пустой ответ
});

Предзагруженные данные удаляются после первого вызова рекламы.


Для старта рекламы вызовите метод runVideoAd(); объекта window.SberDevicesAdSDK:

runVideoAd({
onSuccess: () => {},
onError: () => {},
mute: true,
});

Настройте у метода run (); следующие параметры:

  • onSuccess — сработает при переходе или полном показе рекламы. В этом параметре необходимо прописать код, который назначит пользователю награду за просмотр рекламы.
  • onError — сработает, если во время показа рекламы произошла ошибка. Для улучшения пользовательского опыта рекомендуем для этого параметра прописать код, который назначит пользователю награду.
  • mute — наличие звука в рекламе:
    • true — реклама будет запущена без звука, рекомендуется для игр без фоновой мелодии.
    • false — реклама будет запущена со звуком.

Запуск Interstitial

Вы можете заранее проверить, есть ли в рекламной сети подходящие банеры, и предзагрузить их. Для этого используйте метод preloadBannerAd():

preloadBannerAd({
onSuccess: () => {}, // Вызовется при успешной загрузке данных
onError: (error) => {}, // Вызовется во время ошибки при загрузке данных
onEmptyResponse: () => {}, // Вызовется в случае, если рекламная сеть отдала пустой ответ
});

Предзагруженные данные удаляются после первого вызова рекламы.


Для старта рекламы вызовите метод runBanner(); объекта window.SberDevicesAdSDK:

window.SberDevicesAdSDK.runBanner({
onSuccess,
onError,
});

У метода есть следующие параметры:

  • onSuccess — сработает при полном показе рекламы.
  • onError — сработает, если во время показа рекламы произошла ошибка. По умолчанию будут закрыты все рекламные контейнеры и работа смартапа продолжится в обычном режиме.

Тестирование рекламы

После подключения рекламы протестируйте смартап.

note

Если вы тестируете смартап в браузере, предварительно отключите AdBlock и прочие расширения, которые могут блокировать рекламу.

Примеры реализации

Вы можете ознакомиться с примером подключения рекламы в смартап.

Для запуска собственного демо-проекта следуйте инструкции по ссылке.

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней