Adapty Kotlin Multiplatform SDKをv4.0に移行する

Adapty Kotlin Multiplatform SDK 4.0（ベータ）ではフローが導入され、ペイウォールAPIの名称が変更されました。新しいAPIは新しいFlow BuilderおよびExisting Paywall Builderの両方で動作し、Adapty ダッシュボード側の設定変更は不要です。

クイックリファレンス

v3	v4
`Adapty.getPaywall(placementId, locale)`	`Adapty.getFlow(placementId)`
`Adapty.getPaywallForDefaultAudience(placementId, locale)`	`Adapty.getFlowForDefaultAudience(placementId)`
`Adapty.getPaywallProducts(paywall)`	`Adapty.getPaywallProducts(flow)`
`Adapty.logShowPaywall(paywall)`	`Adapty.logShowFlow(flow)`
`AdaptyPaywall`	`AdaptyFlow`
`AdaptyUI.createPaywallView(paywall, ...)`	`AdaptyUI.createFlowView(flow, ...)`
`AdaptyUI.createNativePaywallView(...)` → `AdaptyNativePaywallView`	`AdaptyUI.createNativeFlowView(...)` → `AdaptyNativeFlowView`
`AdaptyUIPaywallView`	`AdaptyUIFlowView`
`AdaptyUI.presentPaywallView(view)` / `dismissPaywallView(view)`	`AdaptyUI.presentFlowView(view)` / `dismissFlowView(view)`
`AdaptyUI.setPaywallsEventsObserver(observer)`	`AdaptyUI.setFlowsEventsObserver(observer)`
`AdaptyUI.registerPaywallEventsListener` / `unregisterPaywallEventsListener`	`AdaptyUI.registerFlowEventsListener` / `unregisterFlowEventsListener`
`AdaptyUIPaywallsEventsObserver`	`AdaptyUIFlowsEventsObserver`
`AdaptyUIPaywallPlatformView(paywall, ...)`	`AdaptyUIFlowPlatformView(flow, ...)`
`paywallViewDidPerformAction`、`paywallViewDidAppear`、その他の `paywallView...` コールバック	`flowViewDidPerformAction`、`flowViewDidAppear`、その他の `flowView...` コールバック
`paywallViewDidFailRendering`	`flowViewDidReceiveError`

AdaptyPaywallProduct は名前を維持します — プロダクトは引き続きフローに属し、getPaywallProducts も名前を維持したまま AdaptyFlow を受け取るようになります。getFlow と getFlowForDefaultAudience メソッドは locale パラメーターを受け取らなくなりました — 代わりに createFlowView に渡してください。購入およびプロファイルの API（makePurchase、restorePurchases、getProfile、identify、updateProfile）と setFallback はシグネチャを維持しますが、フォールバックファイル自体は再ダウンロードが必要です — フォールバックファイルを参照してください。オンボーディングのメソッドは引き続き動作しますが非推奨となっています — オンボーディング API の非推奨を参照してください。一部のデフォルト動作が変更されました — デフォルト動作の変更を参照してください。

インストール

v4.0 はプレリリース版のため、正確なバージョンを固定してください。Gradle は動的レンジではプレリリースバージョンを選択しません：

[versions]
adapty-kmp = "4.0.1-beta.1"

[libraries]
adapty-kmp = { module = "io.adapty:adapty-kmp", version.ref = "adapty-kmp" }
adapty-kmp-ui = { module = "io.adapty:adapty-kmp-ui", version.ref = "adapty-kmp" }

adapty-kmp-ui モジュールが必要なのは、Compose Multiplatform レイヤー（view.present()）でフローやペイウォールをレンダリングする場合のみです。完全なセットアップ手順については、Adapty SDK のインストールをご覧ください。

両プラットフォームのネイティブ Adapty SDK は 4.x リリースにバンプされており、自動的に解決されるため、ビルドの変更は不要です。iOS のデプロイメントターゲットは 15.0 のままで、このリリースによる変更はありません。

フローの取得

getPaywall → getFlow

戻り値の型が AdaptyPaywall から AdaptyFlow に変わり、locale パラメーターはフェッチ呼び出しから createFlowView に移動します。カスタムペイウォールの場合、すべてのロケールは flow.remoteConfigs で返されます。

