Web Ads SDK (JS)

Web Ads SDK (далее SDK) предназначено для монетизации рекламного инвентаря в веб-приложениях ( веб-сайтах ). В состав SDK включены:

Advertising SDK - для запроса и отображения рекламы в приложении

Прежде чем начать

Вам должны быть известны следующие параметры, необходимые для инициализации и использования SDK. Попросите команду SDK выдать их вам.

bannerURL - URL API рекламной системы. Например: https://test.com/
SDK URL - URL для загрузки SDK в веб-приложение (веб-сайт). Например: https://test-sdk.com/web-sdk.js

Версия Ads SDK: 0.5.1

Инициализация

Инициализация библиотеки выполняется разработчиком посредством вызова метода webSDK.init().

typescript

type InitParams = {
  baseUrl: string; // DEPRECATED
  bannerURL: string;
  uid?: string;
  sessionId: string;
  debug?: 'error' | 'warn' | 'info' | 'debug';
};

type Init = (params: InitParams) => void;

bannerURL - выданный вам URL API рекламной системы (см. выше). Например: https://test.com/
sessionId - Уникальный идентификатор сессии, определяющий текущую сессию приложения. For example: bfd0620a5017d1362431aea6c1d6e504.
uid - (необязательный) уникальный идентификатор пользователя. В качестве идентификатора может служить хэш email-а или номера телефона указанного пользователем при регистрации. Например: bfd0620a5017d1362431aea6c1d6e504.
debug - (необязательный) флаг определяет уровень логирования дебаг информации в SDK. warn по умолчанию.

Разместите вызов метода init как можно раньше при загрузке веб-страницы. Лучше если это сделать внутри тега <head>. Для этого откройте код своего сайта и найдите в нем код тега <head>.

html

<!-- Example -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Web Ads SDK (JS)</title>
    <!-- INSERT SDK CODE FOR INITIALISATION HERE -->
  </head>
</html>

Поместите код инициализации в нижнюю часть раздела заголовка над закрывающим тегом </head>:

html

<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  webSDK.init({
    bannerURL: 'https://test.com/',
    uid: 'bfd0620a5017d1362431aea6c1d6e504',
    sessionId: 'bfd0620a5017d1362431aea6c1d6e504',
  });
</script>

User ID (UID)

Ваше мобильное приложение может быть:

Anonymous - публичное приложение, которое не требует для доступа к функционалу авторизации пользователя.
AuthN/AuthZ - пользователь должен иметь аккаунт и пройти авторизацию для доступа к функционалу.
Комбинированное - часть функционала приложения доступна пользователю без авторизации, когда как другая часть только после прохождения таковой.

SDK предоставляет функцию setUserId, позволяющую выставлять значение уникального идентификатора пользователя, прошедшего авторизацию. Используйте данную функцию для установки значение uid при каждой успешной попытке авторизации пользователя в вашем приложении.

INFO

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

code exampletypes

html

<div id="placement_id" class="placement"></div>
<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  // Вызов без указания uid
  webSDK.init({
    bannerURL: 'https://test.com/',
    sessionId: 'bfd0620a5017d1362431aea6c1d6e504',
  });
  // Позже во время входа пользователя в систему, необходимо вызвать функцию setUserId
  webSDK.setUserId('testUID');
</script>

export type SetUserId = (uid: string) => void;

uid - (обязательный) уникальный идентификатор пользователя, прошедшего успешную авторизацию внутри хост приложения.

Показ рекламного баннера

Инициализация баннера происходит посредством вызова функции webSDK.loadBanner().

typescript

type AdSize = {
  w: number;
  h: number;
};

type BannerPlacement = {
  placementId: string;
  origin?: string;
  sizes: AdSize[];
  refresh?: number;
  customParams?: Record<string, unknown>;
};

export type BannerLoad = (placements: BannerPlacement[]) => Promise<void>;

placementId - идентификатор рекламного места. Например: "456".
origin - (необязательный) строка определяющая origin (scheme, hostname, and port) с которого будет производиться запрос.
sizes - список допустимых размеров для баннера.
refresh - (необязательный) параметр, описывающий время в секундах, через которое будет выполнен повторный запрос рекламного баннера. Если его не указать, то загрузка рекламного креатива произойдет один раз.
customParams - (необязательный) пользовательские параметры, которые можно по согласованию передать на сервер для дальнейшей их обработки.

