Adapty Flutter SDK を v. 4.0 へ移行する

Adapty Flutter SDK 4.0 ではフローが導入され、ペイウォール API の名称が変更されました。新しい API は新しい Flow Builder と既存の Paywall Builder の両方に対応しており、Adapty ダッシュボード側の設定変更は不要です。

クイックリファレンス

v3	v4
`Adapty().getPaywall(placementId: id)`	`Adapty().getFlow(placementId: id)`
`Adapty().getPaywallForDefaultAudience(placementId: id)`	`Adapty().getFlowForDefaultAudience(placementId: id)`
`Adapty().getPaywallProducts(paywall: paywall)`	`Adapty().getPaywallProducts(flow: flow)`
`Adapty().logShowPaywall(paywall: paywall)`	`Adapty().logShowFlow(flow: flow)`
`AdaptyPaywall`（型）	`AdaptyFlow`
`AdaptyPaywallFetchPolicy`（型）	`AdaptyFlowFetchPolicy`
`AdaptyUI().createPaywallView(paywall: paywall)`	`AdaptyUI().createFlowView(flow: flow)`
`AdaptyUIPaywallView`（型）	`AdaptyUIFlowView`
`AdaptyUIPaywallPlatformView`（ウィジェット）	`AdaptyUIFlowPlatformView`
`AdaptyUI().presentPaywallView(view)` / `dismissPaywallView(view)`	`AdaptyUI().presentFlowView(view)` / `dismissFlowView(view)`
`AdaptyUIPaywallsEventsObserver`	`AdaptyUIFlowsEventsObserver`
`AdaptyUI().setPaywallsEventsObserver(observer)`	`AdaptyUI().setFlowsEventsObserver(observer)`
`paywallViewDid*` コールバック	`flowViewDid*` コールバック
`paywallViewDidFailRendering`	`flowViewDidReceiveError`
`AdaptyPaywallProduct` はそのまま名前が変わりません。プロダクトは引き続きフローに属しており、`getPaywallProducts` は `AdaptyFlow` を受け取るようになりました。フローを取得する際に `locale` を渡す必要はなくなりました。購入とプロファイル関連のAPI（`makePurchase`、`restorePurchases`、`getProfile`、`identify` など）は変更なし、ビューメソッド（`present`、`dismiss`、`showDialog`）も変わりません。一部のデフォルト動作が変更されています。詳しくはデフォルト動作の変更をご覧ください。

最小バージョン

Adapty Flutter SDK 4.0 では、最小要件が引き上げられました：

iOS 15.0 — iOS の最小デプロイメントターゲット（iOS 13.0 から引き上げ）。
Xcode 26 以降 — ネイティブ iOS SDK は Swift tools 6.2 を使用します。
Flutter 3.32.0（Dart 3.8.0）以降。

インストール

パッケージを更新する

インストールするパッケージは、アプリがキッズモードを使用しているかどうかによって異なります。

ほとんどのアプリでは、pubspec.yaml の adapty_flutter を v4.0 に更新します：

dependencies:
  adapty_flutter: 4.0.0

アプリがキッズモードを使用している場合は、代わりに adapty_flutter_kids を指定します：

dependencies:
  adapty_flutter_kids: 4.0.0

これはスタンドアロンパッケージで、IDFAおよび広告トラッキングコードを削除してApp Storeの要件に準拠します。Dartのインポートパスをpackage:adapty_flutter_kids/adapty_flutter.dartに更新してください。それ以外の移行手順は通常パッケージとまったく同じです。

キッズモードでは、Adapty ダッシュボードでIPアドレス収集を無効にする必要があります。詳細なセットアップ手順はキッズモードを参照してください。

iOS：ネイティブSDKはSwift Package Manager経由で配布されるようになりました

CocoaPodsのスペックリポジトリは2026年12月に読み取り専用になります。そのため、v4からはネイティブiOS SDKのCocoaPodsによる配布が終了し、プラグインはSwift Package Managerのみを通じて配布されます。

Flutter 3.32〜3.43をお使いの場合は、Swift Package Managerのサポートを一度有効化してください：

flutter config --enable-swift-package-manager

Flutter 3.44以降ではSwift Package Managerがデフォルトで有効になっているため、特別な操作は不要です。

フローの取得

getPaywall → getFlow

返り値の型が AdaptyPaywall から AdaptyFlow に変わり、locale を渡す必要がなくなりました — フローをレンダリングする際にローカライズは自動的に解決され、カスタムペイウォールの場合はすべての設定済みロケールが flow.remoteConfigs に返されます。

- final paywall = await Adapty().getPaywall(placementId: 'YOUR_PLACEMENT_ID', locale: 'en');
+ final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');

getPaywallForDefaultAudience も同様にリネームされています。

- final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID', locale: 'en');
+ final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');

フェッチポリシーの型名が AdaptyPaywallFetchPolicy から AdaptyFlowFetchPolicy に変更されました。オプション（reloadRevalidatingCacheData、returnCacheDataElseLoad、returnCacheDataIfNotExpiredElseLoad）は変更ありません。

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts は名前はそのままですが、flow パラメーターで AdaptyFlow を受け取るようになりました：

