Ajoutez un programme d’affiliation ou de parrainage à votre app Capacitor ou Ionic.

Pourquoi les apps WebView peuvent attribuer plus de parrainages avec exactitude

Une app native obtient une correspondance exacte à partir d’un code saisi ; un clic qui passe par le store est rapproché après coup. Une app WebView peut recevoir le code elle-même, de trois façons :

• L’URL de lancement. Renseignez Paramètres → Général → URL de l’app web : les liens de parrainage y envoient les visiteurs sur ordinateur (et sur mobile, si vous n’avez pas de fiche de store pour leur plateforme), avec influto_code et influto_click ajoutés. initialize lit les deux et nettoie la barre d’adresse.

• Les deep links. listenForCapacitorLaunchUrls(InfluTo) transmet au SDK l’URL de démarrage à froid et chaque événement appUrlOpen ; avec Cordova, appelez InfluTo.handleLaunchUrl(url).

• Le Play Install Referrer. Les liens Google Play d’InfluTo portent le code et le clic dans le paramètre referrer de Play. Lisez-le au premier lancement avec un plugin Install Referrer, puis passez-le à captureInstallReferrer.

Sans code transmis, InfluTo se rabat sur le rapprochement par clic sur le lien dans un délai de 72 heures, qui ne compare jamais les caractéristiques de l’appareil.

Étape 1 : installer

Ajoutez le package. Sur Capacitor, trois plugins sont facultatifs mais recommandés : @capacitor/device pour les infos de l’appareil, @capacitor/preferences pour un stockage qui survit aux réinitialisations de la WebView, et @capacitor/app pour les deep links. Lancez npx cap sync après les avoir ajoutés ; si un plugin manque, le SDK utilise les valeurs par défaut du navigateur.

Pas de bundler ? Chargez la version balise script depuis https://cdn.jsdelivr.net/npm/@influto/web@1/dist/index.global.js et utilisez window.InfluTo. Elle ne contient que le cœur du SDK ; les helpers par sous-chemin exigent un bundler.

npm install @influto/web
# Capacitor / Ionic apps (device info, storage, deep links):
npm install @capacitor/device @capacitor/preferences @capacitor/app

Étape 2 : initialiser une seule fois, au bon moment

Appelez initialize une seule fois, à la racine de l’app, et attendez son résultat. En cas d’échec, il lève une InfluToApiError (status, body) : interceptez-la, journalisez-la et continuez ; le lancement suivant réessaiera. Le tableau ci-dessous indique quand l’appeler selon l’environnement.

La clé d’API (it_…, dans Configuration & SDK) sert en développement comme en production ; gardez-la dans un .env.local ignoré par git, lu via votre bundler. Un démarrage Capacitor type sur une app RevenueCat, dans l’ordre :

import InfluTo from '@influto/web';
import { capacitorAdapters, listenForCapacitorLaunchUrls } from '@influto/web/capacitor';
import { revenueCatCapacitor } from '@influto/web/revenuecat';
import { Purchases } from '@revenuecat/purchases-capacitor';

export async function startInfluTo() {
  await Purchases.configure({ apiKey: 'appl_…' }); // RevenueCat apps: configure it first
  try {
    await InfluTo.initialize({
      apiKey: import.meta.env.VITE_INFLUTO_API_KEY,
      appVersion: '1.4.0',
      ...(await capacitorAdapters()),
      revenueCat: revenueCatCapacitor(Purchases),
    });
  } catch (error) {
    console.warn('InfluTo initialize failed', error); // retried on the next launch
    return;
  }
  await listenForCapacitorLaunchUrls(InfluTo); // deep links → referral claim
  const attribution = await InfluTo.checkAttribution();
  const { appUserID } = await Purchases.getAppUserID();
  await InfluTo.identifyUser(appUserID);
}

Étape 3 : retrouver exactement les installations Play Store

Sur Android, lisez la chaîne referrer au premier lancement avec @capgo/capacitor-install-referrer ou cordova-play-install-referrer, puis transmettez-la après initialize et avant checkAttribution. Un code récupéré plus tard rouvre une réponse « organique » antérieure ; une installation attribuée garde son créateur.