Разместите в любом подходящем с точки зрения дизайна месте страницы div элемент с аттрибутом id, который будет указывать на идентификатор рекламного места. Сразу за ним разместите тег script, содержащий вызов метода webSDK.loadBanner().

Внимание

внутреннее содержимое div тэга используется самим SDK для отображения рекламного баннера. Не размещайте ничего в нем самостоятельно, т.к. в противном случае может получиться непредвиденный результат во время работы SDK.

html

<div id="placement_id" class="placement"></div>
<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  webSDK.loadBanner([
    {
      placementId: 'placement_id',
      origin: 'https://domain.com',
      sizes: [{ w: 240, h: 300 }],
      refresh: 30,
      customParams: {
        gdprConsent: 'CPsmEWIPsmEWIABAMBFRACBsABEAAAAgEIYgACJAAYiAAA.QRXwAgAAgivA',
        ccpa: '1YNN',
        coppa: 1,
      },
    },
  ]);
</script>

NoAd

Если после вызова loadBanner() функции был получен 204 статус, то рекламные места будут обработаны в соотвествии с NoAd логикой.

NoAdContent событие будет сгенерировано.
Элемент div, отведенный для рекламного баннера, будет скрыт.
Если ответ с 204 статусом получен от первого запроса, то по умолчанию через 3 секунды будет произведен повторный запрос рекламного баннера.
Если ответ с 204 статусом получен после серии запросов, тогда для параметра refresh будет установлено значение из последнего 200 ответа от сервера.
Запросы будут повторятся с указанными настройками, пока не будет получен ответ со статусом 200. Из данного ответа обновится параметр refresh.
Если для refresh было установлено значение равно нулю, то повторных запросов рекламного баннера больше производится не будет.

Показ товарного баннера

Товарный баннер - специальный тип рекламного креатива для RetailMedia платформ, использующий в своей основе SKU идентификатор товара в RetailMedia платформе. SDK на своей стороне в данном случае не производит рендеринг рекламного контента и выполнение функционала трекинга и переходов на посадочную страницу. В данном типе креатива это зона отвественности разработчика. Получив ответ от SDK со списком креативов и их SKU, разработчик формирует отображение рекламного контент на основе уже существующих картинок товаров в платформе по этим SKU, в соответствии с внутренними шаблонам и стилями, обеспечивая вызов необходимых трекинг событий.

Инициализация товарного креатива происходит посредством вызова функции webSDK.loadProduct().

typescript

type ProductPlacement = {
  placementId: string;
  origin?: string;
  refresh?: number;
  customParams?: Record<string, unknown>;
};

export type ProductResponse = {
  bids: ProductCreative[];
};

export type ProductLoad = (placements: ProductPlacement[]) => Promise<void>;

Параметры

placementId - идентификатор рекламного места. Например: "456".
origin - (необязательный) строка определяющая origin (scheme, hostname, and port) с которого будет производиться запрос.
refresh - (необязательный) параметр, описывающий время в секундах, через которое будет выполнен повторный запрос рекламного баннера. Если его не указать, то загрузка рекламного креатива произойдет один раз.
customParams - (необязательный) пользовательские параметры, которые можно по согласованию передать на сервер для дальнейшей их обработки.

Возвращаемое значение

ProductResponse объект с полем bids, содержащий массив объектов ProductCreative.

Примеры

html

<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  webSDK.loadProduct([
    {
      placementId: 'placement_id',
      origin: 'https://domain.com',
      refresh: 30,
      customParams: {
        gdprConsent: 'CPsmEWIPsmEWIABAMBFRACBsABEAAAAgEIYgACJAAYiAAA.QRXwAgAAgivA',
        ccpa: '1YNN',
        coppa: 1,
      },
    },
  ]);
  webSDK.onEvent(webSDK.Events.LoadDataSuccess, 'placement_id', ({ detail }) =>
    console.log(`Данные загружены успешно. Товарный креатив: ${JSON.stringify(detail)} `),
  );
</script>

NoAd

Если после вызова loadProduct() функции был получен 204 статус, то рекламные места будут обработаны в соотвествии с NoAd логикой.

Для таких placements будет сгенерировано событие NoAdContent.

