AD, technisch: wie es funktioniert und wie man es einbindet

Was es ist

Was AD ist und für wen

AD ist ein direkter Ad-Server: keine Auktion, keine Black Box. Ein Publisher verkauft die Werbeflächen einer Website, die er bereits betreibt; ein Werbetreibender wählt die genauen Zonen, stellt das Targeting ein und startet. Ein Konto kann die eine oder die andere Rolle spielen — oder beide.

Zugang

Wie man hineinkommt

Melden Sie sich auf forhosting.com an und wählen Sie „Mein AD verwalten“ im Kontomenü. Das Panel öffnet sich mit einer kurzen Sitzung — einem Zugangsschlüssel, der in Minuten abläuft (nie mehr als 60) und keinen dauerhaften Schlüssel im Browser hinterlässt. Läuft sie ab, öffnen Sie das Panel erneut aus demselben Menü.

Für Integrationen erstellen Sie einen API-Schlüssel im Panel (Profil) oder mit POST /tenants/:id/keys. Zwei Geltungsbereiche: tenant (voller Zugriff auf Ihr eigenes Konto) und read (nur lesen, für Dashboards und Bots). Der Schlüssel wird einmal angezeigt; geht er verloren, erstellen Sie einen neuen und widerrufen den alten.

Unser Team kann Ihr Panel „als Kunde“ öffnen, um Ihnen zu helfen: Diese Sitzung dauert höchstens 15 Minuten und trägt den Namen der Person, die sie geöffnet hat. Das Haus bedient Ihr Konto nie mit einem dauerhaften Schlüssel.

Werbetreibende

Kampagnen und Targeting

Die Kampagne ist der Container: Name, Daten, optionale Budgets und das Targeting, das ihre Werbemittel teilen. Sie entsteht als draft; Sie setzen sie auf active, pausieren oder beenden sie. Ausgeliefert werden nur aktive Werbemittel einer aktiven Kampagne — das Pausieren der Kampagne stoppt die Auslieferung sofort.

Unter den zulässigen Werbemitteln wählt die Engine zufällig, gewichtet nach dem Gewicht, das Sie jedem geben. Ein Werbemittel mit Auslieferungslimit wird gepaced: alle 5 Minuten wird sein Gewicht nachjustiert, damit sich das Budget über die Kampagnentage verteilt, statt morgens auszubrennen. Pacing bremst nur — es erfindet nie Traffic.

Ein Werbemittel läuft nur in einer Zone, in der es eine bezahlte Bestellung hat (siehe „Plätze kaufen“). Kampagne, Werbemittel, Zone und Bestellung sind im Panel sichtbar (Kampagnen, Werbemittel, Plätze kaufen).

Werbetreibende

Werbemittel: sechs Typen, ein Tag

Jedes Werbemittel hat eine Klick-URL, eine optionale feste Größe und ein Gewicht. Die Limits in dieser Tabelle sind die, die die API beim Hochladen durchsetzt — sie werden aus dem Code gelesen, nicht hier geschrieben.

Der HTML5-Vertrag

Ihre index.html wird in einem iframe geladen, mit dem Klickziel im Query-String als clickTag. Lesen Sie es aus und verwenden Sie es als href Ihrer klickbaren Fläche — diese URL ist signiert und zählt den Klick; ein handgeschriebener Link zählt nicht.

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

Muss Ihr Werbemittel wachsen, teilen Sie der Seite seine tatsächliche Höhe per postMessage mit. Das Tag teilt dem Werbemittel außerdem beim Laden und bei jeder Größenänderung die Breite des Platzes mit und sendet visible, sobald der Platz zum ersten Mal in den Viewport kommt — der richtige Moment, eine Animation zu starten. Höhen bis 10000 px werden übernommen.

// 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 */ }
});

Ein minimales Werbemittel, das beides tut, bereit zum Hochladen wie es ist: Beispiel-ZIP herunterladen

Makros für Script-Werbemittel

In einem script-Werbemittel ersetzt die Engine diese Platzhalter beim Veröffentlichen der Zone. Eine Vorlage aus dem Panel ist dasselbe mit zusätzlichen Platzhaltern, die Sie in einem Formular ausfüllen.

Drittanbieter-Tracking und Einwilligung

