Документация

Быстрый старт

Добавьте сайт В кабинете укажите домен — получите site key после модерации.
Вставьте скрипт Один раз на страницах, где должен показываться блок.
Поставьте слот Скопируйте один из примеров ниже и при необходимости поправьте CSS.

Скрипт

Подставьте свой site key из кабинета. Скрипт асинхронный и сам находит элементы с data-hads-slot.

<script src="https://api.hads.dev/v1/hads.js?site=YOUR_SITE_KEY" async></script>

TUI- и CLI-программы

Терминальные клиенты берут объявления из того же пула, что и сайты: один GET-запрос на запуск, ответ — готовый текст для stdout. Показ считается сразу, отдельная сессия не нужна.

Добавьте площадку типа TUI / CLI В кабинете выберите тип «TUI / CLI». Вместо домена укажите идентификатор программы, например myapp-cli.
Запросите объявление Один curl или один HTTP-запрос из вашей программы. Один запрос — один показ, дедупликации нет.
Клик через короткую ссылку В ответе — url вида /v1/click/… Откройте его в браузере посетителя: переходит рекламодатель, клик засчитывается.

curl "https://api.hads.dev/v1/serve?site_key=YOUR_SITE_KEY&format=ansi"

Форматы

json — полный payload как у сайтов (по умолчанию)
text — чистый текст для stdout и пайпов
ansi — то же, но с цветами и кликабельной ссылкой

curl "https://api.hads.dev/v1/serve?site_key=YOUR_SITE_KEY&format=ansi&topic=programming"

Параметры

site_key: site key площадки из кабинета (обязателен)
slot: имя места показа в вашей программе — для статистики
topic: подсказка тематики: каталог из /v1/topics
allow_self: разрешить показ собственных объявлений (true/1)
format: json | text | ansi — формат ответа

url=$(curl -s "https://api.hads.dev/v1/serve?site_key=YOUR_SITE_KEY" | jq -r .ad.url); open "$url"

Пустой пул

Если подходящих объявлений нет: json вернёт ad: null, text и ansi — пустой ответ 204. Скрипт должен просто выйти.

Атрибуты

Скрипт заполняет хуки внутри слота. Если хуков нет — соберёт простую ссылку сам. Заголовок и текст объявления обязательны, картинка — нет.

data-hads-slot: Контейнер слота. Значение — имя слота (для вашей аналитики и вёрстки).
data-hads-topic: Свободный hint темы страницы/контекста. Движок в фоне сопоставляет его с каталогом тем и предпочитает подходящие объявления; если hint пустой, ещё не готов или совпадений нет — игнорируется.
data-hads-allow-self: Разрешает показывать объявления других ваших сайтов в том же аккаунте (свой текущий сайт всё равно исключён). Достаточно присутствия атрибута или значений true / 1 / yes.
data-hads-title: Сюда попадёт заголовок объявления.
data-hads-text: Сюда попадёт текст объявления.
data-hads-url: Ссылка объявления (href). Пустой <a> — домен рекламодателя; свой текст или вложенные title/text/image не затираем. Пишите <a data-hads-url></a> (не <a …/>): у <a> нет самозакрытия, лишний пустой якорь скрипт уберёт.
data-hads-source: Доменное имя сайта, которому принадлежит объявление. Хук внутри ссылки: <a data-hads-url><svg…></svg><span data-hads-source></span></a>. Если внутри только элементы без текста и без этого хука — скрипт сам допишет <span class="hads-source">.
data-hads-attribution: Необязательная ссылка на HADS. Пустой <a data-hads-attribution></a> станет ссылкой на hads.dev с текстом hads.dev; свой текст внутри ссылки сохранится.
data-hads-image: URL картинки (src для <img>). JPEG/PNG/WebP, до 100 КБ. Лучше 16:9; в слоте — object-fit: cover.

Картинки

Картинка в объявлении необязательна. Если указана — движок проверяет файл, заливает в хранилище и подставляет публичный URL.

Форматы: JPEG, PNG, WebP.
Размер файла — не больше 100 КБ.
Рекомендуем 16:9 (например 1200×675). Слоты в примерах: карточка 16:9, превью в строке 1:1 — cover обрежет края, важное держите в центре.
Исходный URL должен быть http(s); после загрузки в объявлении будет URL из CDN.
В вёрстке слота задайте рамку (16:9 или 1:1) и object-fit: cover — одна картинка подстроится под разные слоты без искажений.

/* Fit any source size into the slot frame */
[data-hads-image]{
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
  object-position: center;
}

Вёрстка слота

Контент подставляется асинхронно. Заранее зафиксируйте геометрию блока — страница не будет прыгать после загрузки объявления.

Задайте слоту желаемый размер: min-height и при необходимости max-width, чтобы место под рекламу было зарезервировано сразу.
Для картинки всегда задавайте рамку (aspect-ratio или width/height) и object-fit: cover — кадр не разъедется после появления src.
Ограничьте число строк у заголовка и текста (line-clamp) и задайте min-height — блоки с разной длиной копирайта останутся ровными.
Стилируйте пустой слот так же, как заполненный: те же отступы и высота, пока скрипт не подставит данные.
Внутрь хуков (title/text) удобно положить скелетон — серые полоски-плейсхолдеры: скрипт заменяет содержимое целиком, и они исчезнут после загрузки.

/* Reserve space before the ad loads */
[data-hads-slot]{
  min-height: 7.5rem;
}

