Adicione um programa de afiliados ou de indicação ao seu app Flutter.

Quais pacotes você precisa

Há dois pacotes no pub.dev, ambos com licença MIT, com código em github.com/influto/influto-flutter:

• influto, sempre. Atribuição, códigos de indicação, identificação de usuário, códigos de acesso gratuito e registro manual de compras. Suas únicas dependências são http e shared_preferences.

• influto_iap, só para captura direto da loja. Adicione se o seu app não usa RevenueCat e vende pelo plugin in_app_purchase; ele captura as compras automaticamente. Apps com RevenueCat e purchases_flutter não precisam dele.

Tudo passa por InfluTo.instance; não há chamadas estáticas. A instalação:

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

Passo 1: inicialize sem atrasar o primeiro frame

Chame initialize uma vez na inicialização e aguarde sua conclusão antes de chamar qualquer outra coisa; até ele ter sucesso, checkAttribution e reportPurchase lançam uma InfluToException. Ele lança erro quando falha (chave errada, sem rede), então capture o erro, registre no log e siga em frente. A próxima abertura tenta de novo.

Não bloqueie o primeiro frame com ele: configure o RevenueCat, chame runApp e só então inicie o InfluTo com unawaited, como abaixo. Passe a chave de API (it_…, em Setup & SDK) na compilação com --dart-define=INFLUTO_API_KEY=it_… e leia com String.fromEnvironment.

Depois, checkAttribution informa se a instalação veio por indicação e de qual código. A resposta é definida uma vez por instalação e guardada no dispositivo, e um erro de rede retorna attributed: false sem guardar nada. Um 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);
}

Passo 2: deixe os usuários digitarem um código

applyCode(code) valida um código e o aplica se for válido; result.applied indica se foi aplicado. Os códigos são limpos de espaços e convertidos para maiúsculas, e um código inválido retorna valid: false com um errorCode como CODE_NOT_FOUND ou CODE_EXPIRED.

A opção pronta é o widget ReferralCodeInput (Material). Ele valida enquanto o usuário digita, aplica o código ao toque, preenche o campo em instalações atribuídas por link e aceita seus textos traduzidos. Ele só mostra o nome do criador se você definir showReferrerName.

Passo 3: conecte as compras

O InfluTo só paga comissão sobre compras verificadas na loja. Escolha apenas um caminho por plataforma:

• RevenueCat (purchases_flutter): passe um revenueCatHook em InfluToConfig que chame Purchases.setAttributes, como no main.dart acima. O SDK o chama uma vez, quando uma indicação é encontrada ou um código é aplicado, com influto_code e influto_referral. Depois, conecte o webhook do RevenueCat em Setup & SDK.

• Direto da loja (in_app_purchase): adicione influto_iap, crie um InfluToPurchaseObserver e ative-o depois que initialize terminar. Ele só roda quando o app está configurado como direto da loja em Settings → Validation, então a mesma build é segura em um app com RevenueCat.

Sem o hook, nada define o atributo do RevenueCat no Flutter; ao contrário do React Native, não há marcação automática. Configure o RevenueCat antes de checkAttribution e chame identifyUser com o ID de usuário do app no RevenueCat. É o fallback que a InfluTo usa quando um evento chega sem o atributo.

O que o observer faz dentro do seu app: conclui as compras pendentes (completePurchase) para que a loja não as reenvie nem as reembolse; o preenchimento retroativo chama restorePurchases(), então seu próprio listener também vê as compras restauradas na inicialização (enable(backSync: false) evita isso); e no iOS ele muda o in_app_purchase para StoreKit 2, que o store-direct exige.

Os produtos únicos do Android entram em oneTimeProductIds do observer, não em InfluToConfig. Para reportar as compras por conta própria, defina autoCapture: false, dispense o observer e chame reportPurchase com a transação assinada do StoreKit 2 ou o purchaseToken do Play. A configuração do 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

Etapa 4: teste de ponta a ponta

Compras em sandbox nunca movimentam dinheiro nem alteram suas estatísticas:

1. 1

   Confira Setup & SDK. Depois do primeiro initialize bem-sucedido, aparece “SDK connected” com a plataforma e a versão do SDK; debug: true imprime cada etapa com debugPrint.

2. 2

   Simule uma compra. Simulate a purchase em Setup & SDK envia uma compra de teste em sandbox pelo pipeline real da InfluTo. Digite um dos seus códigos para ver a resolução.

3. 3

   Instale por um link de indicação. Entre na sua campanha com uma segunda conta de criador, abra o link em um dispositivo de teste, instale e abra o app. Digitar o código é o teste mais confiável.

4. 4

   Compre no sandbox. Use um testador do TestFlight ou do sandbox (no iOS store-direct, defina antes o ambiente Apple como Sandbox) ou um testador de licença do Google Play. O log de Integration, alternado para Sandbox, mostra a compra atribuída. enable() retorna as contagens de fetched, sent e failed para depuração.

clearAttribution() redefine o dispositivo para um novo teste.

Observações sobre Flutter

Três coisas que costumam atrapalhar as integrações com Flutter:

• A ordem importa. Configure o RevenueCat, depois initialize, depois checkAttribution. Ative o observer influto_iap só depois que initialize terminar, ou ele continua desligado.

• Configs const. InfluToConfig tem um construtor const, mas uma closure não é constante. Por isso, remova const ao passar um revenueCatHook.

• Identifique uma vez. Chame identifyUser uma vez por login, de preferência na primeira sessão do usuário, e não a partir de build.

Ou deixe seu agente de código fazer isso

Conecte o servidor MCP da InfluTo ao Claude Code, Codex ou Cursor e peça a integração: o agente associa um projeto Dart a este SDK, escreve o código do caminho de validação que você escolher e consulta influto_integration_status até chegar uma compra em sandbox atribuída.