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

Adapty Kotlin Multiplatform SDK 4.1 は 4.x ラインの最初の安定版リリースです。4.0 はベータとしてのみリリースされたため、3.x をお使いの場合は直接 4.1 に移行してください。このガイドでは、4.0 で導入されたフローと、その上に加えられた 4.1 の変更点を含む移行全体を説明します。

4.x ラインではフローが導入され、それに合わせてペイウォール API が名称変更されました。新しい API は、フロー＆ペイウォールビルダーと旧ペイウォールビルダーの両方に対応しており、Adapty ダッシュボード側での設定変更は不要です。さらに 4.1 では、Adapty Attribution がオプトイン方式になり、外部アトリビューション API とプロダクトのサブスクリプションタイプの名称が変更され、App Store のプロモーションアプリ内課金が追加されました。

Note

4.0 ベータからアップデートする場合は、バージョンを更新した後、以下の5つのセクションのみが該当します: Adapty アトリビューションはデフォルトで無効、外部アトリビューション API のリネーム、AdaptyPaywallProductSubscription → AdaptyProductSubscription、App Store プロモーションアプリ内課金、特定のレイアウトの選択。hasViewConfiguration もフローモデルに戻りました。

クイックリファレンス

v3	v4.1
Adapty アトリビューション自動有効	デフォルト無効 — `.withAdaptyAttributionEnabled(true)` でオプトイン
`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`
`Adapty.updateAttribution(attribution, source)`（`String` 型のソース）	`Adapty.updateExternalAttribution(attribution, provider)`（`AdaptyExternalAttributionProvider` 型）
プロバイダーを文字列で指定（例：`"adjust"`）	`AdaptyExternalAttributionProvider`（例：`AdaptyExternalAttributionProvider.ADJUST`）
`AdaptyProfile.appliedAttributionSources: List<String>`	`AdaptyProfile.appliedExternalAttributionProviders: List<AdaptyExternalAttributionProvider>`
`AdaptyPaywallProductSubscription`	`AdaptyProductSubscription`
プロモートされたアプリ内課金は自動的に完了し、途中で処理を引き取る方法がない	`OnPromotedPurchaseListener` と `Adapty.makePromotedPurchase(product)` により、完了処理をアプリ側で制御可能

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

インストール

バージョンを更新してプロジェクトを同期してください：

[versions]
adapty-kmp = "<the latest SDK version>"

[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 のままで、このリリースでは変更ありません。

⚠️ Adapty アトリビューションはデフォルトで無効になっています

Warning

Adapty アトリビューションを使用していて、オプトインせずに SDK 4.1 にアップデートすると、エラーが表示されないまま機能が停止します。インストールの記録が止まり、何も警告されません。

以前のバージョンでは、SDKはAdapty Attributionのインストールを自動的に登録していました。SDK バージョン 4.1 以降、この機能はデフォルトで無効になっています。SDKはインストールを登録せず、setOnInstallationDetailsListener で設定したリスナーは呼び出されず、getCurrentInstallationStatus は AdaptyInstallationStatus.Determined.NotAvailable を返します。

Adapty Attribution を使用する場合は、SDK のアクティベーション時に有効化してください：

  val config = AdaptyConfig
      .Builder("PUBLIC_SDK_KEY")
+     .withAdaptyAttributionEnabled(true)
      .build()

  Adapty.activate(configuration = config)

Adapty Attribution を使用しない場合は、変更は不要です。

フローの取得

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`	維持	フローにAdaptyUIがレンダリングできるレイアウトが含まれているかどうかを示します。4.0ベータでは存在しませんでしたが、4.1で復活しました。ベータ向けにチェックを削除していた場合、再度使用できます。`false` はフローにレイアウトが含まれていないことを意味するため、リモートコンフィグ専用として扱ってください。`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 がレンダリングするフローやペイウォールを表示する際にこのメソッドを呼び出す必要はありません — Adapty がそれらのビューを自動的に追跡します。

フローの表示

createPaywallView → createFlowView

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

Note

customTimers は引き続き存在しますが、レガシーのペイウォールビルダーのペイウォールにのみ影響します。フローのカウントダウンタイマーはフロー＆ペイウォールビルダーで設定した動作で動作するため、ここで渡した値はフローに無視されます。

- 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
+     }

Note

フロービューは使い捨てです。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 modeで動作中に、フローから開始された購入と復元を処理します。以前はネイティブのiOSおよびAndroid SDKでのみ利用可能でした。フローをObserver modeで表示するを参照してください。
AdaptyUI.setSystemRequestsHandler(...) と AdaptyUISystemRequestsHandler — フローからのシステムリクエスト（OSの権限プロンプトやアプリレビューリクエスト）向けに予約されています。フローはまだこれらのリクエストをトリガーしないため、ハンドラーを登録する必要はありません。
新しいオプションのコールバック flowViewDidReceiveAnalyticEvent は、フローからの分析イベントを報告します。ユーザーが開いた各画面のスクリーンビューから始まります。フローの画面ビューを追跡するを参照してください。
AdaptyUI.openWebUrl(url, openIn) と AdaptyUI.requestAppReview() — デフォルトの OpenUrlAction 処理とデフォルトの handleAppReviewRequest を支援するものです。これにより、URLとアプリレビュープロンプトがすぐにネイティブで処理されます。これらのデフォルト動作をオーバーライドする場合にのみ、直接呼び出してください。
AdaptyUIFlowView.locale — ビューが構築された際のローカライゼーションを報告します。これにより、ユーザーが実際に見ているローカライゼーションを確認できます。
AdaptyConfig.ServerCluster.CN — DEFAULT と EU に加えた新しいサーバークラスターオプションです。アプリをAdaptyのChinaサーバーに接続するために使用します。