Jedes Werbemittel kann einen Tracking-Code tragen (ein Pixel oder Script eines Messdienstleisters). Er wird nach der Anzeige ausgegeben, wobei jedes src zu data-src wird, damit nichts lädt, bevor das Tag es erlaubt.

Geben Sie die IAB-TCF-v2-ID des Anbieters an, lädt der Code erst nach der Einwilligung des Besuchers für diesen Anbieter, mit ausgefülltem ${GDPR} und ${GDPR_CONSENT_n}. Das Tag wartet bis zu 10 Sekunden auf den Consent-Manager der Website; ohne Anbieter-ID lädt der Code als gewöhnliches Element.

Manuelle Prüfung

Jedes Werbemittel entsteht als en_revision und wird von einer Person geprüft, bevor es ausliefern darf. Freigegeben setzen Sie es auf active oder paused; abgelehnt sehen Sie den Grund und können es bearbeiten und erneut einreichen. Nichts aus einem ungeprüften Werbemittel — weder Markup, noch Script, noch Tracking-Code — erreicht je einen Besucher.

Das Ändern der Klick-URL, des Inhalts oder der Datei eines freigegebenen Werbemittels schickt es zurück in die Prüfung: Ausgeliefert wird, was freigegeben wurde, nie etwas anderes.

Werbetreibende

Plätze kaufen

Der Marktplatz listet jede Zone, die zum Verkauf steht: Website, Größe, zulässige Formate, Verkaufsmodell und der vom Publisher gesetzte Preis. Sie wählen eine Zone, ein Werbemittel in einem Format, das die Zone erlaubt, ein Budget und ein Startdatum. Angebot und Abbuchung verwenden dieselbe Formel:

Die Mindestbestellung beträgt $5; das Angebot lehnt alles darunter ab. Eine Bestellung ist ein vorausbezahlter Volumenkauf — das Geld bewegt sich einmal, beim Kauf. Senden Sie einen idempotencyKey, und eine wiederholte Anfrage liefert dieselbe Bestellung statt einer zweiten.

Wie Sie bezahlen

Wird eine Bestellung als bezahlt markiert, werden 80% ihres Endpreises dem Publisher der Zone gutgeschrieben — auf die gesamte Bestellung, nicht anteilig nach Auslieferung. Die Zone wird sofort neu veröffentlicht und Ihr Werbemittel läuft ab der nächsten Minute.

Publisher

Websites, Zonen, Tag und Auszahlungen

Websites

Legen Sie eine Website über ihre Domain an (Publisher werden). Sie entsteht als ausstehend und wird von einer Person geprüft, bevor ihre Zonen verkaufen dürfen — eine ungeprüfte Domain kann keinen Anteil verdienen. Das Zurückziehen einer Website startet eine 90-tägige Sperrfrist für die Domain: Niemand sonst kann sie in dieser Zeit anlegen und ihre Historie erben.

Zonen

Die Zone ist der verkäufliche Platz: ein Name, eine Größe in Pixeln (oder -1 für anpassbare Breite), die zulässigen Formate, ein Verkaufsmodell mit seinem Preis und ob sie im Marktplatz zum Verkauf steht. Sie können ein eigenes Fallback-Werbemittel setzen, das ausliefert, wenn nichts anderes zulässig ist — es überspringt Targeting und Caps.

Zwei optionale Verhalten laufen im Browser des Besuchers: Auto-Refresh (alle N Sekunden eine neue Anfrage, mindestens 5; ein verborgener Tab aktualisiert nie, und ein Platz, der leer zurückkommt, behält die vorherige Anzeige) und Parameterweitergabe (der Query-String der Seite reist mit dem Klick zum Ziel des Werbetreibenden). Eine Interstitial-Zone legt zudem fest, welche Links das Overlay auslösen — standardmäßig p a, nav a, h2 a — und die Sekunden, bevor es geschlossen werden kann.

Das Tag

Fügen Sie es dort ein, wo die Anzeige erscheinen soll. Die Zonen-ID steht im Panel (Websites & Zonen). Dasselbe Tag liefert jedes Format aus, das die Zone erlaubt; auch eine Interstitial-Zone verwendet das Standard-Tag.

Standard (ein div und ein script, asynchron):

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

