Añade un programa de afiliados o de referidos a tu app Flutter.

Qué paquetes necesitas

Hay dos paquetes en pub.dev, ambos con licencia MIT y con el código en github.com/influto/influto-flutter:

• influto, siempre. Atribución, códigos de referido, identificación de usuarios, códigos de acceso gratuito e informe manual de compras. Solo depende de http y shared_preferences.

• influto_iap, solo para compras directas de la tienda. Añádelo si tu app no usa RevenueCat y vende con el plugin in_app_purchase; captura las compras automáticamente. Las apps con RevenueCat y purchases_flutter no lo necesitan.

Todo pasa por InfluTo.instance; no hay llamadas estáticas. La instalación:

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

Paso 1: inicializa sin retrasar el primer frame

Llama a initialize una vez al arrancar y espera a que termine antes de llamar a nada más; hasta que se complete con éxito, checkAttribution y reportPurchase lanzan una InfluToException. Lanza una excepción si falla (clave incorrecta, sin red), así que captura el error, regístralo y sigue. En el siguiente arranque vuelve a intentarlo.

No bloquees tu primer frame con esto: configura RevenueCat, llama a runApp y arranca InfluTo con unawaited, como abajo. Pasa la clave de API (it_…, en Setup & SDK) en tiempo de compilación con --dart-define=INFLUTO_API_KEY=it_… y léela con String.fromEnvironment.

Después, checkAttribution te dice si la instalación fue referida y con qué código. La respuesta se decide una vez por instalación y se guarda en el dispositivo; un error de red devuelve attributed: false sin guardar nada. Un main.dart típico:

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

Paso 2: deja que los usuarios escriban un código

applyCode(code) valida un código y lo aplica si es válido; result.applied indica si se aplicó. Los códigos se recortan y se pasan a mayúsculas, y uno inválido devuelve valid: false con un errorCode como CODE_NOT_FOUND o CODE_EXPIRED.

La opción lista para usar es el widget ReferralCodeInput (Material). Valida mientras el usuario escribe, aplica el código al tocar, lo rellena de antemano si la instalación viene de un enlace y acepta tus textos traducidos. Solo muestra el nombre del creador si activas showReferrerName.

Paso 3: conecta las compras

InfluTo solo paga comisión por compras verificadas con la tienda. Elige exactamente una vía por plataforma:

• RevenueCat (purchases_flutter): pasa un revenueCatHook en InfluToConfig que llame a Purchases.setAttributes, como en el main.dart de arriba. El SDK lo llama una sola vez, cuando encuentra un referido o se aplica un código, con influto_code e influto_referral. Después conecta el webhook de RevenueCat en Setup & SDK.

• Compra directa de la tienda (in_app_purchase): añade influto_iap, crea un InfluToPurchaseObserver y actívalo cuando initialize haya terminado. Solo se ejecuta si la app está configurada como compra directa en Settings → Validation, así que el mismo build es seguro en una app con RevenueCat.

Sin el hook, nada establece el atributo de RevenueCat en Flutter; a diferencia de React Native, no hay etiquetado automático. Configura RevenueCat antes de checkAttribution y llama a identifyUser con el app user ID de RevenueCat. InfluTo lo usa como respaldo cuando llega un evento sin el atributo.

Qué hace el observer dentro de tu app: completa las compras pendientes (completePurchase) para que la tienda no las reenvíe ni las reembolse; su relleno retroactivo llama a restorePurchases(), así que tu propio listener también ve las compras restauradas al arrancar (enable(backSync: false) lo evita); y en iOS cambia in_app_purchase a StoreKit 2, que store-direct necesita.

Los productos Android de pago único van en oneTimeProductIds del observer, no en InfluToConfig. Si prefieres reportar las compras tú mismo, usa autoCapture: false, omite el observer y llama a reportPurchase con la transacción firmada de StoreKit 2 o el purchaseToken de Play. La configuración del 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

Paso 4: pruébalo de principio a fin

Las compras en sandbox nunca mueven dinero ni cambian tus estadísticas:

1. 1

   Revisa Setup & SDK. Tras el primer initialize correcto aparece “SDK connected” con la plataforma y la versión del SDK; con debug: true se imprime cada paso con debugPrint.

2. 2

   Simula una compra. Simulate a purchase, en Setup & SDK, envía una compra de prueba en sandbox por el pipeline real de InfluTo. Introduce uno de tus códigos para ver cómo se resuelve.

3. 3

   Instala desde un enlace de referido. Únete a tu campaña con una segunda cuenta de creador, abre su enlace en un dispositivo de prueba, instala y abre la app. Escribir el código es la prueba más fiable.

4. 4

   Compra en el sandbox. Usa un tester de TestFlight o de sandbox (en iOS store-direct, cambia antes el entorno de Apple a Sandbox) o un license tester de Google Play. El Integration log, en modo Sandbox, muestra la compra atribuida. enable() devuelve los recuentos de fetched, sent y failed para depurar.

clearAttribution() restablece el dispositivo para otra prueba.

Notas sobre Flutter

Tres cosas que suelen dar problemas en las integraciones con Flutter:

• El orden importa. Configura RevenueCat, luego initialize y después checkAttribution. Activa el observer de influto_iap solo cuando initialize haya terminado; si no, se queda desactivado.

• Configs const. InfluToConfig tiene un constructor const, pero una función anónima no es una constante, así que quita const cuando pases un revenueCatHook.

• Identifica una sola vez. Llama a identifyUser una vez por inicio de sesión, idealmente en la primera sesión del usuario, no desde build.

O deja que lo haga tu agente de código

Conecta el servidor MCP de InfluTo a Claude Code, Codex o Cursor y pide la integración: el agente relaciona un proyecto Dart con este SDK, escribe el código para la vía de validación que elijas y consulta influto_integration_status hasta que llegue una compra de sandbox atribuida.