AD, technically: how it works and how to integrate

What it is

What AD is, and who it is for

AD is a direct ad server: no auction and no black box. A publisher sells the ad space on a site they already run; an advertiser picks the exact zones, sets the targeting and launches. One account can play either role — or both.

Access

How to get in

Sign in on forhosting.com and choose “Manage my AD” in your account menu. The panel opens with a short session — a credential that expires in minutes (never more than 60) and never leaves a permanent key in the browser. When it expires, reopen it from the same menu.

For integrations, create an API key from the panel (Profile) or with POST /tenants/:id/keys. Two scopes: tenant (full access to your own account) and read (read-only, for dashboards and bots). The key is shown once; if it is lost, create another and revoke the old one.

Our staff can open your panel “as client” to help you: that session lasts at most 15 minutes and carries the name of the person who opened it. The house never operates your account with a permanent key.

Advertisers

Campaigns and targeting

A campaign is the container: name, dates, optional budgets and the targeting shared by its creatives. It is born as a draft; you set it active, pause it, or end it. Only active creatives of an active campaign are served — pausing the campaign stops delivery at once.

Between the eligible creatives the engine picks at random, weighted by the weight you give each one. A creative with a delivery limit is paced: every 5 minutes its weight is re-tuned so the budget spreads across the campaign's days instead of burning out in the morning. Pacing only slows down — it can never invent traffic.

A creative only serves on a zone where it has a paid order (see “Buying placements”). Campaign, creative, zone and order are all visible in the panel (Campaigns, Creatives, Buy placements).

Advertisers

Creatives: six types, one tag

Every creative has a click URL, an optional fixed size and a weight. The limits in this table are the ones the API enforces on upload — they are read from the code, not written here.

The HTML5 contract

Your index.html is loaded in an iframe with the click destination in the query string as clickTag. Read it and use it as the href of your clickable area — that URL is signed and counts the click; a hand-written link does not.

// index.html — the click goes where the engine says
var clickTag = new URLSearchParams(location.search).get("clickTag");
document.getElementById("ad").href = clickTag;

If your creative needs to grow, tell the page its real height with postMessage. The tag also tells the creative the width of the slot on load and on every resize, and sends visible the first time the slot enters the viewport — the right moment to start an animation. Heights up to 10000 px are applied.

// creative → page: ask for the real height (applied up to 10000 px)
parent.postMessage({ fh: "resize", nh: document.documentElement.scrollHeight }, "*");

// page → creative: { fh: "size" | "visible" }
window.addEventListener("message", function (ev) {
  if (ev.data && ev.data.fh === "visible") { /* start your animation */ }
});

A minimal creative that does both is ready to upload as-is: download the example ZIP

Macros for script creatives

In a script creative the engine replaces these placeholders when the zone is published. A template from the panel is the same thing with extra placeholders you fill in a form.

Third-party tracking and consent

Any creative can carry a tracking code (a pixel or script from a measurement vendor). It is emitted after the ad with every src turned into data-src, so nothing loads until the tag allows it.

If you set the vendor's IAB TCF v2 id, the code loads only after the visitor's consent for that vendor, with ${GDPR} and ${GDPR_CONSENT_n} filled in. The tag waits up to 10 seconds for the site's consent manager; without a vendor id the code loads as a plain element.

Manual review

Every creative is born en_revision and is reviewed by a person before it can serve. Approved, you set it active or paused; rejected, you see the reason and can edit and resubmit. Nothing from an unreviewed creative — not the markup, not the script, not the tracking code — ever reaches a visitor.

Changing the click URL, the content or the file of an approved creative sends it back to review: what was approved is what gets served, never something else.

Advertisers

Buying placements

The marketplace lists every zone on sale: site, size, formats accepted, sale model and the price the publisher set. You choose a zone, a creative of a format the zone accepts, a budget and a start date. The quote and the charge use the same formula:

The minimum order is $5; the quote refuses anything below. An order is a prepaid purchase of volume — the money moves once, when you buy. Send an idempotencyKey and a retried request returns the same order instead of a second one.

How you pay

