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, paused oder — wenn sie vorbei ist — ended. Ausgeliefert werden nur aktive Werbemittel einer aktiven Kampagne — das Pausieren der Kampagne stoppt die Auslieferung sofort.

Unter den zulässigen Kampagnen würfelt die Engine nicht: Sie wechselt sich ab. Sie liefert die eine aus, dann die andere, und erst wenn beide gleichauf sind, entscheidet das Gewicht, das Sie jedem Werbemittel gegeben haben — demselben Besucher zehnmal hintereinander dieselbe Kampagne zu zeigen, verkauft nichts. Die Abwechslung wird pro Besucher und pro Zone gezählt, im Browser des Besuchers selbst; sind Cookies blockiert, fällt sie auf die gewichtete Auslosung zurück. Ein Werbemittel mit Auslieferungslimit wird zudem 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.

Mehrere Ziele in einem Werbemittel

Ein Werbemittel kann neben seiner Haupt-Klick-URL bis zu 8 benannte Ziele tragen — etwa eine App-Store-Schaltfläche und eine Google-Play-Schaltfläche in derselben Anzeige. Jedes trägt eine ID aus höchstens 20 Kleinbuchstaben; main ist für die Haupt-URL reserviert.

In einem HTML5-Werbemittel kommen sie im Query-String als clickTag_<id> an, neben dem üblichen clickTag; in einem script-Werbemittel schreiben Sie [CLICKTAG:<id>]. Jedes davon läuft über den Klick-Tracker, sodass sie sich zur Gesamtzahl summieren und sich in den Berichten pro Schaltfläche aufschlüsseln.

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 prüft sich selbst: veröffentlichen Sie das Token, das wir Ihnen geben, unter /.well-known/fh-ad-site-verification.txt oder auf der Startseite, fordern Sie die Prüfung an, und die Website schaltet sich von selbst frei — ohne Warteschlange und ohne dass hier jemand erst hinsehen muss. Eine ungeprüfte Domain kann keinen Anteil verdienen. Eine Website stillzulegen startet eine Sperrfrist von 90 Tagen auf der 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).

Wie das Interstitial ausgelöst wird

Das Overlay ist eine Eigenschaft der Zone, nicht der Website: dafür muss nichts eingefügt werden — der Tag baut sich, was er braucht — und Sie ändern den Rhythmus in dem Panel, in dem Sie kaufen. Vier Modi:

Ein fester Rhythmus ermüdet den Besucher am 30. Tag genauso wie am ersten — dafür ist der gestaffelte Kalender da: Er holt die erste Impression früh und tritt danach zurück. Der Zähler lebt im Browser des Besuchers selbst; ist der Speicher blockiert, wird im Arbeitsspeicher weitergezählt, statt dass etwas kaputtgeht.

Wann die Anzeigen angefordert werden — Ihre Website hat Vorrang

Anzeigen dürfen Ihre Website nicht verlangsamen, und die Einstellung liegt hier, nicht in Ihrem HTML. Jede Website wählt, wann das Tag seine erste Anzeige anfordert:

Und während die Anzeige unterwegs ist, bleibt der Platz nicht leer: Das Tag zeichnet einen Platzhalter, und es lernt die Höhe — der erste Besuch reserviert ein vorsichtiges Maß, ab dem zweiten ist der reservierte Platz genau der richtige, sodass die Seite nicht springt, wenn die Anzeige eintrifft. Genau dieses Springen misst Google als Layout Shift, und es ist der übliche Grund, warum ein Werbenetzwerk eine Website ihre Bewertung kostet.

Das Tag

