Codes promo et cartes cadeaux

Kaiho a son propre système de codes, entièrement maîtrisé (création, plafond, suivi, révocation) et indépendant des consoles Apple et Google. Il sert à deux choses :

• Code conférence : un code par conférence de Vincent en entreprise, qui offre un accès Premium gratuit (30 jours en général). Il permet aussi de savoir combien de participants de chaque conférence ont utilisé l’app.
• Carte cadeau : quelqu’un offre 1 an ou 3 mois de Kaiho à un proche, typiquement pour Noël.

Il n’y a pas de remise : le système n’offre que des durées d’accès. À la fin d’un accès offert, on propose le plein tarif, jamais l’offre comeback.

Pas encore en ligne

Au 14/10/2026, tout tourne sur l’environnement de dev (Stripe en mode test). La mise en production (base, fonctions, Stripe en mode réel, site) est prévue vers le 1er décembre, pour les cadeaux de Noël. Cette page décrit le fonctionnement prévu, tel que codé.

Pourquoi tout se passe sur le site

Aucune app ne permet de saisir un code, ni sur iOS ni sur Android. Tout se fait sur kaiho.fr/code et kaiho.fr/offrir.

• Sur iOS, un champ « code promo » maison dans l’app est un motif de refus App Store (guideline 3.1.1, qui vise explicitement les codes). Ce qui est acquis en dehors de l’app peut en revanche y être utilisé (guideline 3.1.3(b)) : c’est le modèle de Headspace.
• Pour garder le même parcours sur les deux plateformes, Android suit la même règle, alors que Google l’aurait permis.
• L’app iOS ne renvoie jamais vers ces pages : la consigne passe hors de l’app (Vincent sur scène, l’email de la carte cadeau, la page de vente).
• Avantage : créer un code, changer une règle ou lancer une campagne ne demande aucune mise à jour des apps.

Ne pas masquer un champ pendant la review

Cacher un champ de saisie aux reviewers Apple est visé par la guideline 2.3.1 (fonctionnalités cachées) et expose à l’exclusion du programme développeur. Ce mécanisme a été écarté le 14/10/2026. Si l’abandon entre « code vérifié » et « code activé » s’avère trop fort, la voie propre est d’ajouter les Offer Codes Apple pour les conférences.

Le parcours du bénéficiaire

Identique pour un code conférence et un code cadeau :

1. Sur kaiho.fr/code, la personne saisit le code sans se connecter. Pour une conférence, un QR code ouvre kaiho.fr/code/LECODE, qui préremplit le champ. Le site dit tout de suite ce que le code offre (« 30 jours de Kaiho Premium »). Le code n’est pas encore consommé.
2. Pour l’activer, elle se connecte à son compte Kaiho : Apple, Google ou email. Sans compte, la page affiche les badges des stores : on installe l’app, on crée son compte, puis on revient. Le code reste valable.
3. Activation : « Tu as Premium jusqu’au … ».
4. De retour dans l’app, Premium est actif.

Le site est traduit dans les 6 langues de l’app. Les vérifications sans connexion sont limitées à 20 essais par 10 minutes et par adresse IP, les activations à 10 par 10 minutes et par compte, pour qu’on ne puisse pas deviner des codes en masse.

Les refus possibles

Cas	Ce qui se passe
Code inconnu ou désactivé	« Ce code n’existe pas ». Un code désactivé ne se distingue pas d’un code inconnu.
Code expiré	La date de fin du code est passée (ou les 12 mois d’un code cadeau).
Code épuisé	Le plafond d’utilisations est atteint. Le compteur est atomique : une ruée à la sortie d’une conférence ne peut pas le dépasser.
Déjà utilisé par ce compte	Un compte n’utilise un même code qu’une fois.
Deuxième code conférence	Un compte ne cumule pas deux codes conférence.
Compte pas encore prêt	Le compte existe mais n’a pas fini l’onboarding dans l’app (cas typique : compte créé en se connectant sur le site). Le code n’est pas consommé.
Déjà abonné	Le compte a un abonnement payant en cours sur l’App Store ou Google Play : refus poli, le code n’est pas consommé. Sinon l’accès offert tournerait en parallèle d’un abonnement que la personne continuerait de payer.

Un code cadeau s’ajoute à un accès offert en cours : la nouvelle durée démarre à la fin de l’accès actuel.

La carte cadeau

Achat sur kaiho.fr/offrir, sans compte Kaiho :

• 1 an à 49,99 € (le prix de l’annuel) ou 3 mois à 29,97 € (trois mois de mensuel), toutes taxes comprises ;
• paiement unique par carte, sur la page de paiement de Stripe, sans renouvellement ;
• en option, le prénom du bénéficiaire et un petit mot, imprimés sur la carte.