Legacy, für CMS, die keine asynchronen Scripts ausführen:

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

Textlink: eine URL, die die Impression zählt und zum Werbetreibenden weiterleitet:

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

Das Tag aktualisiert sich selbst: Seine URL trägt keine Version und ändert sich nie, sodass eine Verbesserung von uns alle Websites in rund undefined Minuten erreicht und niemand ein Template bearbeitet (heute liefert es v6, im Header x-tag-version). Es wartet, bis Ihre Seite fertig geladen ist, bevor es etwas anfordert — Anzeigen konkurrieren nie mit Ihren Inhalten. Seine einzigen Spuren auf Ihrer Seite sind das Attribut data-fh-ad und die Overlay-ID — gegen die gängigen Blockierlisten geprüft, ohne einen einzigen Treffer. Frequenzobergrenzen nutzen ein First-Party-Cookie.

Auszahlungen

Ihr Anteil von 80% an jeder bezahlten Bestellung sammelt sich im Panel (Auszahlungen). Erreicht der Betrag $10, fordern Sie die Auszahlung mit der Methode aus Ihrem Profil an (paypal, bank, other); unser Team zahlt außerhalb des Panels aus und hinterlegt die Referenz.

Zustände: accrued → requested → processing → paid; eine fehlgeschlagene Auszahlung geht mit dem Grund an Sie zurück, damit Sie sie mit korrigierten Daten erneut anfordern können.

Für alle

Berichte

Impressionen, Klicks und Video-Start/-Ende werden am Edge gezählt, bei jeder Anfrage. Bevor sie zählen, wird der Traffic gefiltert: bekannte Crawler am User-Agent, Rechenzentrums-Netze, Anfragen mit sehr niedrigem Bot-Score und jede IP, die dieselbe Anfrage innerhalb von 2 Sekunden wiederholt. Eine gefilterte Anfrage bekommt trotzdem ihre Anzeige oder Weiterleitung — geschützt wird nur der Zähler.

Alle 5 Minuten werden die Zählungen zu Tageszeilen pro Werbemittel, Zone und Referrer-Host zusammengefasst. Der laufende Tag kann bis zu so lange hinterherhinken; abgeschlossene Tage ändern sich nie.

Das Panel (Berichte) zeigt Summen und eine Tagesreihe, die CTR (Klicks ÷ Impressionen × 100) und den eCPM (gelieferter Wert × 1000 ÷ Impressionen), für die Werbetreibenden- oder die Publisher-Seite, sowie eine Top-Liste nach Werbemittel, Zone, Kampagne, Website oder Referrer-Host. Gespeichert wird nur der Host des Referrers, nie die URL.

Einbinden

API-Referenz

Basis-URL https://api.ad.forhosting.com. Senden Sie Ihren Schlüssel als Bearer-Token; Anfragekörper und Antworten sind JSON. Jede Antwort hat die Form {"success":true,"data":…} oder {"success":false,"error":{"code","message"}} mit dem passenden HTTP-Status.

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

Geltungsbereiche der Zugangsschlüssel

Ein tenant-, read- oder session-Schlüssel arbeitet immer auf seinem eigenen Konto — eine vom Client gesendete tenantId wird ignoriert. Eine ID, die jemand anderem gehört, liefert 404, nicht 403: Die API bestätigt nie, dass sie existiert.

Routen

Jede Route, die der Dienst ankündigt, mit dem Bereich, den der Router verlangt — bei jedem Build aus dem Router selbst abgeleitet.

öffentlich: ohne Schlüssel — der Auslieferungspfad · beliebig: jeder gültige Schlüssel, auf dem eigenen Konto · lesen: tenant, session oder read · schreiben: tenant oder session (read wird abgelehnt) · system: nur das Haus

Fehler, die man kennen sollte: 401 unauthorized (Schlüssel fehlt oder ist abgelaufen), 403 forbidden (der Bereich darf das nicht), 404 not_found, 400 bad_request mit dem Grund in der Nachricht, 409 conflict (ein nicht erlaubter Zustandswechsel), 402 insufficient_balance beim Bezahlen einer Bestellung und 503 payments_disabled, wenn der Verkauf pausiert ist.

FAQ

Technische Fragen