# Mise en production du systeme de pubs rewardees (plan complet)

## Etat d'avancement (2026-02-15)

### Deja valide en local (OK)

- Flux pub boutique: `POST /api/ads/daily/reward` en `200`, recompense creditee.
- Flux pub double points victoire: `POST /api/ads/double-points` en `200`.
- Flux pub solution en partie: tracking API active via `POST /api/ads/free-solution`.
- UX victoire: le modal reste affiche apres pub, puis choix "Niveau suivant" ou "Menu".
- UX boutique: onglet videos visible et fonctionnel selon consentement.
- Consentement pub: routes privacy et blocage sans consentement en place.
- Runtime config backend: seul `.env` est charge en local; `.env.example` n'est plus charge au runtime.
- Suivi pub fin: table `ad_reward_events` ajoutee (daily, double points, free solution).

### Reste a faire avant activation des vraies pubs prod

- Integrer un provider web rewarded pour le navigateur (prod web), avec gating strict du credit.
- Finaliser les feature flags de rollout (`ads_web_enabled`, `ads_daily_enabled`, `ads_double_points_enabled`).
- Completer la conformite (CMP + textes legaux definitifs + parcours refus aussi simple qu'acceptation).
- Ajouter monitoring exploitable (metriques ads success/fail, duplicates, quota rejects) et plan rollback.

### Checklist go-live minimal (prod)

- Variables/secrets prod verifies (API + mobile/web), sans `.env` en prod.
- Consentement et textes legaux publies et relies dans l'app.
- Test pre-prod: daily reward, double points, refus pub, quota atteint, retry reseau.
- Deploy progressif (canary), suivi live, puis ouverture totale.

## Objectif produit

Mettre en place un systeme publicitaire robuste et monetisable avec deux usages:

1. Boutique: jusqu'a 10 pubs/jour pour gagner des actions (indices + bonus final).
2. Victoire de niveau: bouton optionnel pour doubler la recompense si la pub est regardee.

Le joueur doit toujours pouvoir continuer sans regarder de pub.

## Constat actuel du code

### Mobile / web

- `rollerlogic-mobile/src/core/ads.ts`:
  - les pubs sont desactivees en PWA/prod (non natif).
  - le flux actuel est AdMob natif (Capacitor), donc pas exploitable tel quel pour le navigateur.

### Backend pub

- `rollerlogic-api/src/routes/misc-routes.ts`:
  - endpoints existants: `/ads/daily/reward`, `/ads/double-points`, `/ads/free-solution`.
  - limite quotidienne globale `MAX_DAILY_ADS = 10`.
  - la table `ad_rewards` cumule actuellement les usages (daily + double points) dans `watched_count`.
- `rollerlogic-api/src/server/db-schema.ts`:
  - table `ad_rewards` deja en place (agregat journalier).

### Limite structurelle actuelle

- Le serveur ne recoit pas de preuve publicitaire verifiable cote ad network (il fait confiance a l'appel client).
- Les quotas "daily hints" et "double points" partagent le meme compteur journalier, ce qui n'est pas ideal pour ton design cible.

## Ce que je vais faire (plan technique)

## 1) Cadrer le modele cible

- Separer clairement 2 mecanismes:
  - `daily_ads` (10/jour max, recompense indices, bonus final configurable)
  - `victory_double_points` (x2 en fin de partie, plafonnable independamment)
- Definir des limites serveur explicites:
  - ex: `daily_ads_limit = 10`, `double_points_limit = 20` (ou illimite avec anti-abus).

Livrable: spec technique courte validee avant dev.

## 2) Refonte data et anti-fraude

- Ajouter une table d'evenements pub (journal fin):
  - `ad_reward_events` (id, user_id, reward_type, status, reward_date, reward_payload, provider, created_at, claimed_at, idempotency_key, session_nonce).
- Conserver `ad_rewards` pour l'agregat journalier/performances, mais alimentee depuis les events.
- Ajouter des contraintes anti-double-credit:
  - index unique sur `idempotency_key`.
  - verrou transactionnel lors du credit wallet.

Livrable: migration SQL + update `db-schema.ts`.

## 3) Nouveau protocole backend de recompense

- Remplacer le mode "client appelle directement pour crediter" par un flux en 2 temps:
  1. `POST /ads/reward/start` -> cree une session/nonce.
  2. Client lance la pub.
  3. `POST /ads/reward/claim` avec `session_nonce` apres evenement de completion.
- Le `claim` est idempotent et atomique:
  - si deja credite, renvoyer l'etat sans redonner la recompense.
- Controle serveur:
  - auth utilisateur stricte
  - rate limit par endpoint + par user
  - verification de contexte (daily/victory, basePoints borne, niveau termine).

Livrable: nouvelles routes + tests backend.

## 4) Integration web rewarded ads (navigateur)

- Ajouter un provider web dedie (Google Ad Manager GPT Rewarded) pour la version navigateur.
- Conserver AdMob natif pour mobile si necessaire.
- Interface unifiee cote jeu:
  - `requestRewardedAd({ type: "daily_reward" | "double_points" })`.
- Gating du credit:
  - recompense accordee uniquement apres evenement `rewardedSlotGranted`.
  - si fermeture/abandon: aucun credit.

Note importante:
- Sur web GPT rewarded, la server-side verification native n'est pas disponible comme sur app mobile SDK; on compense par idempotence, quotas, audit et controles metier.

Livrable: module ads web + branchement UI + fallback propre.

### Configuration front (navigateur web GPT rewarded)

Variables a definir dans l'environnement frontend (build web):

- `VITE_ADS_ENABLED=true`
- `VITE_WEB_REWARDED_PROVIDER=gpt`
- `VITE_WEB_REWARDED_SIMULATION=false`
- `VITE_GPT_REWARDED_UNIT_DAILY_REWARD=/NETWORK_CODE/UNIT_DAILY_REWARDED`
- `VITE_GPT_REWARDED_UNIT_DOUBLE_POINTS=/NETWORK_CODE/UNIT_DOUBLE_POINTS_REWARDED`
- `VITE_GPT_REWARDED_UNIT_FREE_HINT=/NETWORK_CODE/UNIT_FREE_HINT_REWARDED`

Comportement:

- Sur navigateur: provider GPT rewarded (on-demand uniquement, jamais auto).
- Sur natif Capacitor: AdMob natif conserve.
- Si GPT n'est pas configure: fallback simulation (si `VITE_WEB_REWARDED_SIMULATION=true`) ou indisponible.

## 5) UX / UI

- Boutique:
  - compteur `X/10` base sur etat serveur.
  - barre de progression mise a jour uniquement apres `claim` reussi.
  - message clair sur reward suivante.
- Victoire:
  - bouton "Doubler mes points (pub)" optionnel.
  - bouton desactive pendant chargement, puis etat "recompense recue" ou "echec".
  - si refus pub, progression du joueur non bloquee.

Livrable: UX stable desktop/mobile + messages d'erreur lisibles.

## 6) Observabilite, exploitation et rollback

- Journaliser:
  - `ad.start`, `ad.granted`, `ad.claimed`, `ad.claim_rejected`, `ad.claim_duplicate`.
- Dashboard admin:
  - taux completion, taux echec, revenus eCPM (si dispo), credits distribues, anomalies.
- Feature flags:
  - `ads_web_enabled`
  - `ads_daily_enabled`
  - `ads_double_points_enabled`
- Plan de rollback:
  - desactivation par flag sans casser le jeu.

Livrable: pilotage prod + securite d'exploitation.

## 7) Tests et validation

- Tests unitaires backend:
  - quotas, idempotence, reset journalier, bonus jour 10.
- Tests E2E:
  - completion pub -> reward
  - fermeture pub -> pas de reward
  - double clic/retry reseau -> un seul credit
- Tests charge:
  - endpoints de claim sous pic.

Livrable: suite de tests executable en CI.

## Cadre legal France/UE a respecter (checklist pratique)

## A. Donnees perso, cookies et consentement

1. Cookies/traceurs publicitaires:
- En France, les traceurs pub necessitent consentement prealable (Loi Informatique et Libertes, art. 82 + doctrine CNIL).
- Refuser doit etre aussi simple qu'accepter.
- Prevoir retrait du consentement a tout moment.

2. RGPD:
- Base legale claire pour chaque traitement.
- Information transparente (politique de confidentialite, finalites, destinataires, durees de conservation).
- Minimisation des donnees et securisation.
- Preuve du consentement si consentement utilise.

3. Mineurs:
- En France, seuil de 15 ans pour consentement autonome en ligne (art. 45 Loi Informatique et Libertes).
- En dessous de 15 ans: consentement conjoint mineur + titulaire de l'autorite parentale pour les traitements fondes sur consentement.

## B. Publicite et protection du consommateur

1. Identification de la pub:
- La nature publicitaire doit etre claire et non ambigue.
- Ne pas dissimuler l'intention commerciale.

2. Pas de pratique trompeuse/agressive:
- Interdiction des pratiques commerciales deloyales/trompeuses/agressives (Code de la consommation: L121-1, L121-2, L121-3, L121-6, L121-7).
- Ne pas forcer le joueur via dark patterns (ex: UI qui pousse abusivement au clic pub).

3. Protection des mineurs en pub:
- Vigilance renforcee si audience mineure (messages, ciblage, design, incitations).
- Eviter tout message qui pousse directement les enfants a l'achat ou a influencer les parents.

## C. DSA (a verifier selon qualification de ton service)

- Si le service est juridiquement qualifie de "plateforme en ligne" au sens DSA:
  - exigences de transparence publicitaire (article 26),
  - interdiction de certaines pubs profilees (donnees sensibles),
  - protections mineurs (article 28, dont restrictions publicitaires si mineur connu avec certitude raisonnable).

Ce point doit etre confirme avec conseil juridique selon ton modele exact.

## D. Exigences Google (si stack Google ads)

- Respect des "Policies for ad units that offer rewards":
  - opt-in clair,
  - details de la recompense avant affichage,
  - pas de recompense monetaire directe,
  - livraison effective de la recompense promise.
- Pour EEE/UK/CH sur ads personnalisees:
  - CMP certifiee Google + TCF IAB requis.

## Documents conformite a preparer avant go-live

1. Politique de confidentialite mise a jour (ads, consentement, partenaires).
2. Bandeau CMP conforme (accepter/refuser/reparametrer).
3. CGU/mentions boutique expliquant le fonctionnement des recompenses pub.
4. Registre de traitements (interne).
5. Procedure de gestion des droits RGPD (acces/suppression/etc).
6. Note interne "protection mineurs" (si audience mineure probable).

## Ordre de realisation propose (jour par jour)

1. Jour 1:
- finaliser spec + schema DB + flags + quotas separes.
2. Jour 2:
- backend `start/claim`, migrations, tests unitaires.
3. Jour 3:
- integration web rewarded + branchement UI boutique/victoire.
4. Jour 4:
- CMP, ecrans info, textes legaux, test consentement.
5. Jour 5:
- recette complete, monitoring, deploiement progressif (10% puis 100%).

## Decision a prendre avant implementation

1. Veux-tu un quota `double_points` separe (recommande) ou partage avec les 10/jour?
2. La recompense du 10e visionnage reste "1 solution" ou tu veux la changer?
3. Ciblage mineurs: veux-tu une politique stricte par defaut (pubs non personnalisees si age inconnu)?

## Sources officielles utilisees

- CNIL - Cookies et traceurs (obligations):  
  https://www.cnil.fr/fr/cookies-et-autres-traceurs/que-dit-la-loi
- CNIL - Lignes directrices/recommandation cookies (refus aussi simple que acceptation):  
  https://www.cnil.fr/fr/cookies-et-autres-traceurs/regles/cookies/lignes-directrices-modificatives-et-recommandation
- Loi Informatique et Libertes - Article 82 (traceurs):  
  https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000037813978
- Loi Informatique et Libertes - Article 45 (mineurs, 15 ans):  
  https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000037823135
- Code de la consommation - L121-1 (pratiques deloyales):  
  https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000032227301
- Code de la consommation - L121-2 (pratiques trompeuses):  
  https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000032227297/
- Code de la consommation - L121-3 (intention commerciale / omission):  
  https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000044563111
- Code de la consommation - L121-6 (pratiques agressives):  
  https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000032227285
- DSA (Regulation EU 2022/2065 - art. 26 et 28):  
  https://eur-lex.europa.eu/eli/reg/2022/2065/oj
- Google Ad Manager - Rewarded ads web:  
  https://support.google.com/admanager/answer/9116812?hl=en
- Google Ad Manager - Rewarded ads apps:  
  https://support.google.com/admanager/answer/7386053?hl=en
- Google - Policies for ad units that offer rewards:  
  https://support.google.com/admanager/answer/7496282
- Google - EU User Consent Policy:  
  https://www.google.com/about/company/user-consent-policy.html
- Google - CMP requirements (EEA/UK/CH):  
  https://support.google.com/admanager/answer/13554116

---

Note: ce document est un plan produit/technique et conformite operationnelle, pas un avis juridique formel. Avant mise en prod definitive, validation par un juriste/avocat recommande.