Après le paiement, la page affiche le code unique (format KAIHO-XXXX-XXXX), à copier ou à imprimer sous forme de carte. Le même contenu part par email à l’acheteur seulement (envoi Brevo depuis contact@kaiho.fr) : c’est lui qui transmet la carte.

Règles :

• le code est à usage unique et s’active dans les 12 mois suivant l’achat ;
• il donne 365 ou 90 jours de Premium à partir de l’activation ;
• remboursement : à l’acheteur, tant que le code n’a pas été activé. Un remboursement fait depuis Stripe désactive automatiquement le code s’il n’a pas servi.

Kaiho est le vendeur de ces cartes, et non plus Apple ou Google : c’est Kaiho qui déclare la TVA de ces ventes. Le comptable valide la partie TVA et les conditions de vente. Les règles des cartes cadeaux et des codes offerts sont la section 14 des conditions générales de vente (en français et en anglais).

Comment l’accès est accordé

Le site appelle des fonctions du backend Supabase, seules à pouvoir lire et écrire les tables des codes :

• promo_codes : les codes (type conférence ou cadeau, durée, dates, plafond, désactivation, notes) ;
• promo_redemptions : qui a utilisé quel code, quand, jusqu’à quand ;
• gift_purchases : les ventes de cartes (paiement Stripe, email de l’acheteur, montant, code généré, statut).

L’utilisation est enregistrée avant l’appel à RevenueCat, puis confirmée, ou annulée si RevenueCat échoue : un plantage au milieu ne consomme pas le code pour rien.

L’accès est un accès promotionnel RevenueCat sur l’entitlement premium, sans carte bancaire. Dans RevenueCat, il apparaît comme un « achat » à 0 € du produit rc_promo_premium_custom, avec le store PROMOTIONAL. Deux codes successifs créent deux accès séparés qui démarrent tous les deux le jour de l’activation ; le second se termine plus tard.

Le backend écrit aussi l’accès dans le miroir serveur des abonnements (celui qui autorise le téléchargement des livres complets), avec le store promotional. À la fin, RevenueCat envoie un événement d’expiration qui retire l’accès aux livres.

Accès empilés

Depuis le 14/10/2026, quand un accès expire, le webhook RevenueCat redemande à RevenueCat si le compte a encore un accès en cours avant de couper les livres. Sans ça, la fin du premier de deux accès empilés aurait retiré les livres à quelqu’un dont le second accès courait encore.

Ce que font les apps

En PR, pas encore publié

kaiho-ios#122 et kaiho-android#126 (textes : kaiho-localization#50), ouvertes le 14/10/2026. Partiront dans la prochaine release. Pour les codes conférence (30 jours), elles doivent être publiées avant la première conférence, sinon les participants retomberaient sur le comeback un mois plus tard. Pour les cadeaux de Noël, elles ont un an devant elles.

Les apps n’ont rien à saisir : elles constatent seulement que la personne est Premium. Les ajouts sont identiques sur iOS et Android.

Reconnaître un accès offert. L’app regarde si RevenueCat a déjà donné à ce compte un accès promotionnel (un produit rc_promo_… dans l’historique, ou l’entitlement premium venant du store PROMOTIONAL). Une fois vu, le drapeau reste levé jusqu’à la déconnexion. Les accès « à vie » (que RevenueCat date à +200 ans) sont traités à part : tout accès qui se termine dans plus de 50 ans compte comme à vie.

Plus jamais d’offre comeback pour un compte qui a eu un accès offert : c’est une 4ᵉ condition d’éligibilité. Sans elle, un participant de conférence serait tombé sur les -30 % un mois plus tard. Voir Promo « comeback ».

« A déjà payé » comptait les accès offerts

Jusqu’à ces PR, le drapeau « a déjà payé » des deux apps comptait un accès promotionnel comme un achat (il regardait seulement si l’historique RevenueCat était vide). Il ignore désormais les produits rc_promo_…. Pour que la correction s’applique aussi aux téléphones qui avaient déjà enregistré la mauvaise valeur, il est recalculé une fois (nouvelle clé de stockage) : au premier lancement de la nouvelle version, le comeback reste retenu jusqu’à la première réponse de RevenueCat.

Rafraîchissement au retour dans l’app. À chaque retour au premier plan, l’app redemande l’état à RevenueCat (au plus une fois par minute, mais toujours après un passage en arrière-plan). Un code activé sur le site débloque Premium sans relancer l’app.

