Documentation

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.

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>

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-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.run link labelled hads.run; 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.

<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>

<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>

<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>

<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>

<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>