Flutter SDKでFlow & Paywall Builderを使ったアプリ内課金の有効化

アプリ内課金を有効にするには、3つの重要な概念を理解する必要があります。

• プロダクト – ユーザーが購入できるもの（サブスクリプション、消耗型アイテム、永続アクセス）
• フロー – ノーコードの Flow & Paywall Builder で作成した、プロダクトをユーザーに提示する画面シーケンス。SDK は getFlow を使って取得します。UI を独自のコードで実装したい場合は、代わりにペイウォールを使用してください — ペイウォールを手動で実装するを参照。
• プレースメント – アプリ内でフローを表示する場所とタイミング（main、onboarding、settings など）。ダッシュボードでフローをプレースメントに紐付け、コード内ではプレースメント ID で取得します。これにより、A/B テストの実施や異なるユーザーへの異なるフロー表示が簡単に行えます。

Adaptyでは、アプリ内課金を有効にする方法を3つ提供しています。アプリの要件に応じていずれかを選択してください：

Adapty フロー & ペイウォールビルダーで作成したフローを表示するには、アプリのコード内で以下の操作を行うだけです。

1. フローを取得する: Adaptyからフローを取得します。
2. 表示するだけで購入処理はAdaptyが行います: アプリにビューを表示します。
3. ボタンアクションを処理する: ユーザー操作をアプリの応答に関連付けます。たとえば、ユーザーがボタンをクリックしたときにリンクを開いたり、フローを閉じたりします。

始める前に

始める前に、以下の手順を完了してください：

1. Adapty ダッシュボードでアプリを App Store および/または Google Play に接続する。
2. Adapty でプロダクトを作成する。
3. フローを作成し、プロダクトを追加する。
4. プレースメントを作成し、フローを追加する。
5. アプリのコードに Adapty SDK をインストールして有効化する。このガイドでは Adapty Flutter SDK v4 の API を使用します。

1. フローを取得する

フローは、ダッシュボードで設定されたプレースメントと関連付けられています。プレースメントを使用すると、異なるオーディエンスに異なるフローを表示したり、A/B テストを実施したりできます。

Adapty Flow & Paywall Builder で作成したフローを取得するには、以下の手順を行います：

1. getFlow メソッドを使用してプレースメント ID から flow オブジェクトを取得し、hasViewConfiguration プロパティを使ってビルダーで作成されたものかどうかを確認します。

2. createFlowView メソッドを使用してフロービューを作成します。ビューにはフローの表示に必要な UI 要素とスタイルが含まれています。

try {
  // the requested flow
  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
  final view = await AdaptyUI().createFlowView(
    flow: flow,
  );
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
  // handle the error
}

2. フローを表示する

フローのビューが用意できたら、あとは数行追加するだけで表示できます。

フローを表示するには、createFlowView メソッドで作成した view に対して view.present() メソッドを呼び出します。各 view は一度しか表示できません。閉じた後はメモリから解放されます。再度フローを表示する必要がある場合は、createFlowView をもう一度呼び出して新しい view インスタンスを作成してください。

try {
  await view.present();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

3. ボタンアクションの処理

ユーザーがフロー内のボタンをクリックすると、Flutter SDK は購入・復元・画面を閉じる・URL を開くなどの操作を自動的に処理します。ただし、カスタムまたは事前定義された ID を持つボタンについては、コード側でアクションを処理する必要があります。

フロー画面上のプロセスを制御・監視するには、AdaptyUIFlowsEventsObserver のメソッドを実装し、画面を表示する前にオブザーバーを設定してください。ユーザーが何らかのアクションを実行すると flowViewDidPerformAction が呼び出されるので、アクション ID に応じてアプリが適切に応答する必要があります。

3つのオブザーバーメソッドが必須です：flowViewDidFinishPurchase、flowViewDidFinishRestore、flowViewDidReceiveError — これらがないとクラスはコンパイルエラーになります。

ウィジェットではなく、専用の長命なオブジェクトとしてオブザーバーを実装してください。アプリ全体で1つのグローバルなオブザーバースロットが共有されるため、State にバインドするとその画面がリークし（SDKが強参照を保持するため）、次の画面が登録された時点でサイレントに上書きされてしまいます。extends を使うことでSDKのデフォルト動作も継承されるため、必須の3つのメソッドに加え、必要なコールバックだけをオーバーライドすれば十分です。

// A dedicated, long-lived handler for flow events.
// It does NOT live inside a Widget/State, so it never leaks and is never
// silently replaced when screens are pushed or popped.
class FlowEventsHandler extends AdaptyUIFlowsEventsObserver {
  // A single, app-wide instance — same idiom as Adapty() and AdaptyUI().
  static final FlowEventsHandler _instance = FlowEventsHandler._();
  factory FlowEventsHandler() => _instance;
  FlowEventsHandler._();

  // This method is called when user performs an action on the flow UI.
  // Overriding it replaces the default behavior (dismiss on close, open URLs),
  // so keep those cases if you want to preserve it.
  @override
  void flowViewDidPerformAction(AdaptyUIFlowView view, AdaptyUIAction action) {
    switch (action) {
      case const CloseAction():
      case const AndroidSystemBackAction(): // close the flow on the Android back button
        view.dismiss();
        break;
      case OpenUrlAction(:final url, :final openIn):
        AdaptyUI().openUrl(url, openIn: openIn);
        break;
      default:
        break;
    }
  }

  // Required: decide what happens after a purchase finishes
  @override
  void flowViewDidFinishPurchase(AdaptyUIFlowView view,
      AdaptyPaywallProduct product, AdaptyPurchaseResult purchaseResult) {
    if (purchaseResult is! AdaptyPurchaseResultUserCancelled) {
      view.dismiss();
    }
  }

  // Required: dismiss the flow once a restore succeeds
  @override
  void flowViewDidFinishRestore(AdaptyUIFlowView view, AdaptyProfile profile) {
    view.dismiss();
  }

  // Required: handle rendering and other view errors
  @override
  void flowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) {
    print('Flow error: $error');
    view.dismiss();
  }
}