await InfluTo.captureInstallReferrer(referrer); // the raw referrer string from the plugin
const attribution = await InfluTo.checkAttribution();

Étape 4 : laisser les utilisateurs saisir un code

applyCode(code) vérifie un code saisi par l’utilisateur et l’applique s’il est valide. Les codes sont nettoyés des espaces et passés en majuscules ; un code invalide renvoie valid: false avec un error_code comme CODE_NOT_FOUND ou CODE_EXPIRED.

Avec React et Ionic React, ReferralCodeInput de @influto/web/react est un formulaire simple, sans style, qui préremplit un code issu d’un lien et l’applique à l’envoi. Avec Angular, Vue ou sans framework, construisez le champ sur applyCode.

Étape 5 : connecter les achats

InfluTo ne verse de commission que sur les achats vérifiés auprès du store. Choisissez une voie par plateforme :

• RevenueCat : passez un binding via revenueCat: revenueCatCapacitor(Purchases) pour @revenuecat/purchases-capacitor 7.5.10+, revenueCatCordova(window.Purchases) pour cordova-plugin-purchases, ou revenueCatJs pour purchases-js. Attachez-le avant checkAttribution, car l’attribut est écrit au moment où le parrainage est trouvé ; les écritures échouées sont retentées jusqu’à 3 fois.

• Direct via le store : passez une purchaseSource (voir le tableau). Quand l’app est réglée sur « direct via le store » dans Paramètres → Validation, initialize signale les nouveaux achats et rattrape les achats existants, chacun une seule fois.

Sur iOS, le mode direct via le store exige la transaction signée StoreKit 2 : capgoNativePurchasesSource la transmet, alors qu’avec cordova-plugin-purchase, vérifiez que votre configuration en expose une. Sur Android, ces sources ne fournissent aucun prix : signalez vous-même les produits à achat unique avec price et currency, sinon ils sont enregistrés à 0 $.

Dans une TWA, la Digital Goods API n’a pas d’événement d’achat : appelez InfluTo.syncExistingPurchases() après chaque paiement ; digitalGoodsSource récupère le prix pour vous.

Pièges propres aux plateformes

La plupart des intégrations WebView qui échouent tiennent à l’une de ces causes :

• Stockage Capacitor. Si @capacitor/preferences est installé, le SDK y stocke son état ; le localStorage de la WebView est effacé quand androidScheme ou iosScheme change.

• ionic serve. Dans un build de développement web, le plugin Capacitor de RevenueCat n’est qu’une doublure : les écritures d’attributs n’y font rien. Testez sur un appareil.

• Cordova bloque l’API par défaut. Un modèle neuf demande une entrée access origin pour https://influ.to dans config.xml, et connect-src https://influ.to dans la Content-Security-Policy. RevenueCat a abandonné son plugin Cordova : pour une nouvelle app, préférez Capacitor.

• Navigateurs et PWA. Dans un navigateur ou une PWA, passez toujours platform (ios ou android) à reportPurchase : le SDK ne le devine pas quand il détecte le web. Les web apps ajoutées à l’écran d’accueil sur iOS ne peuvent pas vendre d’achats intégrés, mais l’attribution fonctionne quand même.

Étape 6 : testez

Les achats de test ne déplacent jamais d’argent et ne modifient pas vos statistiques :

1. 1

   Consultez Setup & SDK. Après le premier initialize réussi, la page affiche « SDK connected » avec la plateforme, @influto/web et la version du SDK. Avec debug: true, chaque étape est consignée dans les logs.

2. 2

   Simulez un achat. Simulate a purchase, dans Setup & SDK, envoie un achat de test sandbox dans le vrai pipeline d’InfluTo. Saisissez l’un de vos codes pour voir comment il est reconnu.

3. 3

   Lancez une installation parrainée sur un appareil. Ouvrez le lien de parrainage d’un créateur sur un appareil de test, installez l’app, lancez-la et achetez avec un testeur sandbox, TestFlight ou de licence. Le journal d’intégration, réglé sur Sandbox, affiche l’achat attribué.

clearAttribution() efface l’attribution enregistrée, le code et le code de lancement pour repartir de zéro. Si un agent de code est connecté via MCP, il peut lancer ces vérifications à votre place.