Обработка событий

Обработка событий показа рекламного баннера происходит с помощью функций webSDK.onEvent() и webSDK.onEvent(). Список самих событий приведен ниже.

Функция webSDK.onEvent() позволяет добавлять функции-обработчики (callback) на определенное событие показа рекламного баннера. Функция webSDK.offEvent() удаляет все функции-обработчики с определенного события показа рекламного баннера.

typescript

type onEvent = (event: Events, placementId: string, callback: () => void) => void;

type offEvent = (event: Events, placementId: string) => void;

События:

LoadDataSuccess - запрос к рекламному серверу успешно вернул данные;
LoadDataFail - ошибка при запросе к рекламному серверу;
LoadContentSuccess - креатив успешно отрисован;
LoadContentFail - ошибка при отрисовке креатива, контент креатива содержит недопустимые данные;
NoAdContent - запрос к рекламному серверу успешно завершился, но сервер не нашел рекламного контента под данные параметры запроса;
Impression - рекламный креатив был показан пользователю;
Click - пользователь произвел нажатие на рекламный креатив;
Viewable - рекламный креатив был показан в зоне видимости пользователя.

html

<div id="placement_id" class="placement">Placeholder for ad placement</div>
<script type="module">
  import webSDK from 'https://test-sdk.com/web-sdk.js';
  webSDK.onEvent(webSDK.Events.LoadDataSuccess, 'placement_id', () => console.log('Данные загружены успешно.'));
  webSDK.onEvent(webSDK.Events.LoadContentSuccess, 'placement_id', () =>
    console.log('Контент креатива успешно добавлен на страницу.'),
  );

  webSDK.onEvent(webSDK.Events.LoadDataFail, 'placement_id', () => console.log('Данные не загружены с сервера.'));
  webSDK.onEvent(webSDK.Events.LoadContentFail, 'placement_id', () =>
    console.log('Контент креатива не был отрисован на странице.'),
  );

  webSDK.onEvent(webSDK.Events.Impression, 'placement_id', () => console.log('Контент креатива успешно показан.'));
  webSDK.onEvent(webSDK.Events.Click, 'placement_id', () => console.log('Пользователь произвел нажатие на креатива.'));
  webSDK.onEvent(webSDK.Events.Viewable, 'placement_id', () =>
    console.log('Контент креатива находится в зоне видимости пользователя.'),
  );
</script>

Вспомогательные типы

AdSize

Тип объект, описывающий размер места размещения. Содержит поля, соответствующих ширине и высоте места размещения в пикселях.

typescript

type AdSize = {
  w: number;
  h: number;
};

w - Ширина в пикселях. Например: 300
h - Высота в пикселях. Например: 250

ProductCreative

Объект, описывающий товарный креатив.

typescript

export type ProductCreative = {
  id: string;
  placementId: string;
  sku: string;
  externalId: string;
  disclaimer?: string;
  tracking?: ProductTracking;
  advertiser?: string;
};

requestId - id запроса
placementId - идентификатор рекламного места.
sku - уникальный идентификатор товара
externalId - уникальный внешний идентификатор рекламного объявления
disclaimer - (необязательный) письменный отказ от ответственности либо об ограничении ответственности при публикации рекламного контента
tracking - (необязательный) объект, содержащий URLs для трекинга событий ProductTracking
advertiser - (необязательный) имя рекламодателя.

ProductTracking

Object represents tracking urls.

typescript

export type ProductTracking = {
  view: string[];
  click: string[];
  impression: string[];
};

click - список URLs для трекинга событий клика.
impression - список URLs для трекинга событий показа.
view - список URLs для трекинга событий показа в области видимости.

Web Ads SDK (JS) ​

Инициализация ​

User ID (UID) ​

Показ рекламного баннера ​

NoAd ​

Показ товарного баннера ​

Параметры ​

Возвращаемое значение ​

Примеры ​

NoAd ​

Обработка событий ​

Вспомогательные типы ​

AdSize ​

ProductCreative ​

ProductTracking ​

Web Ads SDK (JS)

Инициализация

User ID (UID)

Показ рекламного баннера

NoAd

Показ товарного баннера

Параметры

Возвращаемое значение

Примеры

NoAd

Обработка событий

Вспомогательные типы

AdSize

ProductCreative

ProductTracking