- final products = await Adapty().getPaywallProducts(paywall: paywall);
+ final products = await Adapty().getPaywallProducts(flow: flow);

データモデル

getFlow は AdaptyPaywall の代わりに AdaptyFlow を返し、オブジェクトの構造が変わりました。

v3 `AdaptyPaywall` メンバー	v4 `AdaptyFlow` メンバー	アクション
`remoteConfig`（単一、nullable）	`remoteConfigs`（リスト）	フローは設定された言語ごとに1つのリモートコンフィグを持ちます。`remoteConfig` ゲッターは引き続き存在し、最初のエントリを返します。特定の言語を選択するには、`remoteConfigs` を `locale` で検索してください。
`productIdentifiers`	`productIdentifiers`	維持されていますが、フローのすべてのペイウォールバリエーションを横断して収集されるようになりました。バリエーションごとの識別子は `flow.paywalls[i].productIdentifiers` に格納されています。
`hasViewConfiguration`	`hasViewConfiguration`	変更なし。
`placementId`（非推奨）	削除済み	`flow.placement.id` を使用してください。
`revision`（非推奨）	削除済み	`flow.placement.revision` を使用してください。
`vendorProductIds`（非推奨）	削除済み	`productIdentifiers` を使用してください。
(新規)	`paywalls`（`AdaptyFlowPaywall` のリスト）	各エントリはフロー内の1つのペイウォールバリエーションで、独自の `name`、`variationId`、および `productIdentifiers` を持ちます。
`AdaptyPaywallViewConfiguration` は非公開になりました — ビュー設定は不透明になりました。この型への参照をすべて削除してください。

Webペイウォールメソッド

openWebPaywall と createWebPaywallUrl の名前はそのままですが、paywall パラメータは AdaptyPaywall の代わりに AdaptyFlowPaywall（フローのバリアント）を受け取るようになりました。引き続き AdaptyPaywallProduct を渡すこともできます。

  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
- await Adapty().openWebPaywall(paywall: paywall);
+ if (flow.paywalls.isNotEmpty) {
+   await Adapty().openWebPaywall(paywall: flow.paywalls[0]);
+ }

フローのビュー数を追跡する

logShowPaywall → logShowFlow

logShowPaywall は logShowFlow に名前が変更され、AdaptyFlow を受け取るようになりました。イベントは引き続き同じバリアントに対して記録されるため、既存のファネルおよび A/B テストの指標はダッシュボードの変更なしにそのまま機能します。

- await Adapty().logShowPaywall(paywall: paywall);
+ await Adapty().logShowFlow(flow: flow);

v3 と同様に、フロービルダーまたはペイウォールビルダーでレンダリングされたフローやペイウォールを表示する際には、このメソッドを呼び出す必要はありません。Adapty がそれらのビューを自動的にトラッキングします。

フローの表示

createPaywallView → createFlowView

メソッド名を変更し、AdaptyFlow を flow パラメータで渡します。その他のパラメータ（loadTimeout、preloadProducts、customTags、customTimers、customAssets、productPurchaseParams）や、ビューのメソッド（present、dismiss、showDialog）は変更ありません：

- final view = await AdaptyUI().createPaywallView(paywall: paywall);
+ final view = await AdaptyUI().createFlowView(flow: flow);
  await view.present();

AdaptyUIPaywallView → AdaptyUIFlowView

ビュータイプの名前が変更されました。非推奨の paywallVariationId プロパティは削除されました — 代わりに variationId を使用してください:

- void flowViewDidAppear(AdaptyUIPaywallView view) {
+ void flowViewDidAppear(AdaptyUIFlowView view) {

AdaptyUIPaywallPlatformView → AdaptyUIFlowPlatformView

ウィジェットツリーにビューをウィジェットとして埋め込む場合は、名前を変更して flow パラメータを渡してください。イベントコールバック（onDidAppear、onDidFinishPurchase など）は名前がそのまま引き継がれます：

- AdaptyUIPaywallPlatformView(
-   paywall: paywall,
+ AdaptyUIFlowPlatformView(
+   flow: flow,
    onDidFinishPurchase: (view, product, purchaseResult) { /* … */ },
  )

createFlowView で作成したフロービューは使い捨てです。dismiss() を呼び出すと、ビューはメモリから解放され、再表示できなくなります。フローをもう一度表示するには、再度 createFlowView を呼び出してください。

イベントの処理

オブザーバークラスは AdaptyUIPaywallsEventsObserver から AdaptyUIFlowsEventsObserver へ、登録メソッドは setPaywallsEventsObserver から setFlowsEventsObserver へ、そしてすべての paywallViewDid* コールバックは flowViewDid* へとそれぞれリネームされました。

- class MyObserver extends AdaptyUIPaywallsEventsObserver {
+ class MyObserver extends AdaptyUIFlowsEventsObserver {
    @override
-   void paywallViewDidPerformAction(AdaptyUIPaywallView view, AdaptyUIAction action) {
+   void flowViewDidPerformAction(AdaptyUIFlowView view, AdaptyUIAction action) {
      // …
    }
  }

- AdaptyUI().setPaywallsEventsObserver(this);
+ AdaptyUI().setFlowsEventsObserver(this);

次の3つのコールバックは必須です — これらがないとオブザーバーはコンパイルエラーになります：

flowViewDidFinishPurchase: v3 ではオプションで、デフォルトでは購入後にビューが閉じられていました。現在は、フローを続けるか view.dismiss() を呼び出すかを自分で決定します。
flowViewDidFinishRestore: v3 と同様に必須です。
flowViewDidReceiveError: paywallViewDidFailRendering を置き換え、その他のビューエラーも受け取るようになりました。

その他の小さな変更点が 2 つあります：

setFlowsEventsObserver（および setOnboardingsEventsObserver）が null を受け付けるようになり、設定済みのオブザーバーを取り外せるようになりました。これにより、SDK がオブザーバーを保持し続けることがなくなります。
新しいオプションの flowViewDidReceiveAnalyticEvent コールバックは、フローからのカスタム分析イベント用に予約されています。現時点ではフローからこのコールバックがコードに送出されることはないため、実装する必要はありません。

v4 ではオプトインで利用できる新機能も追加されています。

AdaptyUI().setObserverModeResolver(...) と AdaptyUIObserverModeResolver — SDKがオブザーバーモードで動作中に、フローから開始された購入やリストアを処理します。以前はネイティブのiOSおよびAndroid SDKでのみ利用可能でした。オブザーバーモードでフローを表示するを参照してください。
AdaptyUI().setSystemRequestsHandler(...) と AdaptyUISystemRequestsHandler — フローからのシステムリクエスト（OSの権限プロンプトやApp Storeのレビューリクエスト）用に予約されています。フローはまだこれらのリクエストをトリガーしないため、ハンドラーを登録する必要はありません。

削除された API

これらのシンボルは 3.x で非推奨となり、v4 では削除されています：

setFallbackPaywalls → setFallback

- await Adapty().setFallbackPaywalls(assetId);
+ await Adapty().setFallback(assetId);

withIdfaCollectionDisabled → withAppleIdfaCollectionDisabled

  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
-   ..withIdfaCollectionDisabled(true),
+   ..withAppleIdfaCollectionDisabled(true),

その他の削除されたメンバー

AdaptyPurchaseResultSuccess.jwsTransaction: appleJwsTransaction を使用してください。
AdaptyUIFlowView.paywallVariationId: variationId を使用してください。
AdaptyUIObserver と AdaptyUI().setObserver(...): AdaptyUIFlowsEventsObserver と setFlowsEventsObserver(...) を使用してください。

デフォルト動作の変更

これらの変更はコンパイルエラーを引き起こしませんが、実行時にテストしてください：

購入成功時: v3 では paywallViewDidFinishPurchase のデフォルト動作でビューが閉じられていましたが、v4 では flowViewDidFinishPurchase が必須となり、デフォルトの動作はありません。ビューを閉じたい場合は自分でその処理を実装してください。
Android システムの戻るボタン: デフォルトではフローを閉じなくなりました。このアクションは AndroidSystemBackAction として flowViewDidPerformAction に渡されるため、戻るボタンでフローを閉じたい場合はそこで処理してください。
URL を開く処理: flowViewDidPerformAction のデフォルト動作が変更され、CloseAction 時のビュー閉鎖に加え、OpenUrlAction をネイティブに処理する（ダッシュボードで設定されたアプリ内ブラウザまたは外部ブラウザの設定に従う）ようになりました。URL を独自に処理したい場合はコールバックをオーバーライドしてください。
ビューのエラー: flowViewDidReceiveError が必須となり、ビューを閉じるかどうかはご自身の実装次第です。v3 でレンダリングエラー時に自動的にビューが閉じられる動作に依存していた場合は、このコールバック内で view.dismiss() を呼び出してください。
ビューのライフサイクル: フローまたはオンボーディングのビューを閉じると、そのビューはメモリから解放されます。一度閉じたビューは再表示できないため、新しいビューを作成してください。

オンボーディング API の廃止

レガシーオンボーディング API は v4.0 で廃止され、Flow Builder に移行されました。引き続き動作しますが、@Deprecated アノテーションにより IDE が廃止シンボルをフラグとして表示します（ランタイム警告は発生しません）。これらのシンボルは将来のリリースで削除される予定ですので、オンボーディングの Flow Builder への移行を計画してください。非推奨のシンボル: getOnboarding、getOnboardingForDefaultAudience、createOnboardingView、presentOnboardingView、dismissOnboardingView、setOnboardingsEventsObserver、AdaptyOnboarding、AdaptyUIOnboardingView、AdaptyUIOnboardingPlatformView、AdaptyUIOnboardingsEventsObserver、およびオンボーディングの状態・入力・アナリティクスモデル。