SDKВебJavaScript SDK

Методы и параметры

Методы и параметры браузерного клиента Sidekick.

Настройки клиента

create()

const ads = Sidekick.create({
  platformId: "plt_example",
  onError: (error) => console.error(error.message)
});

Параметр	Тип	Описание
`platformId`обязательно	string	Публичный ID площадки.
`baseUrl`	string	HTTPS-адрес API без пути. По умолчанию https://sidekick-ads.com.
`visitorId`	string	ID посетителя, 16–128 символов. Если не передан, SDK создаёт и сохраняет его автоматически.
`storage`	string	local — сохранять ID в браузере; memory — на время работы клиента. По умолчанию local.
`timeoutMs`	number	Таймаут запроса, 100–30 000 мс. По умолчанию 8 000.
`appearance`	object	Оформление всех карточек
`onError`	function	Обработчик ошибок запросов и загрузки медиа.

Обязательные поля.

Методы

Метод	Описание
`create({ platformId, … })`	Создаёт клиент.
`requestAd({ target, requestId, … })`	Запрашивает и отображает рекламу. Возвращает Promise<{filled, fromCache?}>.
`fetchAd({ requestId, … })`	Возвращает Promise<ad \| null> для своей отрисовки.
`trackView(ad)`	Для своей отрисовки: подтверждает просмотр, когда не меньше половины карточки было на экране не меньше секунды. Показ оплачивается только после этого.
`interact(ad, action)`	Возвращает Promise<ad \| null> со следующей сценой consent или quiz.
`setAppearance(options)`	Обновляет оформление без запроса новой рекламы.
`setScreenActive(active)`	Управляет воспроизведением медиа на экране.
`unmount(target)`	Удаляет карточку из контейнера. Кэш клиента сохраняется.
`dispose()`	Завершает запросы и освобождает ресурсы клиента.

Параметры запроса

Параметр	Тип	Описание
`target`обязательно	HTMLElement	Контейнер карточки. Требуется для requestAd().
`requestId`обязательно	string	ID рекламного места в сообщении, 1–128 символов. Сохраняется при повторной отрисовке.
`placement`	string	Место показа. По умолчанию chat.
`languageCode`	string	Язык рекламы. По умолчанию язык страницы или en.
`acceptFormats`	string[]	Допустимые форматы; по умолчанию все шесть.
`context`	object	Контекст показа: conversation, article, feed или static.
`test / testFormat`	boolean / string	Тестовый режим и формат тестовой рекламы.
`appearance`	object	Оформление отдельной карточки в requestAd().
`onFill / onNoFill`	function	Обработчики результата requestAd().

Обязательные поля.

Поля контекста →

Результат и ошибки

requestAd() возвращает filled: true, если карточка передана на отрисовку, и filled: false при отсутствии рекламы или ошибке запроса. fromCache: true означает, что использован сохранённый результат. Просмотр SDK подтверждает отдельно, когда карточка видна.

Ошибки запросов передаются в onError. fetchAd() при ошибке возвращает null. Неверные настройки при вызове create() вызывают исключение.

Кэш действует в пределах одного клиента и не сохраняется после перезагрузки страницы. Повторный HTTP-запрос — новая выдача. SDK не повторяет запрос после сетевой ошибки автоматически.