Aggiungi un programma di affiliazione o referral alla tua app Flutter.

Quali pacchetti ti servono

Su pub.dev ci sono due pacchetti, entrambi con licenza MIT, con sorgente su github.com/influto/influto-flutter:

• influto, sempre. Attribuzione, codici referral, identificazione dell'utente, codici di accesso gratuito e segnalazione manuale degli acquisti. Le uniche dipendenze sono http e shared_preferences.

• influto_iap, solo per l'acquisizione dallo store. Aggiungilo se la tua app non usa RevenueCat e vende tramite il plugin in_app_purchase: cattura gli acquisti in automatico. Le app RevenueCat con purchases_flutter non ne hanno bisogno.

Tutto passa da InfluTo.instance; non ci sono chiamate statiche. L'installazione:

flutter pub add influto
# optional: automatic store-direct purchase capture
flutter pub add influto_iap

Passaggio 1: inizializza senza bloccare il primo frame

Chiama initialize una sola volta all'avvio e aspettane il completamento prima di chiamare altro: finché non è riuscito, checkAttribution e reportPurchase lanciano una InfluToException. Se fallisce (chiave errata, assenza di rete) lancia un errore: intercettalo, registralo e vai avanti. Il prossimo avvio riproverà.

Non bloccare il primo frame per questo: configura RevenueCat, chiama runApp, poi avvia InfluTo con unawaited, come sotto. Passa la chiave API (it_…, in Setup & SDK) in fase di build con --dart-define=INFLUTO_API_KEY=it_… e leggila con String.fromEnvironment.

checkAttribution ti dice poi se l'installazione arriva da un referral e da quale codice. La risposta viene decisa una sola volta per installazione e salvata sul dispositivo; un errore di rete restituisce attributed: false senza salvare nulla. Un main.dart tipico:

import 'dart:async';
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:influto/influto.dart';
import 'package:purchases_flutter/purchases_flutter.dart'; // only if you use RevenueCat

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Purchases.configure(PurchasesConfiguration('appl_…')); // RevenueCat apps: configure it first
  runApp(const MyApp());
  unawaited(startInfluTo());
}

Future<void> startInfluTo() async {
  try {
    await InfluTo.instance.initialize(InfluToConfig(
      apiKey: const String.fromEnvironment('INFLUTO_API_KEY'),
      appVersion: '1.4.0',
      revenueCatHook: (attrs) => Purchases.setAttributes(attrs),
    ));
  } catch (e) {
    debugPrint('InfluTo initialize failed: $e'); // retried on the next launch
    return;
  }
  final attribution = await InfluTo.instance.checkAttribution();
  await InfluTo.instance.identifyUser(await Purchases.appUserID);
}

Passaggio 2: lascia che gli utenti digitino un codice

applyCode(code) verifica un codice e lo applica se è valido; result.applied ti dice se è stato applicato. I codici vengono ripuliti dagli spazi e convertiti in maiuscolo; uno non valido restituisce valid: false con un errorCode come CODE_NOT_FOUND o CODE_EXPIRED.

L'opzione pronta è il widget ReferralCodeInput (Material). Valida mentre l'utente digita, applica il codice al tocco, lo precompila per un'installazione attribuita tramite link e accetta i tuoi testi tradotti. Mostra il nome di un creator solo se imposti showReferrerName.

Passaggio 3: collega gli acquisti

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

• RevenueCat (purchases_flutter): passa un revenueCatHook in InfluToConfig che chiami Purchases.setAttributes, come nel main.dart qui sopra. L'SDK lo chiama una sola volta, quando trova un referral o viene applicato un codice, con influto_code e influto_referral. Poi collega il webhook di RevenueCat in Setup & SDK.

• Direttamente dallo store (in_app_purchase): aggiungi influto_iap, crea un solo InfluToPurchaseObserver e attivalo dopo che initialize è terminato. Funziona solo se l'app è impostata su store-direct in Settings → Validation, quindi la stessa build è sicura anche su un'app RevenueCat.

Senza l'hook, in Flutter nulla imposta l'attributo RevenueCat: a differenza di React Native, non c'è tagging automatico. Configura RevenueCat prima di checkAttribution e chiama identifyUser con l'app user ID di RevenueCat, che InfluTo usa come riserva quando arriva un evento senza l'attributo.

Cosa fa l'observer dentro la tua app: completa gli acquisti in sospeso (completePurchase) perché lo store non li riconsegni né li rimborsi; il suo back-fill chiama restorePurchases(), quindi anche il tuo listener vede gli acquisti ripristinati all'avvio (enable(backSync: false) lo salta); e su iOS porta in_app_purchase a StoreKit 2, che serve allo store-direct.

I prodotti Android una tantum vanno in oneTimeProductIds dell'observer, non in InfluToConfig. Per segnalare gli acquisti da solo, imposta autoCapture: false, salta l'observer e chiama reportPurchase con la transazione firmata StoreKit 2 o il purchaseToken di Play. La configurazione dell'observer:

import 'package:influto_iap/influto_iap.dart';

final observer = InfluToPurchaseObserver(
  oneTimeProductIds: {'coins_100', 'remove_ads'}, // Android one-time products; omit if you only sell subscriptions
);
final sync = await observer.enable(); // listens for new purchases + back-fills existing ones

Passo 4: testa tutto da capo a fondo

Gli acquisti in sandbox non muovono denaro e non cambiano le tue statistiche:

1. 1

   Controlla Setup & SDK. Dopo il primo initialize riuscito compare “SDK connected” con la piattaforma e la versione dell'SDK; con debug: true ogni passaggio viene stampato con debugPrint.

2. 2

   Simula un acquisto. Simulate a purchase in Setup & SDK invia un acquisto di prova in sandbox attraverso la vera pipeline di InfluTo. Inserisci uno dei tuoi codici per vederlo risolversi.

3. 3

   Installa tramite un link referral. Unisciti alla tua campagna con un secondo account creator, apri il suo link su un dispositivo di test, installa e avvia l'app. Digitare il codice è il test più affidabile.

4. 4

   Acquista in sandbox. Usa un tester TestFlight o sandbox (su iOS store-direct, imposta prima l'ambiente Apple su Sandbox) oppure un license tester di Google Play. Il log Integration, impostato su Sandbox, mostra l'acquisto attribuito. enable() restituisce i conteggi fetched, sent e failed per il debug.

clearAttribution() reimposta il dispositivo per un'altra prova.

Note su Flutter

Tre cose che fanno inciampare nelle integrazioni Flutter:

• L'ordine conta. Configura RevenueCat, poi initialize, poi checkAttribution. Abilita l'observer influto_iap solo dopo che initialize è terminato, altrimenti resta spento.

• Config const. InfluToConfig ha un costruttore const, ma una closure non è una costante: togli const quando passi un revenueCatHook.

• Identifica una sola volta. Chiama identifyUser una volta per accesso, meglio nella prima sessione dell'utente, non da build.

Oppure lascia fare al tuo agente di coding

Collega il server MCP di InfluTo a Claude Code, Codex o Cursor e chiedi l'integrazione: l'agente associa un progetto Dart a questo SDK, scrive il codice per il percorso di validazione che scegli e controlla influto_integration_status finché non arriva un acquisto sandbox attribuito.