ハンドラーは、フローが表示される前のアプリ起動時に 一度だけ 登録してください：

AdaptyUI().setFlowsEventsObserver(FlowEventsHandler());

次のステップ

ペイウォールはアプリに表示する準備が整いました。App Store サンドボックスまたはGoogle Play Storeでテスト購入を試して、ペイウォールからテスト購入が完了できることを確認してください。

次に、ユーザーのアクセスレベルを確認して、適切なユーザーにペイウォールを表示したり有料機能へのアクセスを付与したりできるようにする必要があります。

完全なコード例

以下に、これらのすべてのステップをアプリに統合した場合の完全なサンプルコードを示します。

void main() {
  // Register a single, long-lived observer once, before any flow is shown.
  // It is intentionally a plain object (NOT a Widget/State): its lifetime is the
  // whole app, so it never leaks and is never silently replaced when screens are
  // pushed or popped.
  AdaptyUI().setFlowsEventsObserver(FlowEventsHandler());

  runApp(MaterialApp(home: FlowScreen()));
}

/// A dedicated handler for AdaptyUI flow events.
///
/// It `extends` [AdaptyUIFlowsEventsObserver] (rather than being implemented
/// by a `State`), which gives you two things for free:
///   * the SDK's sensible defaults for optional callbacks, so besides the three
///     required methods you only override what you actually care about;
///   * a lifecycle that is independent of the widget tree — there is no strong
///     reference back into a `Widget`, so nothing leaks and there is nothing to
///     unregister.
///
/// Every callback receives the [AdaptyUIFlowView] it relates to, so handling
/// flow actions never requires a `BuildContext` or widget state.
class FlowEventsHandler extends AdaptyUIFlowsEventsObserver {
  // A single, app-wide instance — same idiom as Adapty() and AdaptyUI().
  static final FlowEventsHandler _instance = FlowEventsHandler._();
  factory FlowEventsHandler() => _instance;
  FlowEventsHandler._();

  // Called when the user performs an action on the flow UI.
  @override
  void flowViewDidPerformAction(AdaptyUIFlowView view, AdaptyUIAction action) {
    switch (action) {
      case const CloseAction():
      case const AndroidSystemBackAction(): // close the flow on the Android back button
        view.dismiss();
        break;
      case OpenUrlAction(:final url, :final openIn):
        // Open the URL natively, honoring the dashboard browser setting.
        AdaptyUI().openUrl(url, openIn: openIn);
        break;
      default:
        break;
    }
  }

  // Required: decide what happens after a purchase finishes.
  @override
  void flowViewDidFinishPurchase(AdaptyUIFlowView view,
      AdaptyPaywallProduct product, AdaptyPurchaseResult purchaseResult) {
    if (purchaseResult is! AdaptyPurchaseResultUserCancelled) {
      view.dismiss();
    }
  }

  // Required: dismiss the flow once a restore succeeds.
  @override
  void flowViewDidFinishRestore(AdaptyUIFlowView view, AdaptyProfile profile) {
    view.dismiss();
  }

  // Required: handle rendering and other view errors.
  @override
  void flowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) {
    print('Flow error: $error');
    view.dismiss();
  }
}

class FlowScreen extends StatefulWidget {
  const FlowScreen({super.key});

  @override
  State<FlowScreen> createState() => _FlowScreenState();
}

class _FlowScreenState extends State<FlowScreen> {
  @override
  void initState() {
    super.initState();
    _showFlowIfNeeded();
  }

  Future<void> _showFlowIfNeeded() async {
    try {
      final flow = await Adapty().getFlow(
        placementId: 'YOUR_PLACEMENT_ID',
      );

      if (!flow.hasViewConfiguration) return;

      final view = await AdaptyUI().createFlowView(flow: flow);

      await view.present();
    } catch (_) {
      // Handle any errors (network, SDK issues, etc.)
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Adapty Flow Example')),
      body: Center(
        // Add a button to re-trigger the flow for testing purposes.
        child: ElevatedButton(
          onPressed: _showFlowIfNeeded,
          child: const Text('Show Flow'),
        ),
      ),
    );
  }
}