Documentation d’intégration

1. Annonces display classiques

Bannières, gratte-ciel, rectangles et annonces natives. Copiez votre extrait personnel depuis Tableau de bord → Sites → votre site → Code d’annonce — il contient déjà votre ID de site.

Option A — annonces automatiques (le plus simple)

Une balise script dans votre head. Elle trouve elle-même les meilleurs emplacements d’annonces sur la page (dans le texte, barre latérale, bas de page) :

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

Activez d’abord les Annonces automatiques dans les réglages de votre site.

Option B — emplacements d’annonces fixes

Ajoutez le script une fois, puis placez un conteneur d’annonce où vous voulez :

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

L’attribut data-ad-type peut être banner, skyscraper, rectangle, native, anchor, interstitial ou popunder. Chaque emplacement ne demande que les annonces de ce format autorisées pour votre site (Réglages du site → Formats d’annonce autorisés). Les deux formats superposés (interstitial, popunder) ne s’affichent pas dans le div — le div sert de déclencheur, un clic ou tap dessus ouvre donc l’annonce (voir section 2).

2. Annonces interstitielles & popunder (superposition + nouvelle fenêtre)

Un interstitiel couvre tout l’écran avec une vidéo ou une image. L’utilisateur doit la regarder entièrement (15–30 s) avant de pouvoir la fermer — notre serveur vérifie ce temps de visionnage, vous pouvez donc récompenser sans risque ceux qui vont au bout. Une fois la vidéo terminée, elle fond en une fin de carte façon Google affichant l’icône, le nom de l’annonceur et un bouton d’appel à l’action (Jouer, Télécharger l’appli, Visiter le site), comme les interstitiels des jeux mobiles. Un format, deux façons de l’utiliser :

• Bouton récompense — vous placez un bouton « Regarder l’annonce, gagner 50 pièces » dans votre jeu/appli et accordez la récompense après le visionnage vérifié.
• Automatique — l’annonce s’affiche seule une fois par visite entre les pages ; sans récompense.

Étape 1 — activer le format

Dans Tableau de bord → Sites → votre site → Formats d’annonce autorisés, cochez interstitial et enregistrez. Cela rend le format éligible à la diffusion sur votre site. Contrairement au popunder, un interstitiel n’apparaît pas du seul commutateur — comme c’est une prise plein écran, il doit être câblé dans la page par du code (Étape 2a ou 2b). Ainsi une page ne couvre jamais soudain l’écran sauf si vous l’avez demandé.

Étape 2a — bouton récompense (callback)déprécié

Fonctionne encore, mais pour les récompenses nous recommandons désormais la Reward API de serveur à serveur (section 3) — elle n’a besoin d’aucun callback navigateur et est impossible à falsifier. Le script ads.js de base de la section 1 doit être sur la page. RobinAds.showInterstitial() affiche l’annonce et ne se résout qu’après vérification du visionnage sur notre serveur :

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

La promesse se résout avec { rewardGranted, token, rewardId }. Pendant l’annonce, l’utilisateur voit un compte à rebours, puis une fin de carte avec l’icône, le nom de l’annonceur et un bouton d’appel à l’action (ex. « ▶ Jouer » ou « ⬇ Télécharger l’appli ») qu’il ferme pour quitter — c’est le propre chemin de récompense de l’annonceur.

Étape 2b — interstitiel automatique

Pour que l’interstitiel s’affiche seul (sans bouton récompense), ajoutez data-interstitial="true" à la balise ads.js sur la page voulue. C’est la seule façon dont un interstitiel apparaît automatiquement — le commutateur Formats autorisés seul ne le déclenche jamais.

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

Étape 2c — annonces popunder (ouvre l’URL de l’annonceur derrière l’onglet actuel)

