> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Глоссарий: Промо-баннеры

> Справочник промо-баннеров платформы: содержимое баннера, правила показа, чёрный список компаний, журнал показов и страницы выдачи, отметки о прочтении и админки.

Справочник к странице [«Промо-баннеры»](/ru/logic/settings/promo).

## Понятия

| Понятие                     | Значение                                                                                                                                                                                                                                                                                            |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Промо-баннер                | Рекламный баннер платформы, который показывается сотрудникам компаний в интерфейсе. Баннеры общие для всей платформы (создаются в админке), а ограничения и журнал показов ведутся по компаниям и пользователям внутри одной записи.                                                                |
| Представление баннера       | Набор полей баннера, которые отдаются в интерфейс. Наружу уходят только содержательные поля; периодичность, журнал показов, чёрный список и флаг активности остаются внутренними.                                                                                                                   |
| Выдача баннера              | Возвращает один баннер, который сейчас уместно показать текущему пользователю компании. Берётся первый активный баннер, не попавший в чёрный список компании и либо ещё не показанный этому пользователю, либо показанный раньше, чем указанная периодичность; если подходящего нет — ответ пустой. |
| Отметка о прочтении баннера | Записывает в журнал показов текущее время для пары «компания — пользователь». Отдельный вызов по номеру баннера; неизвестный номер даёт ошибку «не найдено».                                                                                                                                        |
| Баннеры в админке           | Страница платформенной админки, где создаются и отключаются баннеры. Список показывает заголовок и флаг активности, поиск идёт по заголовку, описанию, промокоду и ссылке.                                                                                                                          |

## Модели и поля

### Промо-баннер

*Рекламный баннер платформы, который показывается сотрудникам компаний в интерфейсе. Баннеры общие для всей платформы (создаются в админке), а ограничения и журнал показов ведутся по компаниям и пользователям внутри одной записи.*

**Идентификация**

| Поле          | Тип   | Описание                                                      |
| ------------- | ----- | ------------------------------------------------------------- |
| Идентификатор | число | Числовой номер баннера, по нему баннер отмечается прочитанным |

**Содержимое**

| Поле        | Тип           | Описание                                                  |
| ----------- | ------------- | --------------------------------------------------------- |
| Заголовок   | текст         | Обязательный заголовок баннера                            |
| Описание    | длинный текст | Обязательный текст баннера                                |
| Промокод    | текст         | Код, который предлагается пользователю; может быть пустым |
| Иконка      | текст         | Название иконки для оформления баннера; может быть пустым |
| Ссылка      | текст         | Адрес перехода по клику на баннер; может быть пустым      |
| Изображение | изображение   | Картинка баннера, загружается в папку promo/              |
| Анимация    | файл          | Анимированный файл баннера, загружается в папку promo/    |

**Показ**

| Поле                 | Тип                | Описание                                                                                                      |
| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------- |
| Периодичность показа | число (часы)       | Через сколько часов после последнего показа баннер можно показать тому же пользователю снова; по умолчанию 24 |
| Журнал показов       | структура (объект) | Отметки о показах в разрезе компания → пользователь → время последнего показа                                 |

**Доступность**

| Поле                   | Тип          | Описание                                                        |
| ---------------------- | ------------ | --------------------------------------------------------------- |
| Чёрный список компаний | список чисел | Компании, которым баннер не показывается вовсе                  |
| Активен                | флаг         | Выключенный баннер не участвует в подборе; по умолчанию включён |

### Представление баннера

*Набор полей баннера, которые отдаются в интерфейс. Наружу уходят только содержательные поля; периодичность, журнал показов, чёрный список и флаг активности остаются внутренними.*

| Поле          | Тип           | Описание                                          |
| ------------- | ------------- | ------------------------------------------------- |
| Идентификатор | число         | Номер баннера для последующей отметки о прочтении |
| Заголовок     | текст         | Заголовок баннера                                 |
| Описание      | длинный текст | Текст баннера                                     |
| Промокод      | текст         | Предлагаемый код                                  |
| Иконка        | текст         | Название иконки                                   |
| Ссылка        | текст         | Адрес перехода                                    |
| Изображение   | изображение   | Картинка баннера                                  |
| Анимация      | файл          | Анимированный файл баннера                        |

### Выдача баннера

*Возвращает один баннер, который сейчас уместно показать текущему пользователю компании. Берётся первый активный баннер, не попавший в чёрный список компании и либо ещё не показанный этому пользователю, либо показанный раньше, чем указанная периодичность; если подходящего нет — ответ пустой.*

### Отметка о прочтении баннера

*Записывает в журнал показов текущее время для пары «компания — пользователь». Отдельный вызов по номеру баннера; неизвестный номер даёт ошибку «не найдено».*

### Баннеры в админке

*Страница платформенной админки, где создаются и отключаются баннеры. Список показывает заголовок и флаг активности, поиск идёт по заголовку, описанию, промокоду и ссылке.*

| Поле           | Тип             | Описание                          |
| -------------- | --------------- | --------------------------------- |
| Колонки списка | список полей    | Заголовок и признак активности    |
| Поля поиска    | список полей    | Заголовок, описание, код и ссылка |
| Фильтр         | список фильтров | По признаку активности            |