Integration Docs

Everything you need to put Robins Ads on your website — normal display ads and full-screen interstitial ads, including the Reward API for games and apps. Setup takes about 2 minutes. You need a publisher account with an approved website (sign up free).

1. Normal display ads

Banners, skyscrapers, rectangles and native ads. Copy your personal snippet from Dashboard → Websites → your site → Ad Code — it already contains your Website ID.

Option A — automatic ads (easiest)

One script tag in your head. It finds the best ad positions on the page itself (in-article, sidebar, bottom):

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

Enable Automatic Ads in your website settings first.

Option B — fixed ad placements

Add the script once, then place an ad container wherever you want:

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

The data-ad-type attribute can be banner, skyscraper, rectangle, native, anchor, interstitial or popunder. Each placement requests only ads of that format that are allowed for your website (Website settings → Allowed Ad Types). The two overlay formats (interstitial, popunder) are not drawn inside the div — the div works as the trigger, so a click or tap on it opens the ad (see section 2).

AttributeOnPurpose
data-website-idScript tag or ad divIdentifies your site — required everywhere
data-ad-typeAd divbanner · skyscraper · rectangle · native · anchor · interstitial · popunder
data-interstitialScript tagShow a full-screen ad automatically (see section 2)
data-popunderScript tagOpen the advertiser URL in a popunder window on click (see section 2c)
⚠️ Paid-view rule: an ad must be genuinely visible and uncovered before it can be paid. If your content, a sticky header, a cookie banner or another ad covers the creative, the view is not counted. Overlay, interstitial and full-page popunder ads follow the same rule.

2. Interstitial & popunder ads (overlay + new-window formats)

An interstitial covers the whole screen with a video or image. The user must watch it for its full duration (30–60 s) before it can be closed — our server verifies that watch time, so you can safely reward users who finish. When the video ends it fades into a Google-style end card showing the advertiser icon, name and a call-to-action button (Play Game, Download App, Visit Website), just like the interstitials in mobile games. One format, two ways to use it:

  • Reward button — you put a "Watch ad, get 50 coins" button in your game/app and grant the reward after the verified watch.
  • Automatic — the ad appears by itself once per visit between pages; no reward involved.

Step 1 — enable the format

In Dashboard → Websites → your site → Allowed Ad Types, tick interstitial and save. This makes the format eligible to serve on your site. Unlike popunder, an interstitial does not appear from the toggle alone — because it is a full-screen takeover it must be wired into the page with code (Step 2a or Step 2b). That way a page never suddenly covers the screen unless you asked for it.

Step 2a — reward button (callback)deprecated

Still works, but for rewards we now recommend the server-to-server Reward API (section 3) — it needs no browser callbacks and is impossible to fake. The base ads.js script from section 1 must be on the page. RobinAds.showInterstitial() shows the ad and resolves only after the watch is verified on our server:

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

The promise resolves with { rewardGranted, token, rewardId }. During the ad the user sees a countdown, then an end card with the advertiser icon, name and call-to-action button (e.g. "▶ Play Game" or "⬇ Download App") that they dismiss to close — that is the advertiser own reward path.

Step 2b — automatic interstitial

To have the interstitial show on its own (without a reward button), add data-interstitial="true" to the ads.js tag on the page where you want it. This is the only way an interstitial auto-appears — the Allowed Ad Types toggle by itself never triggers it.

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

Step 2c — popunder ads (behind-tab window or full-page overlay)

A popunder opens the advertiser page either in a browser window behind the current tab or as a full-page overlay on your site. In the overlay mode the visitor closes the ad with our close button; the view is paid only after at least 30 seconds of uncovered visibility and a real close click. When it opens behind the tab, the open is verified server-side, so a window that never rendered is never billed. Billed at $0.04 per 1,000 paid opens (publisher earns $0.02 per 1,000).

Enable popunder in Allowed Ad Types to load popunder-eligible ads, then use a button or placement div to trigger the popunder:

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

Step 3 — valuable rewards? Verify server-sidedeprecated

Legacy flow only — the Reward API does this verification for you. If you still use the browser callback and coins can be traded for anything real, do not rely on it alone: send the token to your backend and check it against our API — this is impossible to fake, because the token is an HMAC signature over the server-stored 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 — server-verified rewards, the easy way

The recommended way to give your users rewards for watching ads — built like a payment gateway. Your backend creates a reward with one REST call, your visitor watches the ad in a popup we host (countdown, anti-fraud, billing — zero code on your side), and your backend polls the reward until it says "verified". There are no browser callbacks and nothing to fake: only our server can flip a reward to verified.

Getting started

  1. Create a free Robins Ads account and get your website approved.
  2. Open Dashboard → Settings → API Keys and create a key.
  3. Store the key on your server — it is shown only once. Never put it in front-end code.
  4. Send it as a Bearer token on every API call.

Base URL & authentication

https://robinsads.com/api/v1

Authorization: Bearer rbads_live_...

1 — Create a reward

POST /api/v1/rewards returns a popup_url — save the reward id in your database together with your user/order, then hand the URL to the visitor browser.

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

Response:

