Integrationsdokumentation

1. Normale Display-Anzeigen

Banner, Wolkenkratzer, Rechtecke und Native Ads. Kopieren Sie Ihren persönlichen Snippet aus Dashboard → Websites → Ihre Seite → Anzeigencode — er enthält bereits Ihre Website-ID.

Option A — automatische Anzeigen (am einfachsten)

Ein Script-Tag im head. Es findet die besten Anzeigenpositionen direkt auf der Seite (im Artikel, Seitenleiste, unten):

<script src="https://robinsads.com/ads.js" data-website-id="YOUR_WEBSITE_ID" async></script>

Aktivieren Sie zuerst Automatische Anzeigen in den Einstellungen Ihrer Website.

Option B — feste Anzeigenplatzierungen

Fügen Sie das Script einmal ein und platzieren Sie dann einen Anzeigencontainer beliebig:

<!-- in <head> -->
<script src="https://robinsads.com/ads.js" data-website-id="YOUR_WEBSITE_ID" async></script>

<!-- anywhere in your <body> -->
<div class="adsense-ad"
     data-website-id="YOUR_WEBSITE_ID"
     data-ad-type="banner"></div>

Das Attribut data-ad-type kann banner, skyscraper, rectangle, native, anchor, interstitial oder popunder sein. Jede Platzierung fordert nur Anzeigen dieses Formats an, die für Ihre Website zulässig sind (Website-Einstellungen → Zulässige Anzeigenformate). Die beiden Overlay-Formate (interstitial, popunder) werden nicht innerhalb des div gerendert — das div dient als Auslöser, sodass ein Klick oder Tap darauf die Anzeige öffnet (siehe Abschnitt 2).

2. Interstitial- & Popunder-Anzeigen (Overlay- + Neue-Fenster-Formate)

Ein Interstitial deckt den gesamten Bildschirm mit einem Video oder Bild ab. Der Nutzer muss es vollständig ansehen (15–30 s), bevor es geschlossen werden kann — unser Server überprüft diese Wiedergabezeit, sodass Sie Nutzern, die zu Ende schauen, bedenkenlos eine Belohnung geben können. Nach Ende des Videos blendet es in eine Google-Endcard mit Symbol, Namen des Advertisers und einer Call-to-Action-Schaltfläche (Spiel spielen, App herunterladen, Website besuchen), genau wie die Interstitials in Mobile-Spielen. Ein Format, zwei Nutzungsarten:

• Belohnungs-Button — Sie platzieren in Ihrem Spiel/App einen Button "Anzeige ansehen, 50 Münzen erhalten" und gewähren die Belohnung nach der bestätigten Wiedergabe.
• Automatisch — die Anzeige erscheint von selbst einmal pro Besuch zwischen den Seiten; ohne Belohnung.

Schritt 1 — Format aktivieren

In Dashboard → Websites → Ihre Seite → Zulässige Anzeigenformate interstitial ankreuzen und speichern. Damit wird das Format für die Auslieferung auf Ihrer Website zugelassen. Anders als popunder erscheint ein Interstitial nicht allein durch den Schalter — da es eine Vollbild-Übernahme ist, muss es per Code in die Seite eingebunden werden (Schritt 2a oder 2b). So verdeckt eine Seite nie plötzlich den Bildschirm, außer Sie haben es verlangt.

Schritt 2a — Belohnungs-Button (Callback)veraltet

Funktioniert noch, aber für Belohnungen empfehlen wir jetzt die Server-zu-Server-Reward-API (Abschnitt 3) — sie braucht keine Browser Callbacks und ist nicht fälschbar. Das Basis ads.js Script aus Abschnitt 1 muss auf der Seite sein. RobinAds.showInterstitial() zeigt die Anzeige und löst erst auf, nachdem die Wiedergabe auf unserem Server bestätigt wurde:

<button id="watchAdBtn">▶ Watch ad · get 50 coins</button>

<script>
  document.getElementById('watchAdBtn').addEventListener('click', function () {
    RobinAds.showInterstitial().then(function (result) {
      if (result.rewardGranted) {
        // Full watch verified by our server - safe to reward:
        giveRewardToMyUser(result.token);   // coins, unlock, extra life...
      } else {
        console.log('No reward:', result.error || 'closed early');
      }
    }).catch(function (err) {
      console.log(err.message); // e.g. "no ad available right now"
    });
  });
</script>

Das Promise löst mit { rewardGranted, token, rewardId } auf. Während der Anzeige sieht der Nutzer einen Countdown, dann eine Endcard mit Symbol, Namen des Advertisers und Call-to-Action-Button (z. B. "▶ Spiel spielen" oder "⬇ App herunterladen"), den er zum Schließen wegklickt — das ist der eigene Belohnungsweg des Advertisers.

