Integratiedocumentatie

1. Gewone displayadvertenties

Banners, wolkenkrabbers, rectangles en native advertenties. Kopieer uw persoonlijke snippet via Dashboard → Websites → uw site → Advertentiecode — deze bevat al uw Website-ID.

Optie A — automatische advertenties (makkelijkst)

Eén script-tag in uw head. Deze vindt zelf de beste advertentieposities op de pagina (in de tekst, zijbalk, onderaan):

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

Schakel eerst Automatische advertenties in bij de instellingen van uw website.

Optie B — vaste advertentieposities

Voeg het script één keer toe en plaats daarna een advertentiecontainer waar u maar wilt:

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

Het kenmerk data-ad-type kan banner, skyscraper, rectangle, native, anchor, interstitial of popunder zijn. Elke positie vraagt alleen advertenties van dat format op die voor uw website zijn toegestaan (Website-instellingen → Toegestane advertentieformaten). De twee overlay-formaten (interstitial, popunder) worden niet binnen de div getekend — de div werkt als trigger, dus een klik of tap erop opent de advertentie (zie sectie 2).

2. Interstitial- & popunderadvertenties (overlay + nieuw-venster formaten)

Een interstitial bedekt het hele scherm met een video of afbeelding. De gebruiker moet deze volledig bekijken (15–30 s) voordat hij kan worden gesloten — onze server verifieert die kijktijd, zodat u gebruikers die uitzien veilig kunt belonen. Na de video vervaagt deze naar een Google-stijl eindekaart met het pictogram, de naam van de adverteerder en een call-to-action-knop (Speel game, Download app, Bezoek website), net als de interstitials in mobile games. Eén format, twee manieren om het te gebruiken:

• Beloningsknop — u plaatst een knop "Bekijk advertentie, krijg 50 munten" in uw game/app en geeft de beloning na het geverifieerde kijken.
• Automatisch — de advertentie verschijnt één keer per bezoek tussen pagina’s vanzelf; zonder beloning.

Stap 1 — schakel het format in

Vink bij Dashboard → Websites → uw site → Toegestane advertentieformaten interstitial aan en sla op. Hiermee wordt het format geschikt om op uw site te serveren. In tegenstelling tot popunder verschijnt een interstitial niet alleen door de schakelaar — omdat het een fullscreen-overname is, moet het met code in de pagina worden bedraad (Stap 2a of 2b). Zo bedekt een pagina nooit plotseling het scherm, tenzij u erom vroeg.

Stap 2a — beloningsknop (callback)verouderd

Werkt nog, maar voor beloningen raden we nu de server-tot-server Reward API aan (sectie 3) — deze heeft geen browser-callbacks nodig en is niet te vervalsen. Het basis ads.js-script uit sectie 1 moet op de pagina staan. RobinAds.showInterstitial() toont de advertentie en lost pas op nadat het kijken op onze server is geverifieerd:

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

De belofte lost op met { rewardGranted, token, rewardId }. Tijdens de advertentie ziet de gebruiker een aftelling, daarna een eindekaart met het pictogram, de naam van de adverteerder en een call-to-action-knop (bijv. "▶ Speel game" of "⬇ Download app") die hij wegklikt om te sluiten — dat is het eigen beloningspad van de adverteerder.

Stap 2b — automatische interstitial

Om de interstitial vanzelf te tonen (zonder beloningsknop), voeg data-interstitial="true" toe aan de ads.js-tag op de gewenste pagina. Dit is de enige manier waarop een interstitial automatisch verschijnt — de schakelaar Toegestane formaten alleen activeert hem nooit.

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

Stap 2c — popunderadvertenties (opent adverteerder-URL achter huidig tabblad)

