Dodaj program partnerski lub poleceń do swojej aplikacji Flutter.

Jakich pakietów potrzebujesz

Na pub.dev są dwa pakiety, oba na licencji MIT, z kodem źródłowym na github.com/influto/influto-flutter:

• influto — zawsze. Atrybucja, kody polecające, identyfikacja użytkowników, kody darmowego dostępu i ręczne zgłaszanie zakupów. Jedyne zależności to http i shared_preferences.

• influto_iap — tylko przy zakupach prosto ze sklepu. Dodaj go, jeśli aplikacja nie używa RevenueCat i sprzedaje przez wtyczkę in_app_purchase; przechwytuje zakupy automatycznie. Aplikacje z RevenueCat na purchases_flutter go nie potrzebują.

Wszystko idzie przez InfluTo.instance; nie ma wywołań statycznych. Instalacja:

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

Krok 1: zainicjuj bez wstrzymywania pierwszej klatki

Wywołaj initialize raz przy starcie i poczekaj na wynik, zanim wywołasz cokolwiek innego; do czasu sukcesu checkAttribution i reportPurchase rzucają InfluToException. Przy porażce (zły klucz, brak sieci) initialize też rzuca wyjątek, więc złap błąd, zaloguj go i działaj dalej. Następny start spróbuje ponownie.

Nie blokuj na tym pierwszej klatki: skonfiguruj RevenueCat, wywołaj runApp, a potem uruchom InfluTo z unawaited, jak niżej. Klucz API (it_…, w Setup & SDK) przekaż w czasie budowania przez --dart-define=INFLUTO_API_KEY=it_… i odczytaj go przez String.fromEnvironment.

checkAttribution mówi potem, czy instalacja pochodziła z polecenia i z którego kodu. Odpowiedź zapada raz na instalację i jest zapisana na urządzeniu, a błąd sieci zwraca attributed: false bez zapisywania czegokolwiek. Typowy main.dart:

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

Krok 2: pozwól użytkownikom wpisać kod

applyCode(code) sprawdza kod i stosuje go, jeśli jest poprawny; result.applied mówi, czy tak się stało. Kody są przycinane z białych znaków i zamieniane na wielkie litery, a niepoprawny kod zwraca valid: false z errorCode, np. CODE_NOT_FOUND lub CODE_EXPIRED.

Gotowa opcja to widżet ReferralCodeInput (Material). Sprawdza kod w trakcie pisania, stosuje go po kliknięciu, wstępnie wypełnia go przy instalacji przypisanej do linku i przyjmuje Twoje przetłumaczone teksty. Nazwę twórcy pokazuje tylko wtedy, gdy ustawisz showReferrerName.

Krok 3: podłącz zakupy

InfluTo wypłaca prowizję tylko od zakupów zweryfikowanych przez sklep. Wybierz dokładnie jedną ścieżkę na platformę:

• RevenueCat (purchases_flutter): przekaż w InfluToConfig revenueCatHook, który wywołuje Purchases.setAttributes, jak w main.dart wyżej. SDK wywołuje go raz, gdy znajdzie polecenie lub zostanie zastosowany kod, z influto_code i influto_referral. Potem podłącz webhook RevenueCat w Setup & SDK.

• Prosto ze sklepu (in_app_purchase): dodaj influto_iap, utwórz jeden InfluToPurchaseObserver i włącz go po zakończeniu initialize. Działa tylko wtedy, gdy aplikacja ma w Settings → Validation ustawione store-direct, więc ten sam build jest bezpieczny w aplikacji z RevenueCat.

Bez hooka nic nie ustawia atrybutu RevenueCat we Flutterze. W odróżnieniu od React Native nie ma tu automatycznego tagowania. Skonfiguruj RevenueCat przed checkAttribution i wywołaj identifyUser z app user ID z RevenueCat. InfluTo używa go jako zapasowego identyfikatora, gdy zdarzenie przychodzi bez atrybutu.

Co observer robi w Twojej aplikacji: kończy oczekujące zakupy (completePurchase), żeby sklep nie dostarczał ich ponownie ani nie zwracał pieniędzy. Jego uzupełnianie wsteczne wywołuje restorePurchases(), więc Twój własny listener przy starcie widzi też przywrócone zakupy (enable(backSync: false) to pomija). Na iOS przełącza też in_app_purchase na StoreKit 2, którego wymaga store-direct.

Produkty jednorazowe na Androidzie trafiają do oneTimeProductIds w observerze, nie do InfluToConfig. Aby zgłaszać zakupy samodzielnie, ustaw autoCapture: false, pomiń observera i wywołaj reportPurchase z podpisaną transakcją StoreKit 2 albo z purchaseToken z Play. Konfiguracja observera:

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

Krok 4: przetestuj całość od początku do końca

Zakupy w sandboxie nie przenoszą pieniędzy ani nie zmieniają statystyk:

1. 1

   Sprawdź Setup & SDK. Po pierwszym udanym initialize zobaczysz „SDK connected” wraz z platformą i wersją SDK. Z debug: true każdy krok jest wypisywany przez debugPrint.

2. 2

   Zasymuluj zakup. Simulate a purchase w Setup & SDK wysyła testowy zakup z sandboxa przez prawdziwy potok InfluTo. Wpisz jeden ze swoich kodów, żeby zobaczyć, jak zostanie rozpoznany.

3. 3

   Zainstaluj przez link polecający. Dołącz do swojej kampanii drugim kontem twórcy, otwórz jego link na urządzeniu testowym, zainstaluj i uruchom aplikację. Najpewniejszym testem jest wpisanie kodu.

4. 4

   Kup w sandboxie. Użyj testera TestFlight lub sandboxa (w store-direct na iOS najpierw ustaw środowisko Apple na Sandbox) albo testera licencji Google Play. Dziennik integracji przełączony na Sandbox pokaże zakup z przypisaniem. enable() zwraca liczby fetched, sent i failed, przydatne przy debugowaniu.

clearAttribution() resetuje urządzenie przed kolejną próbą.

Uwagi o Flutterze

Trzy rzeczy, na których najczęściej potykają się osoby integrujące Fluttera:

• Kolejność ma znaczenie. Skonfiguruj RevenueCat, potem initialize, potem checkAttribution. Observera influto_iap włączaj dopiero po zakończeniu initialize, inaczej pozostanie wyłączony.

• Konfiguracje const. InfluToConfig ma konstruktor const, ale domknięcie nie jest stałą. Gdy przekazujesz revenueCatHook, usuń const.

• Identyfikuj raz. Wywołuj identifyUser raz na logowanie, najlepiej w pierwszej sesji użytkownika, a nie z build.

Albo zleć to agentowi kodującemu

Podłącz serwer MCP InfluTo do Claude Code, Codex lub Cursor i poproś o integrację. Agent dopasuje projekt Dart do tego SDK, napisze kod dla wybranej ścieżki weryfikacji i będzie sprawdzać influto_integration_status, aż zakup z sandboxa dotrze z przypisaniem.