HADS

HADS / DOCS

Documentation

One script and your own HTML. HADS only fills title, text, url, and image — styling stays yours.

Quick start

  1. Add a site Register the domain in the dashboard — you get a site key after moderation.
  2. Paste the script Once on pages where the block should appear.
  3. Place a slot Copy one of the examples below and tweak CSS if needed.

Script

Replace with your site key from the dashboard. The script is async and finds data-hads-slot elements.

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

TUI and CLI programs

Terminal clients pull ads from the same pool as websites: one GET request per run, the response is ready-to-print text for stdout. The impression counts immediately, no session needed.

  1. Add a TUI / CLI site Pick the “TUI / CLI” type in the cabinet. Instead of a domain, enter a program identifier, e.g. myapp-cli.
  2. Request an ad One curl or one HTTP request from your program. One request is one impression, no dedupe.
  3. Clicks via the short link The response carries a url like /v1/click/… Open it in the visitor's browser: it redirects to the advertiser and the click counts. 
curl "https://api.hads.dev/v1/serve?site_key=YOUR_SITE_KEY&format=ansi"

Formats

  • json — the full payload, same as for websites (default)
  • text — plain text for stdout and pipes
  • ansi — the same, with colors and a clickable link
curl "https://api.hads.dev/v1/serve?site_key=YOUR_SITE_KEY&format=ansi&topic=programming"

Parameters

site_key
site key of the site, from the cabinet (required)
slot
placement name inside your program — for analytics
topic
topic hint: catalog at /v1/topics
allow_self
allow your own ads to serve (true/1)
format
json | text | ansi — response format
url=$(curl -s "https://api.hads.dev/v1/serve?site_key=YOUR_SITE_KEY" | jq -r .ad.url); open "$url"

Empty pool

When no ad fits: json returns ad: null, text and ansi return an empty 204. Your script should just exit.

Attributes

The script fills hooks inside the slot. With no hooks it builds a simple link. Ad title and text are required; image is optional.

data-hads-slot
Slot container. The value is the slot name (for your analytics and layout).
data-hads-topic
Free-form topical hint for the page/context. The engine maps it to the topic catalog in the background and prefers matching ads; blank, not-yet-mapped, or unmatched hints are ignored.
data-hads-allow-self
Allow ads from your other sites in the same account (the current site is still excluded). Presence of the attribute, or true / 1 / yes, enables it.
data-hads-title
Filled with the ad title.
data-hads-text
Filled with the ad body text.
data-hads-url
Ad link (href). Empty <a> gets the advertiser domain; your own text or nested title/text/image hooks are kept. Prefer <a data-hads-url></a> (not <a …/>): <a> is not void; the script drops spare empty anchors from self-closing markup.
data-hads-source
Domain name of the site that owns the ad. Hook inside the link: <a data-hads-url><svg…></svg><span data-hads-source></span></a>. If the link only has element children (no text, no source hook), the script appends <span class="hads-source">.
data-hads-attribution
Optional credit link to HADS. An empty <a data-hads-attribution></a> becomes a hads.dev link labelled hads.dev; custom text inside the link is preserved.
data-hads-image
Image URL (src on <img>). JPEG/PNG/WebP, max 100 KB. Prefer 16:9; use object-fit: cover in the slot.

Images

An image on the ad is optional. When set, the engine validates the file, uploads it to storage, and replaces the URL with a public CDN link.

  • Formats: JPEG, PNG, WebP.
  • File size must be 100 KB or less.
  • Prefer 16:9 (e.g. 1200×675). Example slots: card 16:9, row thumb 1:1 — cover crops the edges, keep the subject centered.
  • Source URL must be http(s); after upload the ad stores the CDN URL.
  • In slot CSS set a frame (16:9 or 1:1) and object-fit: cover so one image fits different slots without stretching.
/* Fit any source size into the slot frame */
[data-hads-image]{
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
  object-position: center;
}

Slot layout

Ad content is injected asynchronously. Lock the slot geometry up front so the page does not jump when the creative arrives.

  • Give the slot a target size: min-height and max-width if needed, so space for the ad is reserved immediately.
  • Always size the image frame (aspect-ratio or width/height) with object-fit: cover — the box stays stable when src appears.
  • Clamp title and body lines and set min-height so units with different copy length stay even.
  • Style an empty slot like a filled one: same padding and height until the script fills the hooks.
  • Put a skeleton — gray placeholder bars — inside the title/text hooks: the script replaces their content entirely, so the bars go away when the ad arrives.
/* 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; }

Example slot with a skeleton inside the hooks:

<aside data-hads-slot="inline" class="hads-unit hads-unit--inline">
  <a data-hads-attribution class="hads-unit-attribution">Ads by 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>

Ready-made slots

Pick a format, check the preview, then copy HTML, Tailwind, or CSS. The markup already includes skeletons inside title/text — the script replaces them with the ad.

Text block

Classic in-article unit: label, title, body, and link.

<aside data-hads-slot="inline" class="hads-unit hads-unit--inline">
  <a data-hads-attribution class="hads-unit-attribution">Ads by 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>

Image card

Vertical card when the ad includes an image.

<aside data-hads-slot="card" class="hads-unit hads-unit--card">
  <a data-hads-attribution class="hads-unit-attribution">Ads by 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>

Row with thumb

Compact horizontal block for lists and sidebars.

<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">Ads by 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>

Teaser link

The title is the link — minimal chrome.

<aside data-hads-slot="teaser" class="hads-unit hads-unit--teaser">
  <a data-hads-attribution class="hads-unit-attribution">Ads by 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>

Narrow rail

For a side column: short copy and a clear CTA.

<aside data-hads-slot="rail" class="hads-unit hads-unit--rail">
  <a data-hads-attribution class="hads-unit-attribution">Ads by 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>