Une annonce popunder ouvre le site de l’annonceur dans une nouvelle fenêtre derrière l’onglet actuel, via une technique anti-adblock de soumission de formulaire. Pas d’image créative, pas de compte à rebours, pas de superposition — juste l’URL. L’annonceur n’a besoin que de fournir une URL cible et un titre. Facturé 0,04 $ par 1 000 ouvertures (l’éditeur gagne 0,02 $ par 1 000). L’utilisateur ne remarque le popunder que lorsqu’il ferme ou quitte la page actuelle, ce qui rend ce format très efficace et résistant aux adblockers.

Activez popunder dans Formats d’annonce autorisés pour charger les annonces éligibles, puis déclenchez le popunder avec un bouton ou un div de placement :

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

Étape 3 — récompenses de valeur ? Vérifiez côté serveurdéprécié

Ancien flux uniquement — la Reward API fait cette vérification pour vous. Si vous utilisez encore le callback navigateur et que les pièces peuvent être échangées contre du réel, ne vous y fiez pas seule : envoyez le token à votre backend et vérifiez-le contre notre API — c’est impossible à falsifier, car le token est une signature HMAC sur l’impression stockée côté serveur :

// 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 — récompenses vérifiées côté serveur, en simplicité

La façon recommandée de récompenser vos utilisateurs pour le visionnage d’annonces — conçue comme une passerelle de paiement. Votre backend crée une récompense en un appel REST, votre visiteur regarde l’annonce dans une popup que nous hébergeons (compte à rebours, anti-fraude, facturation — zéro code de votre côté), et votre backend interroge la récompense jusqu’à ce qu’elle indique « verified ». Aucun callback navigateur, rien à falsifier : seul notre serveur peut passer une récompense à verified.

Démarrage

1. Créez un compte Robins Ads gratuit et faites approuver votre site.
2. Ouvrez Tableau de bord → Réglages → Clés API et créez une clé.
3. Stockez la clé sur votre serveur — elle n’est affichée qu’une fois. Ne la mettez jamais dans le code front-end.
4. Envoyez-la comme jeton Bearer sur chaque appel API.

URL de base & authentification

https://robinsads.com/api/v1

Authorization: Bearer rbads_live_...

1 — Créer une récompense

POST /api/v1/rewards renvoie un popup_url — enregistrez l’id de la récompense dans votre base avec votre utilisateur/commande, puis transmettez l’URL au navigateur du visiteur.

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

Réponse :