When an order is marked paid, 80% of its final price is credited to the publisher of the zone — on the whole order, not prorated by delivery. The zone is republished immediately and your creative starts serving in the next minute.

Publishers

Sites, zones, tag and payouts

Sites

Register a site by domain (Become a publisher). It is born pending and a person verifies it before its zones can sell — an unverified domain cannot earn a share. Retiring a site starts a 90-day cooldown on the domain: nobody else can register it meanwhile and inherit its history.

Zones

A zone is the sellable slot: a name, a size in pixels (or -1 for responsive width), the formats it accepts, a sale model with its price, and whether it is on sale in the marketplace. You can set a fallback creative of your own that serves when nothing else is eligible — it skips targeting and caps.

Two optional behaviours run in the visitor's browser: auto-refresh (a new request every N seconds, minimum 5; a hidden tab never refreshes, and a slot that comes back empty keeps the previous ad) and parameter forwarding (the page's query string travels with the click to the advertiser's destination). An interstitial zone also declares which links trigger the overlay — by default p a, nav a, h2 a — and the seconds before it can be closed.

The tag

Paste it where the ad should appear. The zone id comes from the panel (Sites & zones). The same tag serves every format the zone accepts; an interstitial zone uses the standard tag too.

Standard (one div and one script, asynchronous):

<div data-fh-ad="zon_XXXXXXXXXXXXXXXXXXXXXXXX"></div>
<script src="https://api.ad.forhosting.com/ad-tag.js" async></script>

Legacy, for CMSs that cannot run asynchronous scripts:

<script src="https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=js"></script>

Text link: a URL that counts the impression and redirects to the advertiser:

https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=link

The tag updates itself: its URL carries no version and never changes, so an improvement on our side reaches every site within about undefined minutes and nobody edits a template (it serves v6 today, in the x-tag-version header). It waits for your page to finish loading before requesting anything, so ads never compete with your own content. Its only marks in your page are the data-fh-ad attribute and the overlay id — checked against the common ad-blocking lists, with zero matches. Frequency caps use a first-party cookie.

Payouts

Your 80% share of each paid order accrues in the panel (Payouts). When the accrued amount reaches $10, request the payout with the method from your profile (paypal, bank, other); our staff pays outside the panel and records the reference.

States: accrued → requested → processing → paid; a failed disbursement goes back to you with the reason so you can request it again with corrected details.

Everyone

Reports

Impressions, clicks and video start/end are counted at the edge, on every request. Before they count, traffic is filtered: known crawlers by user agent, datacenter networks, requests with a very low bot score, and any IP repeating the same request within 2 seconds. A filtered request still gets its ad or its redirect — only the counter is protected.

Every 5 minutes the counts are rolled up into daily rows per creative, zone and referrer host. The current day can lag by up to that much; closed days never change.

The panel (Reports) shows totals and a daily series, CTR (clicks ÷ impressions × 100) and eCPM (value delivered × 1000 ÷ impressions), for the advertiser side or the publisher side, and a top list by creative, zone, campaign, site or referrer host. Only the host of the referrer is stored, never the URL.

Integrate

API reference

Base URL https://api.ad.forhosting.com. Send your key as a Bearer token; bodies and responses are JSON. Every answer has the shape {"success":true,"data":…} or {"success":false,"error":{"code","message"}} with the matching HTTP status.

curl https://api.ad.forhosting.com/me \
  -H "Authorization: Bearer ads_ten_…"

Credential scopes

A tenant, read or session credential always operates its own account — a tenantId sent by the client is ignored. An id that belongs to someone else returns 404, not 403: the API never confirms that it exists.

Routes

Every route the service announces, with the scope the router requires — derived from the router itself on each build.

public: no credential — the serving path · any: any valid credential, on its own account · read: tenant, session or read · write: tenant or session (read is refused) · system: the house only

Errors worth knowing: 401 unauthorized (missing or expired credential), 403 forbidden (the scope cannot do this), 404 not_found, 400 bad_request with the reason in the message, 409 conflict (a state transition that is not allowed), 402 insufficient_balance when paying an order, and 503 payments_disabled if sales are paused.

FAQ

A few technical questions