{
  "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 the popup (visitor side)

That is the entire front-end integration — a button that opens the popup on a user gesture. The interstitial, countdown and verification all run on our page:

<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 — Read reward status

GET /api/v1/rewards/:id is the way to read a reward current status. There are no webhooks — check this endpoint whenever and however you like: on demand, on a timer, from a cron job or a background worker. When the status is verified, grant the reward — and store the id so it is never granted twice.

  • pending — the visitor has not finished the ad yet (or has not opened the popup).
  • verified — full watch confirmed by our server. Credit the user now.
  • expired — the popup URL was not used within 15 minutes.
  • rejected — a completion attempt failed verification (fraud attempt).
// 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);

Errors & rate limits

Errors are returned as JSON {"error": "message"} with the appropriate HTTP status code. Requests are rate-limited per IP (120 per minute). On 429, back off and retry.

  • 401 — missing or invalid API key
  • 403 — website not verified or approved
  • 404 — reward not found (wrong id or not yours)
  • 429 — rate limit exceeded

4. Telegram Mini Apps, bots & mini games

Run the same display ads and the full-screen rewarded view inside a Telegram bot, Mini App or mini game — no extra code, no SDK to wire up. A Telegram Mini App is just a web page, so you use the exact ads.js snippet from section 1. When it detects it is running inside Telegram it automatically adapts: ad clicks open through Telegram bridge (so they never get swallowed by the in-app browser), the full-screen ad expands to fill the mini-app viewport, and the native Back button closes an ad once the required watch is done.

⚠️ In Telegram, use the in-app overlay for rewarded ads — call RobinAds.showInterstitial() (section 2). The hosted-popup flow of the Reward API uses window.open(), which Telegram blocks inside a Mini App.

Easy install for owners — 4 steps

  1. Add your Mini App as a website. In Dashboard → Websites → Add website, enter the HTTPS domain that hosts your Mini App (the same URL you give BotFather). Verify and wait for approval — your ads only serve once the site is approved.
  2. Turn on the formats. Open your site → Allowed Ad Types, tick banner, rectangle, native and interstitial, then copy your Website ID from Ad Code.
  3. Point BotFather at your page. In @BotFather → your bot → Bot Settings → Menu Button / Mini App, set the Web App URL to that HTTPS domain.
  4. Paste one script tag. Drop the snippet below into your Mini App head — the script handles Telegram detection for you, so you never include or initialise the Telegram SDK yourself.
<!-- 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>

That is the whole integration. It is identical on a normal website and inside a Telegram Mini App — the same snippet, the same data-ad-type containers and the same RobinAds.showInterstitial() call. The only difference is that inside Telegram the clicks, fullscreen and Back button are handled automatically.

5. Live demo — try it right here 🎮

real ads from the live network

These buttons run the exact code from the docs above, using a demo website ID. Display formats load an ad into the box below; the interstitial plays full-screen with its countdown and — after our server verifies the watch — credits this demo with 50 coins, the same way a publisher game would reward a player.

Pick a format above to fetch a real ad.

🪙 Demo coins: 0

Demo only: impressions here count against real advertiser campaigns just like any placement. No reward is actually paid out — the coin counter just shows where your own reward logic goes.

6. Rates — what advertisers pay, what you earn

FormatAdvertiser pays (base bid)Publisher earns (50%)
Banner / skyscraper / rectangle / nativefrom $0.40 per 1000 views (CPM)$0.20 per 1000 views at the base bid
Popunder — verified openfrom $0.04 per 1000 opens$0.02 per 1000 opens at the base bid
Interstitial / popup — complete viewfrom $0.60 per 1000 fully-watched views$0.30 per 1000 complete views at the base bid

Every advertiser sets their own CPM bid above these per-format minimums, and one rule covers all formats: the advertiser is charged their bid / 1000 for each paid event, and you are paid 50% of exactly that charge. So an ad bidding $1.00 CPM not only wins a larger share of the live auction (it is shown more often) — it also pays you $0.50 per 1000 views instead of $0.20.

Interstitials are a premium format: the advertiser is charged only when the watch time is fully completed and verified — skipped ads cost nothing. That is why their base bid is higher than standard display. Earnings are credited to your balance automatically.

7. Fraud protection — built in

  • Watch time is measured on the server — from the moment the impression was created, never from the player clock. A claim before the countdown really elapsed is rejected.
  • Tab-hidden / paused detection — the countdown in the ad player freezes when the tab is hidden or the video pauses.
  • Daily per-user caps — one visitor can complete the same interstitial a limited number of times per day (default 10).
  • IP abuse blocking — bots and rapid-fire IPs are blocked automatically for view and click events.
  • Signed reward tokens — HMAC-signed, verified with constant-time comparison; replaying a claim returns the original token without double-billing.
  • Origin check — completion claims are only accepted from the domain the ad was served on.

8. Creating an interstitial ad (advertiser side)

  1. Dashboard → Ads → Create Ad, choose type Interstitial — or hit the play button in the live demo above to see how it looks.
  2. Upload your creative — either an image or a video (MP4 / WebM, max 50 MB) in the same uploader. Videos play full-screen; images are shown full-screen for the countdown.
  3. Set the required watch time (30–60 seconds) and your CTA link — e.g. an app store page ("Download this app") or your website.
  4. Submit. Approved ads are served to every publisher who enabled the interstitial format.

You are only charged $0.60 per 1000 fully watched views your CTA after the ad.

Ready to earn?

Sign up, add your website and paste the snippet — your first ads run within minutes.

Questions? Email info@robinswebdesign.com — Technical documentation for the Robins Ads ad network. Last updated 2026.