{
  "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 — Ouvrir la popup (côté visiteur)

C’est toute l’intégration front-end — un bouton qui ouvre la popup sur un geste utilisateur. L’interstitiel, le compte à rebours et la vérification tournent tous sur notre 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 — Lire le statut de la récompense

GET /api/v1/rewards/:id est le moyen de lire le statut actuel d’une récompense. Pas de webhooks — vérifiez ce point de terminaison quand et comme vous voulez : à la demande, sur minuteur, via un cron ou un worker en arrière-plan. Quand le statut est verified, accordez la récompense — et stockez l’id pour ne jamais l’accorder deux fois.

• pending — le visiteur n’a pas encore fini l’annonce (ou n’a pas ouvert la popup).
• verified — visionnage complet confirmé par notre serveur. Créditez l’utilisateur maintenant.
• expired — l’URL de la popup n’a pas été utilisée sous 15 minutes.
• rejected — une tentative d’achèvement a échoué à la vérification (tentative de fraude).

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

Erreurs & limites de débit

Les erreurs sont renvoyées en JSON {"error": "message"} avec le code d’état HTTP approprié. Les requêtes sont limitées par IP (120 par minute). En cas de 429, patientez puis réessayez.

• 401 — clé API manquante ou invalide
• 403 — site non vérifié ou non approuvé
• 404 — récompense introuvable (mauvais id ou pas la vôtre)
• 429 — limite de débit dépassée

4. Telegram Mini Apps, bots & mini-jeux

Diffusez les mêmes annonces display et la vue récompense plein écran dans un bot Telegram, une Mini App ou un mini-jeu — sans code supplémentaire, sans SDK à câbler. Une Telegram Mini App n’est qu’une page web, vous utilisez donc exactement l’extrait ads.js de la section 1. Quand il détecte qu’il tourne dans Telegram, il s’adapte automatiquement : les clics d’annonces s’ouvrent via le pont Telegram (pour ne jamais être avalés par le navigateur intégré), l’annonce plein écran s’étend au viewport de la mini-app, et le bouton Retour natif ferme une annonce une fois le visionnage requis terminé.

Installation facile pour les propriétaires — 4 étapes

1. Ajoutez votre Mini App comme site. Dans Tableau de bord → Sites → Ajouter un site, saisissez le domaine HTTPS qui héberge votre Mini App (la même URL que vous donnez à BotFather). Vérifiez et attendez l’approbation — vos annonces ne se diffusent qu’une fois le site approuvé.
2. Activez les formats. Ouvrez votre site → Formats d’annonce autorisés, cochez banner, rectangle, native et interstitial, puis copiez votre ID de site depuis le Code d’annonce.
3. Pointez BotFather vers votre page. Dans @BotFather → votre bot → Réglages du bot → Bouton de menu / Mini App, définissez l’URL Web App sur ce domaine HTTPS.
4. Collezz une balise script. Placez l’extrait ci-dessous dans le head de votre Mini App — le script gère la détection Telegram pour vous, vous n’incluez ni n’initialisez jamais le SDK Telegram vous-même.

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

C’est toute l’intégration. Elle est identique sur un site normal et dans une Telegram Mini App — le même extrait, les mêmes conteneurs data-ad-type et le même appel RobinAds.showInterstitial(). La seule différence : dans Telegram, les clics, le plein écran et le bouton Retour sont gérés automatiquement.

6. Tarifs — ce que paient les annonceurs, ce que vous gagnez

Les interstitiels sont un format premium : l’annonceur n’est facturé que lorsque le temps de visionnage est entièrement terminé et vérifié — les annonces passées ne coûtent rien. C’est pourquoi ils paient un peu plus par vue que les annonces display standard. Les gains sont crédités automatiquement sur votre solde.

7. Protection contre la fraude — intégrée

• Le temps de visionnage est mesuré côté serveur — dès la création de l’impression, jamais depuis l’horloge du lecteur. Une réclamation avant la fin réelle du compte à rebours est rejetée.
• Détection onglet caché / pause — le compte à rebours du lecteur se fige quand l’onglet est masqué ou la vidéo en pause.
• Plafonds quotidiens par utilisateur — un visiteur peut terminer la même interstitiel un nombre limité de fois par jour (10 par défaut).
• Blocage des abus d’IP — les bots et les IP à répétition sont bloqués automatiquement pour les événements de vue et de clic.
• Tokens de récompense signés — signés HMAC, vérifiés en temps constant ; rejouer une réclamation renvoie le token d’origine sans double facturation.
• Contrôle d’origine — les réclamations d’achèvement ne sont acceptées que depuis le domaine où l’annonce a été diffusée.

8. Créer une annonce interstitielle (côté annonceur)

1. Tableau de bord → Annonces → Créer une annonce, choisissez le type Interstitiel — ou appuyez sur le bouton Lecture de la démo en direct ci-dessus pour voir le rendu.
2. Téléversez votre créa — une image ou une vidéo (MP4 / WebM, 50 Mo max) dans le même téléverseur. Les vidéos passent en plein écran ; les images sont affichées en plein écran pendant le compte à rebours.
3. Définissez le temps de visionnage requis (15–30 secondes) et votre lien CTA — par ex. une page App Store (« Télécharger cette appli ») ou votre site.
4. Soumettez. Les annonces approuvées sont diffusées à chaque éditeur ayant activé le format interstitiel.

Vous ne payez que 0,60 $ par 1000 vues entièrement regardées — plus 0,08 $ CPC si un utilisateur clique votre CTA après l’annonce.