Fügen Sie ihn dort ein, wo die Anzeige erscheinen soll — oder lassen Sie die Zone sagen, wo sie hingehört, und überspringen Sie diesen Schritt ganz (siehe „Wo die Anzeige erscheint“ weiter unten). Die Zonen-Id kommt aus dem Panel (Websites & Zonen). Derselbe Tag bedient jedes Format, das die Zone annimmt; eine Interstitial-Zone verwendet ebenfalls den 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 60 Minuten erreicht und niemand ein Template bearbeitet (heute liefert es v11, 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.

Wiederholt sich dieselbe Position eine Seite hinunter — „alle N Beiträge“ in einem Forum zum Beispiel —, fordert das Tag alle seine Kopien in einer einzigen Anfrage an (bis zu 10), und die Frequenzobergrenze zählt innerhalb dieses Bündels weiter, sodass ein einzelnes Werbemittel nicht jeden Platz der Seite füllen kann. Versteht unsere Seite das Bündel nicht, fällt das Tag auf einen Platz nach dem anderen zurück, statt die Seite leer zu lassen. Eine Zone zu wiederholen wird bei uns angemeldet: in der Regel eine Zone pro Position, denn die Zone ist das, wonach ein Bericht gruppiert.

Wo die Anzeige erscheint — ohne Ihr Theme anzufassen

Eine Zone kann erklären, wo sie hingehört: ein CSS-Selektor (bis zu 300 Zeichen) und eine Position relativ zu dem, was dieser Selektor findet. Den Platz erzeugt das Tag selbst, eine Anzeige zu verschieben kostet also eine Änderung im Panel und keine Bearbeitung Ihres Themes.

Zwei optionale Zahlen steuern die Wiederholung: eine setzt den Platz alle N Treffer (bis 50), und eine Obergrenze begrenzt, wie viele Plätze überhaupt entstehen — standardmäßig 4 bei Wiederholung, höchstens 20. Es gibt immer eine Obergrenze: ein loser Selektor wie p trifft in einem langen Artikel hunderte Male zu, und diese Grenze darf nicht davon abhängen, dass jemand beim Einrichten daran denkt.

Zwei Dinge, die man wissen sollte. Ein data-fh-ad-Div, das Sie selbst ins Theme setzen, gewinnt: das Tag legt keinen zweiten Platz für diese Zone an, Sie können also von einem Verfahren zum anderen wechseln, ohne zwei Impressionen für eine zu bezahlen. Und ein Selektor, der nichts trifft, wirft keinen Fehler — Ihre Seite sieht ohne die Anzeige einfach gut aus und das Panel bleibt grün. Prüfen Sie die Platzierung im Browser, am Desktop und in Handybreite: ein Selektor kann im Artikel existieren und auf der Startseite nicht, oder am Desktop 1360 px messen und auf dem Handy 0.

WordPress: nichts einzufügen

Läuft Ihre Website unter WordPress, gibt es ein Plugin, forhosting-ad. Sie installieren es und es meldet sich selbst an: es veröffentlicht eine Prüfaufgabe auf Ihrer eigenen Domain, wir lesen sie, und die Zugangsdaten werden genau einmal ausgegeben. Sie tippen keinen Schlüssel, keine Id und kein Token — und nachzuweisen, dass Ihnen die Domain gehört, ist nicht dasselbe wie eingeladen zu sein: es wird nichts ausgegeben, solange die Website nicht freigegeben ist.

Ab dann werden die Zonen im Panel verwaltet, Platzierung eingeschlossen. Das Plugin bittet außerdem den Seiten-Cache, den Ihre Website nutzt, die Seiten zu leeren, deren Markup sich geändert hat — es erkennt die üblichen und spricht jeden auf seine Weise an. Eine gecachte Seite ist der häufigste Grund dafür, dass das Tag in Ihrem HTML steht und die Anzeige trotzdem nicht auf dem Bildschirm ist, und auf der Kommandozeile sieht man das nicht: die veraltete Kopie wird nur einem echten Browser ausgeliefert.

Es gibt ein zweites Plugin, forhosting-ad-updater, das ein Paket entgegennimmt und installiert. Das ist konstruktionsbedingt ein Kanal für Fernausführung, deshalb installieren wir es nur auf eigenen Websites; bei Ihnen kommen Aktualisierungen über den eigenen Kanal von WordPress und Sie entscheiden, wann Sie sie anwenden.

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, gruppiert nach einer von sechs Dimensionen:

Jede dieser Ansichten lässt sich zusätzlich nach Kampagne, Werbemittel, Zone, Referrer-Host oder Ziel filtern, und dieselben Zahlen sind über die API verfügbar.

Bevor überhaupt etwas gezählt wird, läuft der Traffic durch den Bot-Filter, den das Haus in einem von drei Modi betreibt: block (der Standard: Gefilterte Anfragen bekommen ihre Anzeige trotzdem, sie zählen nur nicht), log (sie zählen und werden getrennt erfasst, um zu messen, bevor entschieden wird) und off.

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