Een popunder-advertentie opent de website van de adverteerder in een nieuw browservenster achter het huidige tabblad, met een anti-adblock form-submit-techniek. Geen creatieve afbeelding, geen aftelling, geen overlay — alleen de URL. De adverteerder hoeft alleen een doel-URL en een titel te geven. Gefactureerd tegen $0,04 per 1.000 opens (publisher verdient $0,02 per 1.000). De gebruiker merkt de popunder pas op als hij de huidige pagina sluit of weg navigeert, waardoor dit format zeer effectief en bestand is tegen adblockers.

Schakel popunder in bij Toegestane advertentieformaten om popunder-geschikte advertenties te laden en trigger de popunder daarna met een knop of een plaatsings-div:

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

Stap 3 — waardevolle beloningen? Verifieer server-sideverouderd

Alleen verouderde stroom — de Reward API doet deze verificatie voor u. Als u nog de browser-callback gebruikt en munten kunnen worden geruild voor iets echts, vertrouw er dan niet alleen op: stuur het token naar uw backend en controleer het tegen onze API — dit is niet te vervalsen, want het token is een HMAC-handtekening over de server-opgeslagen impressie:

// 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 — server-verifieerde beloningen, op de makkelijke manier

De aanbevolen manier om uw gebruikers beloningen te geven voor het kijken van advertenties — opgebouwd als een betaalprovider. Uw backend maakt met één REST-aanroep een beloning aan, uw bezoeker bekijkt de advertentie in een popup die wij hosten (aftelling, anti-fraude, facturering — nul code van uw kant), en uw backend pollt de beloning totdat deze "verified" meldt. Er zijn geen browser-callbacks en niets te vervalsen: alleen onze server kan een beloning naar verified zetten.

Aan de slag

1. Maak een gratis Robins Ads-account aan en laat uw website goedkeuren.
2. Open Dashboard → Instellingen → API-sleutels en maak een sleutel aan.
3. Bewaar de sleutel op uw server — hij wordt slechts één keer getoond. Nooit in front-end-code zetten.
4. Stuur het als Bearer-token bij elke API-aanroep.

Basis-URL & authenticatie

https://robinsads.com/api/v1

Authorization: Bearer rbads_live_...

1 — Maak een beloning

POST /api/v1/rewards geeft een popup_url terug — bewaar de beloning-id in uw database samen met uw gebruiker/bestelling en geef de URL daarna mee aan de browser van de bezoeker.

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

Antwoord:

{
  "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 — Open de popup (bezoekerskant)

Dat is de hele front-end-integratie — een knop die de popup opent bij een gebruikersgebaar. De interstitial, aftelling en verificatie draaien allemaal op onze pagina:

<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 — Lees beloningsstatus

GET /api/v1/rewards/:id is de manier om de huidige status van een beloning te lezen. Er zijn geen webhooks — controleer dit eindpunt wanneer en hoe u wilt: op aanvraag, op een timer, via een cron-job of een achtergrond-worker. Wanneer de status verified is, geef de beloning — en bewaar de id zodat hij nooit twee keer wordt gegeven.

• pending — de bezoeker heeft de advertentie nog niet uit gekeken (of de popup nog niet geopend).
• verified — volledig kijken bevestigd door onze server. Schrijf de gebruiker nu bij.
• expired — de popup-URL werd niet binnen 15 minuten gebruikt.
• rejected — een voltooiingspoging faalde de verificatie (fraudepoging).

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

Fouten & rate limits

Fouten worden teruggegeven als JSON {"error": "message"} met de passende HTTP-statuscode. Verzoeken zijn beperkt per IP (120 per minuut). Bij 429, wacht en probeer opnieuw.

• 401 — ontbrekende of ongeldige API-sleutel
• 403 — website niet geverifieerd of goedgekeurd
• 404 — beloning niet gevonden (verkeerde id of niet de uwe)
• 429 — rate limit overschreden

4. Telegram Mini Apps, bots & mini-games

Gebruik dezelfde displayadvertenties en de fullscreen beloningsweergave in een Telegram-bot, Mini App of mini-game — zonder extra code, zonder SDK te bedraden. Een Telegram Mini App is gewoon een webpagina, dus u gebruikt exact de ads.js-snippet uit sectie 1. Wanneer hij detecteert dat hij in Telegram draait, past hij zich automatisch aan: advertentieklikken openen via de Telegram-brug (zodat ze nooit worden geslikt door de in-app browser), de fullscreen advertentie vult de mini-app-viewport, en de native Terug-knop sluit een advertentie zodra het vereiste kijken klaar is.

Makkelijke installatie voor eigenaren — 4 stappen

1. Voeg uw Mini App toe als website. Voer bij Dashboard → Websites → Website toevoegen het HTTPS-domein in dat uw Mini App host (dezelfde URL die u aan BotFather geeft). Verifieer en wacht op goedkeuring — uw advertenties serveren pas als de site is goedgekeurd.
2. Zet de formaten aan. Open uw site → Toegestane advertentieformaten, vink banner, rectangle, native en interstitial aan en kopieer uw Website-ID uit de Advertentiecode.
3. Richt BotFather op uw pagina. Stel bij @BotFather → uw bot → Bot-instellingen → Menuknop / Mini App de Web App-URL in op dat HTTPS-domein.
4. Plak één script-tag. Zet de onderstaande snippet in de head van uw Mini App — het script doet de Telegram-detectie voor u, zodat u het Telegram-SDK nooit zelf opneemt of initialiseert.

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

Dat is de hele integratie. Ze is identiek op een gewone website en in een Telegram Mini App — dezelfde snippet, dezelfde data-ad-type-containers en dezelfde RobinAds.showInterstitial()-aanroep. Het enige verschil: in Telegram worden klikken, fullscreen en de Terug-knop automatisch afgehandeld.

6. Tarieven — wat adverteerders betalen, wat u verdient

Interstitials zijn een premium-format: de adverteerder wordt alleen gefactureerd wanneer de kijktijd volledig is voltooid en geverifieerd — overgeslagen advertenties kosten niets. Daarom betalen ze iets meer per weergave dan standaard displayadvertenties. Verdiensten worden automatisch bijgeschreven op uw saldo.

7. Fraudebescherming — ingebouwd

• Kijktijd wordt server-side gemeten — vanaf het moment dat de impressie werd aangemaakt, nooit vanaf de klok van de speler. Een claim vóórdat de aftelling echt verstreken is, wordt afgewezen.
• Verborgen tabblad / gepauzeerd-detectie — de aftelling in de advertentiespeler bevriest wanneer het tabblad verborgen is of de video pauzeert.
• Dagelijkse limieten per gebruiker — één bezoeker kan dezelfde interstitial een beperkt aantal keer per dag voltooien (standaard 10).
• IP-misbruikblokkering — bots en snel-vurende IP’s worden automatisch geblokkeerd voor weergave- en klikgebeurtenissen.
• Ondertekende beloningstokens — HMAC-ondertekend, geverifieerd met vergelijking in constante tijd; een claim opnieuw afspelen geeft het originele token terug zonder dubbele facturering.
• Origin-controle — voltooiingsclaims worden alleen geaccepteerd vanaf het domein waarop de advertentie werd geserveerd.

8. Een interstitial-advertentie maken (adverteerderskant)

1. Dashboard → Advertenties → Advertentie maken, kies type Interstitial — of druk op de speelknop in de live-demo hierboven om te zien hoe het eruitziet.
2. Upload uw creatieve — een afbeelding of een video (MP4 / WebM, max 50 MB) in dezelfde uploader. Video’s spelen fullscreen; afbeeldingen worden fullscreen getoond tijdens de aftelling.
3. Stel de vereiste kijktijd in (15–30 seconden) en uw CTA-link — bijv. een app-store-pagina ("Download deze app") of uw website.
4. Verstuur. Goedgekeurde advertenties worden geserveerd aan elke publisher die het interstitial-format heeft ingeschakeld.

U betaalt slechts $0,60 per 1000 volledig bekeken weergaven — plus $0,08 CPC als een gebruiker uw CTA klikt na de advertentie.