Schritt 2b — automatisches Interstitial

Um das Interstitial von selbst anzuzeigen (ohne Belohnungs-Button), fügen Sie data-interstitial="true" zum ads.js-Tag auf der gewünschten Seite hinzu. Nur so erscheint ein Interstitial automatisch — der Schalter "Zulässige Anzeigenformate" allein löst es nie aus.

<script src="https://robinsads.com/ads.js"
        data-website-id="YOUR_WEBSITE_ID"
        data-interstitial="true" async></script>
<!-- max 1 automatic ad per visit, 2-minute cooldown -->

Schritt 2c — Popunder-Anzeigen (öffnet Advertiser-URL hinter dem aktuellen Tab)

Eine Popunder-Anzeige öffnet die Website des Advertisers in einem neuen Browserfenster hinter dem aktuellen Tab, mit einer Adblock-Form-Submit-Technik. Kein Creative-Bild, kein Countdown, kein Overlay — nur die URL. Der Advertiser muss nur eine Ziel-URL und einen Titel angeben. Abgerechnet mit 0,04 $ pro 1.000 Öffnungen (Publisher verdient 0,02 $ pro 1.000). Der Nutzer bemerkt den Popunder erst, wenn er die aktuelle Seite schließt oder weg navigiert — deshalb ist dieses Format sehr wirksam und robust gegen Adblocker.

Aktivieren Sie popunder bei den Zulässigen Anzeigenformaten, um popunder-taugliche Anzeigen zu laden, und lösen Sie den Popunder dann über einen Button oder ein Platzierungs-div aus:

<!-- 1) your own button (must be inside a click handler) -->
<button id="popunderBtn">Continue to site</button>
<script>
  document.getElementById('popunderBtn').addEventListener('click', function () {
    RobinAds.showPopunder().then(function (result) {
      console.log('Popunder opened:', result.url);
    }).catch(function (err) { console.log(err.message); });
  });
</script>

<!-- 2) placement div used as a click trigger -->
<div data-website-id="YOUR_WEBSITE_ID" data-ad-type="popunder">Continue</div>

Schritt 3 — Wertvolle Belohnungen? Serverseitig prüfenveraltet

Nur Altverfahren — die Reward-API nimmt diese Prüfung für Sie vor. Wenn Sie noch den Browser Callback nutzen und Münzen gegen etwas Reales getauscht werden können, verlassen Sie sich nicht darauf allein: Senden Sie das Token an Ihr Backend und prüfen Sie es gegen unsere API — das ist nicht fälschbar, denn das Token ist eine HMAC-Signatur über die serverseitig gespeicherte Impression:

// Your backend:
const res = await fetch('https://robinsads.com/api/ads/reward/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ impressionId: rewardId, token: tokenFromFrontend }),
});
const { verified } = await res.json();
// if (verified) → credit the user. Store rewardId so it is never granted twice.

3. Reward-API — serverbestätigte Belohnungen, einfach gemacht

Der empfohlene Weg, Ihren Nutzern Belohnungen fürs Ansehenvon Anzeigen zu geben — aufgebaut wie ein Zahlungs-Gateway. Ihr Backend erstellt mit einem REST-Aufruf eine Belohnung, Ihr Besucher sieht die Anzeige in einem von uns gehosteten Popup (Countdown, Betrugsschutz, Abrechnung — null Code Ihrerseits), und Ihr Backend fragt die Belohnung ab, bis sie "verified" meldet. Es gibt keine Browser Callbacks und nichts zu fälschen: nur unser Server kann eine Belohnung auf verified setzen.

Erste Schritte

1. Erstellen Sie ein kostenloses Robins Ads-Konto und lassen Sie Ihre Website zulassen.
2. Öffnen Sie Dashboard → Einstellungen → API-Keys und erstellen Sie einen Schlüssel.
3. Speichern Sie den Schlüssel auf Ihrem Server — er wird nur einmal angezeigt. Nie in Frontend-Code setzen.
4. Senden Sie ihn als Bearer-Token bei jedem API-Aufruf.

Basis-URL & Authentifizierung

https://robinsads.com/api/v1

Authorization: Bearer rbads_live_...

1 — Belohnung erstellen

POST /api/v1/rewards gibt eine popup_url zurück — speichern Sie die Belohnungs-id zusammen mit Ihrem Nutzer/Ihrer Bestellung in Ihrer Datenbank und übergeben Sie die URL dann an den Browser des Besuchers.

curl -X POST https://robinsads.com/api/v1/rewards \
  -H "Authorization: Bearer rbads_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "website_id": "YOUR_WEBSITE_ID",
    "metadata": { "user_id": "user-42", "coins": 50 }
  }'

Antwort:

{
  "id": "rbads_9f2k1a7c3e...",
  "object": "reward",
  "status": "pending",
  "website_id": "69e6aa...",
  "popup_url": "https://robinsads.com/reward/rbads_9f2k1a7c3e...?s=pub_51ab...",
  "reward_id": null,
  "verified_at": null,
  "metadata": { "user_id": "user-42", "coins": 50 },
  "created_at": "2026-09-30T12:00:00.000Z",
  "expires_at": "2026-09-30T12:15:00.000Z"
}

2 — Popup öffnen (Besucherseite)

Das ist die gesamte Frontend-Integration — ein Button, der das Popup per Nutzergeste öffnet. Interstitial, Countdown und Prüfung laufen alle auf unserer Seite:

<button id="watchAdBtn">▶ Watch ad · get 50 coins</button>

<script>
  document.getElementById('watchAdBtn').addEventListener('click', async function () {
    // Ask YOUR backend (it calls POST /api/v1/rewards with the secret key)
    const { popup_url } = await fetch('/my-backend/reward', { method: 'POST' }).then(function (r) { return r.json(); });
    window.open(popup_url, 'robinads_reward', 'width=480,height=640');
    // Then let your backend poll the reward id until it is "verified" - see step 3.
  });
</script>

3 — Belohnungsstatus lesen

GET /api/v1/rewards/:id ist der Weg, den aktuellen Status einer Belohnung zu lesen. Es gibt keine Webhooks — prüfen Sie diesen Endpunkt wann und wie Sie möchten: bei Bedarf, zeitgesteuert, per Cron-Job oder Hintergrund-Worker. Wenn der Status verified ist, gewähren Sie die Belohnung — und speichern Sie die id, damit sie nie zweimal gewährt wird.

• pending — der Besucher hat die Anzeige noch nicht beendet (oder das Popup nicht geöffnet).
• verified — vollständige Wiedergabe von unserem Server bestätigt. Gehen Sie dem Nutzer jetzt gut.
• expired — die Popup-URL wurde nicht innerhalb von 15 Minuten genutzt.
• rejected — ein Abschlussversuch hat die Prüfung nicht bestanden (Betrugsversuch).

// Your backend - poll until a terminal state, then grant exactly once
const KEY = process.env.ROBINADS_API_KEY; // rbads_live_...
const BASE = 'https://robinsads.com/api/v1';

async function rewardStatus(id) {
  const res = await fetch(BASE + '/rewards/' + id, {
    headers: { Authorization: 'Bearer ' + KEY },
  });
  return res.json(); // { id, status, reward_id, verified_at, metadata, ... }
}

const timer = setInterval(async () => {
  const reward = await rewardStatus(savedRewardId);
  if (['verified', 'expired', 'rejected'].includes(reward.status)) {
    clearInterval(timer); // terminal - stop polling
    if (reward.status === 'verified' && !(await alreadyGranted(reward.id))) {
      await giveCoins(reward.metadata.user_id, reward.metadata.coins);
      await markGranted(reward.id);       // dedupe by reward id, forever
    }
  }
}, 5000);

Fehler & Rate-Limits

Fehler werden als JSON {"error": "message"} mit dem passenden HTTP-Statuscode zurückgegeben. Anfragen sind pro IP begrenzt (120 pro Minute). Bei 429 zurückhalten und erneut versuchen.

• 401 — fehlender oder ungültiger API-Key
• 403 — Website nicht bestätigt oder zugelassen
• 404 — Belohnung nicht gefunden (falsche id oder nicht Ihre)
• 429 — Rate-Limit überschritten

4. Telegram Mini-Apps, Bots & Mini-Spiele

Nutzen Sie dieselben Display-Anzeigen und die Vollbild-Belohnungsansicht in einem Telegram-Bot, einer Mini-App oder einem Mini-Spiel — ohne Zusatzcode, ohne einzubindendes SDK. Eine Telegram Mini-App ist nur eine Webseite, also verwenden Sie exakt den ads.js-Snippet aus Abschnitt 1. Wenn sie erkennt, dass sie in Telegram läuft, passt sie sich automatisch an: Anzeigen-Klicks öffnen über die Telegram-Brücke (damit sie nie vom In-App-Browser geschluckt werden), die Vollbild-Anzeige füllt das Mini-App-Viewport, und die native Zurück-Taste schließt eine Anzeige, sobald die nötige Wiedergabe erledigt ist.

Einfache Installation für Betreiber — 4 Schritte