Carte de fin d’accès offert sur l’accueil Coach, au même emplacement que la carte « Ton accès se termine » des abonnés qui ont résilié, avec une icône cadeau : « Ton accès offert se termine le … », « Tu peux continuer avec Kaiho Premium quand tu veux. ». Elle n’apparaît que dans les 7 derniers jours (30 pour la carte des abonnés) et jamais pour un accès à vie. La toucher ouvre le paywall au plein tarif (source promo_ending).

Deux notifications à 9 h, 7 jours puis 1 jour avant la fin (« Ton accès offert se termine bientôt »). Elles sont reprogrammées à chaque changement de la date de fin, et annulées si la personne s’abonne ou si l’accès disparaît. Les toucher ouvre l’accueil, sans paywall.

Paywall de fin. Au premier retour dans l’app après la fin d’un accès offert, si la personne n’est plus Premium et n’a jamais acheté, le paywall au plein tarif s’ouvre une seule fois (source promo_ended, fermable). Il passe avant le comeback et le paywall au retour, qui ne se déclenchent pas sur ce même retour. Il attend la réponse de RevenueCat (3 secondes au plus) et ne s’affiche qu’à un compte qui a fini l’onboarding ; s’il est empêché (autre paywall, demande de notifications, lien profond), il réessaie au retour suivant.

Profil : « Premium offert jusqu’au … » au lieu de « Premium actif ». Un accès à vie garde « Premium actif ».

Menu debug (identique sur les deux apps) : le sélecteur « Fin d’accès » propose les cas abonnement (fin dans 3 j, dans 60 j) et accès offert (fin dans 3 j, dans 30 j, à vie, expiré), et règle aussi l’état Premium ; dans la carte Comeback, un réglage « Accès offert passé » (Auto / Jamais / Oui), un bouton pour réinitialiser le paywall de fin et un bouton qui programme les deux notifications à +15 s et +30 s.

Mesure

Sur le site (PostHog, mêmes règles que le reste de kaiho.fr) :

Événement	Quand	Propriétés
promo_code_checked	Le code est vérifié, avant connexion	status : ok, invalid, expired, exhausted
promo_signin_started	La personne lance la connexion	method : apple, google, email
promo_code_redeem_result	Réponse à l’activation	status : ok, already_used, conference_limit, already_subscribed, account_not_set_up…
gift_checkout_started	Clic sur « Payer »	gift : 1y ou 3m
gift_purchased	Le code s’affiche sur la page de remerciement	gift

Côté serveur, chaque activation envoie promo_code_redeemed (code, kind, duration_days) sur la personne identifiée par l’app, et pose les propriétés personne promo_code et promo_code_kind. Elles permettent de découper la rétention et la conversion par conférence.

L’entonnoir code vérifié → connexion lancée → activé mesure ce que coûte le passage par le site.

Dans les apps :

• la carte de fin d’accès réutilise subscription_ending_viewed et subscription_ending_tapped, avec une nouvelle propriété access : promotional pour un accès offert, subscription pour un abonné qui a résilié ;
• le paywall s’ouvre avec la source promo_ending (tap sur la carte) ou promo_ended (fin de l’accès) ;
• les notifications de fin remontent dans notification_opened avec category: promo_ending.

Gérer les codes

Le dashboard d’administration vit sur admin.kaiho.fr, une section de HARU réservée à Arthur et protégée par Cloudflare Access (connexion Google, session d’un mois). Il est prêt mais pas encore en ligne : il attend la configuration d’Access. En attendant, les codes se créent directement en base.

• Synthèse : codes actifs, activations, accès en cours, cartes vendues, activées, en attente et remboursées, chiffre d’affaires des cartes, comptes devenus payants.
• Créer un code conférence : code libre ou généré, libellé, durée offerte (30 jours par défaut), dates, plafond, notes. Le lien kaiho.fr/code/LECODE et son QR code (PNG ou SVG) se téléchargent pour les supports de la conférence.
• Fiche d’un code : activations avec l’email du compte et la fin d’accès, désactivation (et réactivation). On ne supprime jamais un code déjà utilisé : on le désactive.
• Révoquer un accès : retire l’accès dans RevenueCat. Attention, RevenueCat retire alors tous les accès offerts du compte, pas seulement celui de ce code ; la confirmation le dit.
• Cartes cadeaux : ventes, statut, lien vers le paiement dans Stripe, email préparé pour renvoyer le code à l’acheteur. Un remboursement se fait dans Stripe ; le code est alors désactivé automatiquement s’il n’a pas servi.

« Devenus payants » est une approximation : comptes ayant activé le code et qui ont aujourd’hui un abonnement App Store ou Google Play actif, enregistré après l’activation. Ceux qui ont résilié depuis n’y figurent pas, et ceux qui se seraient abonnés de toute façon y sont comptés.