外部アトリビューション API の名称変更

SDK バージョン 4.1 以降、外部プロバイダー（Adjust、AppsFlyer、Branch、Tenjin、Apple Ads、またはカスタム）からアトリビューションデータを渡す API の名称がネイティブ SDK に合わせて変更され、プロバイダーの指定が文字列から型に変わりました。非推奨のエイリアスは用意されていないため、既存の呼び出し箇所は更新するまでコンパイルエラーになります。

updateAttribution → updateExternalAttribution

メソッド名が変更され、source パラメーターは provider に改名され、String の代わりに AdaptyExternalAttributionProvider を受け取るようになりました。

- Adapty.updateAttribution(attribution, "adjust")
+ Adapty.updateExternalAttribution(attribution, AdaptyExternalAttributionProvider.ADJUST)

アトリビューションデータは引き続き Map<String, Any> です。

このメソッドは、バックエンドが非同期処理のためにデータを受け付けた時点で処理を返します。成功した結果は、データがすでにプロファイルに適用されたことを意味するわけではありません。

AdaptyExternalAttributionProvider

プロバイダーは現在、APPLE_ADS、ADJUST、APPSFLYER、BRANCH、TENJIN、CUSTOM という定義済みの値を持つ型になっています。それ以外のプロバイダーには、識別子から直接構築してください：

AdaptyExternalAttributionProvider("your_provider")

直接構築することで、このSDKリリース以降に Adapty が追加したプロバイダーにも対応できます。識別子は不明な値に変換されることなく、そのままバックエンドに送信されます。なお、前後の空白は自動的にトリミングされます。

事前定義された各値は、以前 updateAttribution に渡していたのと同じ識別子をラップしています。AdaptyExternalAttributionProvider.APPLE_ADS.value は apple_search_ads であり、残りはそれぞれの小文字の名前になっています。

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

プロファイルに適用されたアトリビューションプロバイダーの一覧を返すプロファイルプロパティが名称変更され、要素の型も変わります：

- if (profile.appliedAttributionSources.contains("apple_search_ads")) {
+ if (profile.appliedExternalAttributionProviders.contains(AdaptyExternalAttributionProvider.APPLE_ADS)) {
      // Apple Ads attribution has been applied
  }

AdaptyPaywallProductSubscription → AdaptyProductSubscription

サブスクリプション詳細の型名が変更されました。プロモーションプロダクトが同じ型を持つようになったためです。名前のみの変更で、すべてのプロパティはそのまま引き継がれます。

- val subscription: AdaptyPaywallProductSubscription? = product.subscription
+ val subscription: AdaptyProductSubscription? = product.subscription

App Storeのプロモートアプリ内課金

SDK 4.1では、App StoreのプロダクトページでプロモートされたアプリURL課金をiOSアプリ内で受け取れるようになりました。以前のバージョンではこのような購入は自動的に完了し、アプリ側で処理を横取りする方法はありませんでした。4.1からは購入がコードの処理を待つ形になったため、プロモート購入を扱っていなかった場合でも対応が必要です。

プロモーション購入をサポートするには、OnPromotedPurchaseListener を登録し、プロダクトを Adapty.makePromotedPurchase に渡して購入を完了します。リスナーが登録されていない場合、購入は完了せず保留状態になります。ユーザーがApp Storeページで Buy をタップしても、アプリ内では何も起こりません。できるだけ早くリスナーを登録してください。タイミングと完全なサンプルコードについては、App Storeからのアプリ内課金を参照してください。

特定のレイアウトを選択する

createFlowView、createNativeFlowView、AdaptyUIFlowPlatformView には、新しいオプションパラメーター customLayoutId が追加されました。これを指定すると、デバイスの種類や画面サイズからSDKが自動的に選択するレイアウトではなく、フローのレイアウト設定内の特定のレイアウトを描画できます。現在、フロー＆ペイウォールビルダーはカスタムレイアウトIDをまだ割り当てていないため、この値は未設定のままにしてください：

AdaptyUI.createFlowView(flow, customLayoutId = "tablet_landscape")

IDに一致するレイアウトがない場合、フローはビュー設定なしで読み込まれます。このパラメータはオプションで、デフォルト値はnullなので、既存の呼び出しには影響しません。

デフォルト動作の変更

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

購入完了時の挙動: 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 で非推奨となりました。現在も動作しますが、将来のリリースで削除される予定です。オンボーディングをフロー & ペイウォールビルダーへ移行する計画を立ててください。

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