1. Fügen Sie Ihre Mini-App als Website hinzu. Geben Sie in Dashboard → Websites → Website hinzufügen die HTTPS-Domain an, die Ihre Mini-App hostet (dieselbe URL, die Sie BotFather geben). Bestätigen Sie und warten Sie auf die Zulassung — Ihre Anzeigen werden erst ausgeliefert, wenn die Seite zugelassen ist.
2. Schalten Sie die Formate ein. Öffnen Sie Ihre Seite → Zulässige Anzeigenformate, kreuzen Sie banner, rectangle, native und interstitial an und kopieren Sie Ihre Website-ID aus dem Anzeigencode.
3. Richten Sie BotFather auf Ihre Seite. Setzen Sie in @BotFather → Ihr Bot → Bot-Einstellungen → Menü-Button / Mini-App die Web-App-URL auf diese HTTPS-Domain.
4. Fügen Sie ein Script-Tag ein. Setzen Sie den folgenden Snippet in den head Ihrer Mini-App — das Script übernimmt die Telegram-Erkennung für Sie, sodass Sie das Telegram-SDK nie selbst einbinden oder initialisieren.

<!-- 1) once in <head> — works on normal sites AND inside Telegram -->
<script src="https://robinsads.com/ads.js" data-website-id="YOUR_WEBSITE_ID" async></script>

<!-- 2) a banner anywhere in your Mini App -->
<div data-website-id="YOUR_WEBSITE_ID" data-ad-type="banner"></div>

<!-- 3) rewarded full-screen ad: "watch an ad, get a reward" button -->
<button id="watchAdBtn">▶ Watch ad · get coins</button>
<script>
  document.getElementById('watchAdBtn').addEventListener('click', function () {
    RobinAds.showInterstitial().then(function (result) {
      if (result.rewardGranted) {
        giveRewardToMyUser(result.token);   // coins, extra life, unlock… (server-verified)
      }
    }).catch(function (err) {
      console.log(err.message);             // e.g. "no ad available right now"
    });
  });
</script>

Das ist die ganze Integration. Sie ist auf einer normalen Website und in einer Telegram Mini-App identisch — derselbe Snippet, dieselben data-ad-type-Container und derselbe RobinAds.showInterstitial()-Aufruf. Der einzige Unterschied: In Telegram werden Klicks, Vollbild und Zurück-Taste automatisch behandelt.

6. Preise — was Advertiser zahlen, was Sie verdienen

Interstitials sind ein Premium-Format: der Advertiser wird nur berechnet, wenn die Wiedergabezeit vollständig beendet und bestätigt wurde — übersprungene Anzeigen kosten nichts. Deshalb zahlen sie etwas mehr pro Ansicht als normale Display-Anzeigen. Verdienste werden Ihrem Guthaben automatisch gutgeschrieben.

7. Betrugsschutz — eingebaut

• Wiedergabezeit wird serverseitig gemessen — ab dem Moment, in dem die Impression erstellt wurde, nie nach der Uhr des Players. Ein Anspruch, bevor der Countdown wirklich abgelaufen ist, wird abgelehnt.
• Erkennung von verstecktem Tab / Pause — der Countdown im Anzeigenplayer friert ein, wenn der Tab versteckt oder das Video pausiert wird.
• Tägliche Obergrenzen pro Nutzer — ein Besucher kann dieselbe Interstitial eine begrenzte Zahl pro Tag abschließen (Standard 10).
• IP-Missbrauchs-Blockierung — Bots und Schnell-Feuer-IPs werden für Ansichts- und Klick-Ereignisse automatisch blockiert.
• Signierte Belohnungs-Tokens — HMAC-signiert, mit konstanter Zeit verglichen bestätigt; ein wiederholter Anspruch gibt das Original-Token zurück, ohne doppelt abzurechnen.
• Origin-Prüfung — Abschlussansprüche werden nur von der Domain akzeptiert, auf der die Anzeige ausgeliefert wurde.

8. Eine Interstitial-Anzeige erstellen (Advertiser-Seite)

1. Dashboard → Anzeigen → Anzeige erstellen, Typ Interstitial wählen — oder drücken Sie im Live-Demo oben die Wiedergabetaste, um zu sehen, wie sie aussieht.
2. Laden Sie Ihr Creative hoch — entweder ein Bild oder ein Video (MP4 / WebM, max. 50 MB) im selben Uploader. Videos spielen im Vollbild; Bilder werden für den Countdown im Vollbild gezeigt.
3. Legen Sie die nötige Wiedergabezeit (15–30 Sekunden) und Ihren CTA-Link fest — z. B. eine App-Store-Seite ("Diese App herunterladen") oder Ihre Website.
4. Einreichen. Zugelassene Anzeigen werden an jeden Publisher ausgeliefert, der das Interstitial-Format aktiviert hat.

Sie zahlen nur 0,60 $ pro 1000 vollständig gesehene Ansichten — plus 0,08 $ CPC, wenn ein Nutzer nach der Anzeige Ihren CTA klickt.