Додайте партнерську чи реферальну програму у свій застосунок на Flutter.

Які пакети вам потрібні

На pub.dev є два пакети, обидва з ліцензією MIT, код — github.com/influto/influto-flutter:

• influto — завжди. Атрибуція, реферальні коди, ідентифікація користувача, коди безкоштовного доступу та ручна передача покупок. Єдині залежності — http і shared_preferences.

• influto_iap — лише для прямого збору зі стору. Додайте його, якщо застосунок не використовує RevenueCat і продає через плагін in_app_purchase: пакет фіксує покупки автоматично. Застосункам із RevenueCat на purchases_flutter він не потрібен.

Усе працює через InfluTo.instance, статичних викликів немає. Встановлення:

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

Крок 1: ініціалізація без затримки першого кадру

Викличте initialize один раз на старті й дочекайтеся його, перш ніж викликати щось інше: доки він не завершився успішно, checkAttribution і reportPurchase кидають InfluToException. У разі помилки (хибний ключ, немає мережі) метод кидає виняток, тож перехопіть його, запишіть у лог і працюйте далі. Наступного запуску спроба повториться.

Не блокуйте через нього перший кадр: налаштуйте RevenueCat, викличте runApp, а потім запустіть InfluTo через unawaited, як нижче. API-ключ (it_…, у розділі Setup & SDK) передайте під час збірки через --dart-define=INFLUTO_API_KEY=it_… і читайте через String.fromEnvironment.

Далі checkAttribution скаже, чи було встановлення за запрошенням і з яким кодом. Відповідь визначається один раз на встановлення й зберігається на пристрої. Якщо сталася помилка мережі, повертається attributed: false, і нічого не зберігається. Типовий 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);
}

Крок 2: дозвольте користувачам вводити код

applyCode(code) перевіряє код і застосовує його, якщо він дійсний; result.applied показує, чи так сталося. Код обрізається від пробілів і переводиться у верхній регістр, а недійсний повертає valid: false з errorCode, наприклад CODE_NOT_FOUND або CODE_EXPIRED.

Готовий варіант — віджет ReferralCodeInput (Material). Він перевіряє код під час введення, застосовує його по тапу, підставляє заздалегідь для встановлення за посиланням і приймає ваші перекладені тексти. Ім'я автора він показує, лише якщо ви задасте showReferrerName.

Крок 3: підключіть покупки

InfluTo нараховує комісію лише за покупки, підтверджені стором. Для кожної платформи оберіть один шлях:

• RevenueCat (purchases_flutter): передайте в InfluToConfig revenueCatHook, що викликає Purchases.setAttributes, як у main.dart вище. SDK викликає його один раз, коли знайдено запрошення або застосовано код, з influto_code та influto_referral. Потім підключіть вебхук RevenueCat у Setup & SDK.

• Напряму зі стору (in_app_purchase): додайте influto_iap, створіть один InfluToPurchaseObserver і ввімкніть його після завершення initialize. Він працює, лише коли для застосунку в Settings → Validation вибрано прямий збір зі стору, тож та сама збірка безпечна й для застосунку з RevenueCat.

Без хука жоден код не встановлює атрибут RevenueCat у Flutter: на відміну від React Native, автоматичного тегування тут немає. Налаштуйте RevenueCat до checkAttribution і викличте identifyUser з app user ID RevenueCat. InfluTo використовує його як запасний варіант, коли подія приходить без атрибута.

Що observer робить у вашому застосунку: завершує відкладені покупки (completePurchase), щоб магазин не надсилав їх повторно й не повертав кошти; його зворотне заповнення викликає restorePurchases(), тож ваш власний слухач теж бачить відновлені покупки на старті (enable(backSync: false) це вимикає); а на iOS перемикає in_app_purchase на StoreKit 2, який потрібен для store-direct.

Одноразові продукти Android додаються в oneTimeProductIds в observer, а не в InfluToConfig. Щоб повідомляти про покупки самостійно, задайте autoCapture: false, пропустіть observer і викличте reportPurchase із підписаною транзакцією StoreKit 2 або purchaseToken з Play. Налаштування 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

Крок 4: перевірте все від початку до кінця

Покупки в пісочниці не переміщують гроші й не змінюють вашу статистику:

1. 1

   Перевірте Setup & SDK. Після першого успішного initialize там з’явиться «SDK connected» із платформою та версією SDK; debug: true виводить кожен крок через debugPrint.

2. 2

   Симулюйте покупку. Simulate a purchase на сторінці Setup & SDK надсилає тестову покупку з пісочниці через справжній конвеєр InfluTo. Введіть один зі своїх кодів, щоб побачити, як він розпізнається.

3. 3

   Встановіть через реферальне посилання. Приєднайтеся до своєї кампанії з другого акаунта автора, відкрийте його посилання на тестовому пристрої, встановіть і запустіть застосунок. Найнадійніший тест — ввести код вручну.

4. 4

   Купіть у пісочниці. Скористайтеся тестувальником TestFlight чи sandbox (на iOS зі store-direct спершу переключіть середовище Apple на Sandbox) або ліцензійним тестувальником Google Play. Журнал Integration, перемкнений на Sandbox, показує покупку з атрибуцією. enable() повертає кількість отриманих, надісланих і невдалих записів для налагодження.

clearAttribution() скидає пристрій для наступного прогону.

Нотатки про Flutter

Три речі, на яких найчастіше спотикаються під час інтеграції у Flutter:

• Порядок важливий. Налаштуйте RevenueCat, потім initialize, потім checkAttribution. Вмикайте observer influto_iap лише після завершення initialize, інакше він лишиться вимкненим.

• const-конфіги. InfluToConfig має const-конструктор, але замикання не є константою, тож прибирайте const, коли передаєте revenueCatHook.

• Ідентифікуйте один раз. Викликайте identifyUser один раз за вхід, найкраще в першій сесії користувача, а не з build.

Або доручіть це кодинг-агентові

Підключіть MCP-сервер InfluTo до Claude Code, Codex або Cursor і попросіть інтеграцію: агент зіставить Dart-проєкт із цим SDK, напише код для обраного вами шляху валідації та перевірятиме influto_integration_status, доки не надійде покупка з пісочниці з атрибуцією.