[data-hads-slot] [data-hads-image]{
  aspect-ratio: 16 / 9;
  width: 100%;
  object-fit: cover;
}

[data-hads-slot] [data-hads-title]{
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
  min-height: 2.6em;
}

[data-hads-slot] [data-hads-text]{
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow: hidden;
  min-height: 4.2em;
}

.hads-unit-skeleton{
  display: block;
  height: 0.75rem;
  border-radius: 999px;
  background: #e1e5ee;
}

.hads-unit-skeleton--title{ width: 72%; height: 1rem; }
.hads-unit-skeleton--text{ width: 100%; margin-top: 0.45rem; }
.hads-unit-skeleton--text-short{ width: 58%; }
.hads-unit-attribution{
  color: #687287; font-size: 0.72rem; font-weight: 600;
  letter-spacing: 0.05em; text-decoration: none; text-transform: uppercase;
}
.hads-unit-attribution:hover{ color: #4f5ff5; }

Пример слота со скелетоном внутри хуков:

<aside data-hads-slot="inline" class="hads-unit hads-unit--inline">
  <a data-hads-attribution class="hads-unit-attribution">Реклама от HADS</a>
  <strong data-hads-title>
    <span class="hads-unit-skeleton hads-unit-skeleton--title" aria-hidden="true"></span>
  </strong>
  <p data-hads-text>
    <span class="hads-unit-skeleton hads-unit-skeleton--text" aria-hidden="true"></span>
    <span class="hads-unit-skeleton hads-unit-skeleton--text hads-unit-skeleton--text-short" aria-hidden="true"></span>
  </p>
  <a data-hads-url></a>
</aside>

Готовые слоты

Выберите формат, посмотрите превью и скопируйте HTML, Tailwind или CSS. В разметке уже есть скелетоны внутри title/text — скрипт заменит их на объявление.

Текстовый блок

Классика в ленте статьи: метка, заголовок, текст и ссылка.

<aside data-hads-slot="inline" class="hads-unit hads-unit--inline">
  <a data-hads-attribution class="hads-unit-attribution">Реклама от HADS</a>
  <strong data-hads-title><span class="hads-unit-skeleton hads-unit-skeleton--title" aria-hidden="true"></span></strong>
  <p data-hads-text><span class="hads-unit-skeleton hads-unit-skeleton--text" aria-hidden="true"></span>
    <span class="hads-unit-skeleton hads-unit-skeleton--text hads-unit-skeleton--text-short" aria-hidden="true"></span></p>
  <a data-hads-url></a>
</aside>

Карточка с картинкой

Если у объявления есть изображение — вертикальная карточка.

<aside data-hads-slot="card" class="hads-unit hads-unit--card">
  <a data-hads-attribution class="hads-unit-attribution">Реклама от HADS</a>
  <img data-hads-image alt="" />
  <strong data-hads-title><span class="hads-unit-skeleton hads-unit-skeleton--title" aria-hidden="true"></span></strong>
  <p data-hads-text><span class="hads-unit-skeleton hads-unit-skeleton--text" aria-hidden="true"></span>
    <span class="hads-unit-skeleton hads-unit-skeleton--text hads-unit-skeleton--text-short" aria-hidden="true"></span></p>
  <a data-hads-url></a>
</aside>

Строка с превью

Компактный горизонтальный блок для списков и сайдбара.

<aside data-hads-slot="row" class="hads-unit hads-unit--row">
  <img data-hads-image alt="" />
  <div class="hads-unit-body">
    <a data-hads-attribution class="hads-unit-attribution">Реклама от HADS</a>
    <strong data-hads-title><span class="hads-unit-skeleton hads-unit-skeleton--title" aria-hidden="true"></span></strong>
    <p data-hads-text><span class="hads-unit-skeleton hads-unit-skeleton--text" aria-hidden="true"></span>
    <span class="hads-unit-skeleton hads-unit-skeleton--text hads-unit-skeleton--text-short" aria-hidden="true"></span></p>
    <a data-hads-url></a>
  </div>
</aside>

Тизер-ссылка

Заголовок сам является ссылкой — минимум шума.

<aside data-hads-slot="teaser" class="hads-unit hads-unit--teaser">
  <a data-hads-attribution class="hads-unit-attribution">Реклама от HADS</a>
  <a data-hads-url><strong data-hads-title><span class="hads-unit-skeleton hads-unit-skeleton--title" aria-hidden="true"></span></strong></a>
  <p data-hads-text><span class="hads-unit-skeleton hads-unit-skeleton--text" aria-hidden="true"></span>
    <span class="hads-unit-skeleton hads-unit-skeleton--text hads-unit-skeleton--text-short" aria-hidden="true"></span></p>
</aside>

Узкая колонка

Для боковой колонки: короткий текст и явный переход.

<aside data-hads-slot="rail" class="hads-unit hads-unit--rail">
  <a data-hads-attribution class="hads-unit-attribution">Реклама от HADS</a>
  <strong data-hads-title><span class="hads-unit-skeleton hads-unit-skeleton--title" aria-hidden="true"></span></strong>
  <p data-hads-text><span class="hads-unit-skeleton hads-unit-skeleton--text" aria-hidden="true"></span>
    <span class="hads-unit-skeleton hads-unit-skeleton--text hads-unit-skeleton--text-short" aria-hidden="true"></span></p>
  <a data-hads-url></a>
</aside>