Aggiungi un programma di affiliazione o referral alla tua app Capacitor o Ionic.

Perché le app WebView possono attribuire più referral in modo esatto

Un'app nativa ottiene un abbinamento esatto da un codice digitato; un tap che passa dallo store viene abbinato in un secondo momento. Un'app WebView può ricevere il codice stesso, in tre modi:

• L'URL di avvio. Imposta Impostazioni → Generali → URL dell'app web: i link di referral vi indirizzano i visitatori da desktop (e da telefono, se non hai una scheda store per la loro piattaforma) con influto_code e influto_click in coda. initialize legge entrambi e ripulisce la barra degli indirizzi.

• I deep link. listenForCapacitorLaunchUrls(InfluTo) passa all'SDK l'URL di avvio a freddo e ogni evento appUrlOpen; in Cordova, chiama InfluTo.handleLaunchUrl(url).

• Il Play Install Referrer. I link Google Play di InfluTo portano il codice e il click nel parametro referrer di Play. Leggilo al primo avvio con un plugin Install Referrer e passalo a captureInstallReferrer.

Se non arriva nessun codice, InfluTo ripiega sull'abbinamento tramite click sul link entro 72 ore, che non confronta mai le caratteristiche del dispositivo.

Passo 1: installa

Aggiungi il pacchetto. Su Capacitor, tre plugin sono facoltativi ma consigliati: @capacitor/device per i dettagli del dispositivo, @capacitor/preferences per un archivio che sopravvive ai reset della WebView e @capacitor/app per i deep link. Dopo averli aggiunti, esegui npx cap sync; i plugin mancanti ripiegano sui valori predefiniti del browser.

Nessun bundler? Carica la build per tag script da https://cdn.jsdelivr.net/npm/@influto/web@1/dist/index.global.js e usa window.InfluTo. Contiene solo l'SDK di base; gli helper dei sottopercorsi richiedono un bundler.

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

Passo 2: inizializza una volta, al momento giusto

Chiama initialize una sola volta, alla radice dell'app, e aspetta che finisca. In caso di errore lancia un InfluToApiError (status, body): intercettalo, registralo e vai avanti; al prossimo avvio riprova. La tabella qui sotto indica quando chiamarlo per ogni runtime.

La chiave API (it_…, in Setup e SDK) vale sia per lo sviluppo sia per la produzione; tienila in un .env.local escluso da git e letto dal tuo bundler. Un tipico avvio di Capacitor in un'app con RevenueCat, in ordine:

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

Passo 3: riscatta in modo esatto le installazioni dal Play Store

Su Android, leggi la stringa referrer al primo avvio con @capgo/capacitor-install-referrer o cordova-play-install-referrer e passala dopo initialize, prima di checkAttribution. Un codice rilevato più tardi riapre una risposta “organica” precedente; un'installazione già attribuita mantiene il suo creator.

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

Passo 4: lascia che gli utenti digitino un codice

applyCode(code) verifica un codice digitato dall'utente e, se è valido, lo applica. I codici vengono ripuliti dagli spazi e convertiti in maiuscolo; uno non valido restituisce valid: false con un error_code come CODE_NOT_FOUND o CODE_EXPIRED.

In React e Ionic React, ReferralCodeInput da @influto/web/react è un semplice form senza stile che precompila un codice arrivato da un link e lo applica all'invio. In Angular, Vue o senza framework, costruisci il campo su applyCode.

Passo 5: collega gli acquisti

InfluTo paga commissioni solo sugli acquisti verificati con lo store. Scegli un percorso per piattaforma:

• RevenueCat: passa un binding come revenueCat: revenueCatCapacitor(Purchases) per @revenuecat/purchases-capacitor 7.5.10+, revenueCatCordova(window.Purchases) per cordova-plugin-purchases, oppure revenueCatJs per purchases-js. Collegalo prima di checkAttribution, perché l'attributo viene scritto quando il referral viene trovato; le scritture fallite vengono ritentate fino a 3 volte.

• Direttamente con lo store: passa un purchaseSource (vedi la tabella). Quando l'app è impostata su store diretto in Impostazioni → Validazione, initialize segnala i nuovi acquisti e recupera quelli esistenti, ciascuno una sola volta.

Su iOS, la modalità store diretto richiede la transazione firmata di StoreKit 2: capgoNativePurchasesSource la inoltra, mentre con cordova-plugin-purchase devi verificare che la tua configurazione ne esponga una. Su Android queste fonti non portano il prezzo, quindi segnala tu i prodotti una tantum con price e currency, altrimenti vengono registrati a 0 $.

In una TWA, la Digital Goods API non ha un evento di acquisto: chiama InfluTo.syncExistingPurchases() dopo ogni checkout; digitalGoodsSource cerca il prezzo al posto tuo.

Insidie delle piattaforme

La maggior parte delle integrazioni WebView che falliscono dipende da uno di questi punti:

• Archiviazione di Capacitor. Con @capacitor/preferences installato, l'SDK salva lì il proprio stato; il localStorage della WebView viene cancellato quando cambia androidScheme o iosScheme.

• ionic serve. In una build di sviluppo web il plugin RevenueCat per Capacitor è solo una finta implementazione, quindi le scritture degli attributi non fanno nulla. Prova su un dispositivo.

• Cordova blocca l'API per impostazione predefinita. Un template nuovo richiede una voce access origin per https://influ.to in config.xml e connect-src https://influ.to nella Content-Security-Policy. RevenueCat ha dichiarato obsoleto il suo plugin per Cordova: per una nuova app, scegli Capacitor.

• Browser e PWA. In un browser o in una PWA passa sempre platform (ios o android) a reportPurchase: l'SDK non lo indovina quando rileva il web. Le web app iOS aggiunte alla schermata Home non possono vendere acquisti in-app, ma l'attribuzione funziona comunque.

Passaggio 6: provalo

Gli acquisti di test non spostano denaro e non cambiano le tue statistiche:

1. 1

   Controlla Setup & SDK. Dopo il primo initialize riuscito compare “SDK connected” con la piattaforma, @influto/web e la versione dell'SDK. Con debug: true ogni passaggio viene registrato nel log.

2. 2

   Simula un acquisto. Simulate a purchase in Setup & SDK invia un acquisto di test sandbox nella vera pipeline di InfluTo. Inserisci uno dei tuoi codici per vedere come viene riconosciuto.

3. 3

   Prova un'installazione da referral su un dispositivo. Apri il link di referral di un creator su un dispositivo di test, installa l'app, avviala e acquista con un tester sandbox, TestFlight o licenza. L'Integration log, impostato su Sandbox, mostra l'acquisto attribuito.

clearAttribution() cancella l'attribuzione salvata, il codice e il codice di avvio, così puoi ripetere la prova. Se colleghi un agente di coding via MCP, può eseguire questi controlli al posto tuo.