- Adapty.getPaywall("YOUR_PLACEMENT_ID", locale = "en")
-     .onSuccess { paywall ->
-         // use the paywall
+ Adapty.getFlow("YOUR_PLACEMENT_ID")
+     .onSuccess { flow ->
+         AdaptyUI.createFlowView(flow = flow, locale = "en")
      }
      .onError { error ->
          // handle the error
      }

locale は createFlowView でも省略可能です。省略した場合、ビューは en でレンダリングされるか、フローに en がない場合はフローのデフォルトローカライゼーションで表示されます。詳しくはローカライゼーションとロケールコードを参照してください。

getPaywallForDefaultAudience も同様にリネームされます：

- Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID", locale = "en")
+ Adapty.getFlowForDefaultAudience("YOUR_PLACEMENT_ID")

getPaywallProducts(paywall) → getPaywallProducts(flow)

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

- Adapty.getPaywallProducts(paywall)
+ Adapty.getPaywallProducts(flow)
      .onSuccess { products ->
          // use the products
      }

フォールバックファイル

フォールバックファイルのフォーマットは SDK v4 で変更されました。Placements > Fallbacks から新しいファイルをダウンロードし、アプリにバンドルしてください。

データモデル

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

v3 `AdaptyPaywall` プロパティ	v4 `AdaptyFlow` プロパティ	対応内容
`remoteConfig: AdaptyRemoteConfig?` (単一)	`remoteConfigs: List<AdaptyRemoteConfig>`	フローは設定された言語ごとに1つのリモートコンフィグを持ちます。ユーザーに合ったものを取得するには: `flow.remoteConfigs.firstOrNull { it.locale == "en" }`
(新規)	`paywalls: List<AdaptyFlowPaywall>`	各エントリはフロー内の1つのペイウォールバリエーションで、`name`、`variationId`、`productIdentifiers` を持ちます。WebペイウォールのメソッドはAdaptyFlowPaywallを引数に受け取ります — Webペイウォールメソッドを参照してください。
`productIdentifiers`	移動	プロダクト識別子は各バリエーションに移動しました: `flow.paywalls[i].productIdentifiers`。プロダクトの取得には引き続き `getPaywallProducts(flow)` を使用してください。
`hasViewConfiguration`	削除	コードから`hasViewConfiguration`のチェックをすべて削除してください — 代わりに`createFlowView`がエラーを返します（フローの表示を参照）。

hasViewConfiguration は AdaptyOnboarding に残ります — フローモデルのみが削除されます。

Webペイウォールメソッド

openWebPaywall と createWebPaywallUrl の名前はそのままですが、paywall パラメータが AdaptyFlowPaywall を受け取る flowPaywall パラメータに置き換わりました。AdaptyFlowPaywall は flow.paywalls のバリアントの1つです。引き続き AdaptyPaywallProduct を渡すこともできます:

- Adapty.openWebPaywall(paywall = paywall)
+ flow.paywalls.firstOrNull()?.let { flowPaywall ->
+     Adapty.openWebPaywall(flowPaywall = flowPaywall)
+ }

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

logShowPaywall → logShowFlow

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

- Adapty.logShowPaywall(paywall)
+ Adapty.logShowFlow(flow)

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

フローの表示

createPaywallView → createFlowView

ファクトリーメソッドの名前を変更し、AdaptyFlow を渡してください。返されるビューの型名は AdaptyUIPaywallView から AdaptyUIFlowView に変わりましたが、メソッド（present、dismiss）とオプションパラメーター（loadTimeout、preloadProducts、customTags、customTimers、customAssets、productPurchaseParams）は変更ありません。新しいオプションパラメーターとして locale が追加されました。これは以前 getPaywall に渡していた locale の代替です。詳しくはフローの取得を参照してください。

- AdaptyUI.createPaywallView(paywall)
+ AdaptyUI.createFlowView(flow)
      .onSuccess { view ->
          view.present()
      }
      .onError { error ->
          // handle the error
      }

Compose Multiplatform を使用しない場合、ネイティブのファクトリメソッドも同様にリネームされます：

- AdaptyUI.createNativePaywallView(paywall)
+ AdaptyUI.createNativeFlowView(flow)

createFlowView は、フローにビューが設定されていない場合に AdaptyResult.Error を返します。これは v3 の hasViewConfiguration チェックに置き換わるものです：

- if (paywall.hasViewConfiguration) {
-     AdaptyUI.createPaywallView(paywall)
-         .onSuccess { view -> view.present() }
- }
+ AdaptyUI.createFlowView(flow)
+     .onSuccess { view -> view.present() }
+     .onError { error ->
+         // the flow has no view configured, or view creation failed
+     }

フロービューは使い捨てです。dismiss() を呼び出すとビューが破棄されるため、フローを再表示するには createFlowView を再度呼び出してください。

イベントの処理

イベントオブザーバーは AdaptyUIPaywallsEventsObserver から AdaptyUIFlowsEventsObserver に名前が変わり、コールバックの paywallView プレフィックスが flowView に変わります。既存のハンドラー本体のコード変更は不要です。型名とオーバーライドを変更するだけです。

- AdaptyUI.setPaywallsEventsObserver(object : AdaptyUIPaywallsEventsObserver {
-     override fun paywallViewDidFinishPurchase(
-         view: AdaptyUIPaywallView,
+ AdaptyUI.setFlowsEventsObserver(object : AdaptyUIFlowsEventsObserver {
+     override fun flowViewDidFinishPurchase(
+         view: AdaptyUIFlowView,
          product: AdaptyPaywallProduct,
          purchaseResult: AdaptyPurchaseResult
      ) {
          // custom logic after purchase
      }
  })

コールバックも1つ名前が変更されています。paywallViewDidFailRendering が flowViewDidReceiveError になりました。以前と同じレンダリングエラーに加え、購入以外のランタイムエラーでも発火します。

- override fun paywallViewDidFailRendering(view: AdaptyUIPaywallView, error: AdaptyError) {}
+ override fun flowViewDidReceiveError(view: AdaptyUIFlowView, error: AdaptyError) {}

コールバックの全一覧については、フロー & ペイウォールイベントの処理を参照してください。

Compose プラットフォームビュー

Compose Multiplatform のコンポーザブルを使用してビューを埋め込む場合、AdaptyUIPaywallPlatformView(paywall, ...) は AdaptyUIFlowPlatformView(flow, ...) に名称変更されます。イベントコールバックの onDid... という名前はそのまま維持されますが、onDidFailRendering のみ onDidReceiveError に変更されます。

- AdaptyUIPaywallPlatformView(
-     paywall = paywall,
+ AdaptyUIFlowPlatformView(
+     flow = flow,
      onDidFinishPurchase = { view, product, result -> /* ... */ },
  )

v3と同様に、ここで渡すコールバック（およびregisterFlowEventsListenerで登録したオブザーバー）は、グローバルオブザーバーの代わりにではなく、追加として実行されます。つまり、コールバックはイベントを監視するのみであり、グローバルのデフォルト動作を置き換えるものではありません。変更されたデフォルト動作に注意してください。たとえば、グローバルのデフォルトでは購入後にビューが閉じられなくなっています。

新しいAPI

AdaptyUI.setObserverModeResolver(...) と AdaptyUIObserverModeResolver — SDKがObserverモードで動作している間、フローから開始された購入と復元を処理します。以前はネイティブのiOSおよびAndroid SDKでのみ利用可能でした。詳細はObserverモードでのFlowの表示を参照してください。
AdaptyUI.setSystemRequestsHandler(...) と AdaptyUISystemRequestsHandler — フローからのシステムリクエスト（OS権限プロンプトやアプリレビューリクエスト）のために予約されています。フローはまだこれらのリクエストをトリガーしないため、ハンドラーを登録する必要はありません。
新しいオプションの flowViewDidReceiveAnalyticEvent コールバックは、フローからのカスタム分析イベント用に予約されています。フローはまだこれらをコードに送出しないため、実装する必要はありません。
AdaptyUI.openWebUrl(url, openIn) と AdaptyUI.requestAppReview() — デフォルトの OpenUrlAction 処理とデフォルトの handleAppReviewRequest を支援するため、URLとアプリレビュープロンプトはネイティブで自動的に処理されます。これらのデフォルトをオーバーライドする場合にのみ、直接呼び出してください。
AdaptyUIFlowView.locale — ビューが構築されたローカライズを報告するため、ユーザーが実際に表示しているものを確認できます。SDK 4.0.1-beta.1以降が必要です。
AdaptyConfig.ServerCluster.CN — DEFAULT および EU と並ぶ新しいサーバークラスターオプションで、アプリをAdaptyの中国サーバーに接続します。

デフォルト動作の変更

これらの変更はコンパイルエラーを引き起こさないため、ランタイムでテストしてください。

購入完了時の挙動: v3 では、デフォルトの paywallViewDidFinishPurchase が AdaptyPurchaseResult.UserCanceled 以外の購入結果に対してビューを閉じていました。v4 では、デフォルトの flowViewDidFinishPurchase は何もしないため、購入が完了してもフローは明示的に閉じるまで開いたままになります — iOS の挙動に合わせた変更です。自動的に閉じる動作に依存していた場合は、購入完了後に自分で view.dismiss() を呼び出してください。
Android のシステムバック: v3 では、デフォルトの paywallViewDidPerformAction が CloseAction と AndroidSystemBackAction の両方でビューを閉じていました。v4 では、デフォルトは CloseAction のみを処理します — システムバックボタンでは単独でフローが閉じなくなりました。これは、システムジェスチャーでフローを閉じられない iOS の挙動に合わせたものです。ユーザーが明示的に閉じられるよう（Close ボタンや on_device_back アクションなど）対応するか、flowViewDidPerformAction 内で自分でビューを閉じてください。
ビューのエラー: v3 では、デフォルトの paywallViewDidFailRendering は何もしませんでした。v4 では、デフォルトの flowViewDidReceiveError がビューを閉じます — ビューを開いたままにしたい場合やエラーを独自に処理したい場合はオーバーライドしてください。
ビューは使い捨て: dismiss() を呼び出すとビューは破棄されます。フローを再度表示するには、createFlowView をもう一度呼び出してください。

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

レガシーのオンボーディング API は、フロービルダーへの移行に伴い v4.0 で非推奨となりました。現時点では引き続き動作しますが、将来のリリースで削除される予定です。オンボーディングをフロービルダーへ移行する計画を立ててください。

非推奨のシンボル: getOnboarding、getOnboardingForDefaultAudience、AdaptyUI.createOnboardingView、AdaptyUI.createNativeOnboardingView、AdaptyUIOnboardingsEventsObserver。