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

4.x ラインではフローが導入され、ペイウォール API が対応する名前に変更されます。新しい API はフローと連携し、旧ビルダーのペイウォールも引き続き動作します。Adapty ダッシュボード側での設定変更は不要です。また、4.1.1 ではAdapty アトリビューションがオプトイン形式になり、外部アトリビューションメソッドの名称変更、フォールバックファイル形式の変更、App Store プロモーションアプリ内課金のサポートが追加されます。

クイックリファレンス

v3	v4.1.1
Adapty アトリビューション 自動有効化	デフォルトで無効 — adaptyAttributionEnabled: true でオプトイン
adapty.getPaywall({ placementId, locale?, params? })	adapty.getFlow({ placementId, params? })
adapty.getPaywallForDefaultAudience({ placementId, locale?, params? })	adapty.getFlowForDefaultAudience({ placementId, params? })
adapty.getPaywallProducts({ paywall })	adapty.getPaywallProducts({ flow })
adapty.logShowPaywall({ paywall })	adapty.logShowFlow({ flow })
AdaptyPaywall（型）	AdaptyFlow + AdaptyFlowPaywall
createPaywallView(paywall, params?)	createFlowView(flow, params?)
PaywallViewController	FlowViewController
EventHandlers（型）	FlowEventHandlers
CreatePaywallViewParamsInput	CreateFlowViewParamsInput
onRenderingFailed	onError
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders
AttributionSource	AdaptyExternalAttributionProvider
3.x 向けフォールバックファイルをダウンロード済み	新しいフォールバックファイル形式 — ファイルを再ダウンロードしてください
プロモーションアプリ内課金は自動完了し、途中で処理を差し込む手段なし	'onPromotedPurchaseReceived' イベントと adapty.makePromotedPurchase({ product }) でアプリ側が完了を制御できる

AdaptyPaywallProduct はその名称を維持します。プロダクトは引き続きフローに属しており、getPaywallProducts もその名称を維持しますが、AdaptyFlow を受け取るようになりました。getFlow および getFlowForDefaultAudience メソッドは locale パラメーターを受け取らなくなりました。代わりに createFlowView に渡してください。購入・プロファイル API（makePurchase、restorePurchases、getProfile、identify、updateProfile）および setFallback はシグネチャが変わりませんが、フォールバックファイル自体は再ダウンロードが必要です。詳しくはフォールバックファイルを参照してください。ビューメソッド present、dismiss、setEventHandlers、clearEventHandlers、showDialog、およびイベントハンドラー onCloseButtonPress、onUrlPress、onCustomAction、onProductSelected、onPurchaseStarted、onPurchaseCompleted、onPurchaseFailed、onRestoreStarted、onRestoreCompleted、onRestoreFailed、onLoadingProductsFailed、onWebPaymentNavigationFinished、onAndroidSystemBack はすべて v3 と同じ名称を維持します。オンボーディングメソッドは引き続き動作しますが、非推奨となっています。詳しくはオンボーディング API の非推奨を参照してください。一部のデフォルト動作が変更されています。詳しくはデフォルト動作の変更を参照してください。

最小バージョン

実行時の要件はv3.16+から変更なし：iOS 15.0、Android minSdk 24、Capacitor 8。デプロイターゲットの変更は不要です。

新たなビルド要件が1つ追加されました：Xcode 26以降 — このリリースにバンドルされているネイティブのAdapty iOS SDKはSwift tools 6.2を使用しています。

インストール

パッケージの更新

npm install @adapty/capacitor@latest

ネイティブプロジェクトを同期します：

npx cap sync

iOS: Swift Package Manager のみ

CocoaPods の spec リポジトリは 2026 年 12 月に読み取り専用になります。そのため、v4 以降は AdaptyCapacitor.podspec が削除され、iOS への SDK インストールは Swift Package Manager (SPM) のみ対応となります。アプリの iOS プロジェクトで Capacitor の SPM 連携を使用する必要があります。

• 新規アプリの場合: SPM パッケージマネージャーを指定して iOS プラットフォームを追加します。

npx cap add ios --packagemanager SPM

• CocoaPods を使用している既存アプリの場合: 既存プロジェクトで SPM を使用するための Capacitor ガイドに従って iOS プロジェクトを移行してください。

完全なセットアップ手順については、SDK のインストールをご覧ください。

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

以前のバージョンでは、SDKはインストールを Adapty Attribution に自動的に登録していました。SDK バージョン 4.1.1 以降、この機能はデフォルトで無効になっています。SDKはインストールを登録せず、'onInstallationDetailsSuccess' および 'onInstallationDetailsFail' イベントは発火せず、getCurrentInstallationStatus は not_available ステータスを返します。

Adapty Attribution を使用する場合は、SDK を有効化する際にこの機能を有効にしてください：

  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
+     adaptyAttributionEnabled: true,
    },
  });

Adapty アトリビューションを使用していない場合は、変更は不要です。

フローの取得

getPaywall → getFlow

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

- const paywall = await adapty.getPaywall({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlow({ placementId: 'YOUR_PLACEMENT_ID' });
+ const view = await createFlowView(flow, { locale: 'en' });

locale は createFlowView でオプションのままです。省略した場合、ビューは en でレンダリングされるか、フローに en のローカライゼーションがない場合はフローのデフォルトのローカライゼーションでレンダリングされます。このフォールバックのため、ビューが指定したローカライゼーションとは異なるローカライゼーションでレンダリングされる場合があります。新しい FlowViewController.locale プロパティで実際に使用されたローカライゼーションを確認できます。詳しくはローカライゼーションとロケールコードをご覧ください。

getPaywallForDefaultAudience も同様の方法で名前が変更されています:

- const paywall = await adapty.getPaywallForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlowForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID' });

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts は名前を維持しますが、AdaptyFlow を受け取るようになります：

- const products = await adapty.getPaywallProducts({ paywall });
+ const products = await adapty.getPaywallProducts({ flow });

フォールバックファイル

フォールバックファイルのフォーマットは4.0で変更され、さらに4.1.1でも変更されました。4.0ベータ版向けにすでにダウンロードした場合でも、Placements > Fallbacks から再度ダウンロードし、アプリにバンドルしてください。

データモデル

getFlow は AdaptyPaywall の代わりに AdaptyFlow を返し、オブジェクトの形状が変更されました。

v3 AdaptyPaywall フィールド	v4 AdaptyFlow フィールド	操作
remoteConfig? (単一)	remoteConfigs?: AdaptyRemoteConfig[] (配列)	フローは設定された言語ごとに1つのリモートコンフィグを持ちます。ユーザーに合ったものを取得するには: flow.remoteConfigs?.find((c) => c.lang === 'en')。
productIdentifiers	flow.paywalls[i].productIdentifiers	プロダクト識別子は、フローではなく各フローバリアントに移動しました。
products (v3では非推奨)	削除	flow.paywalls[i].productIdentifiers を使用するか、完全なプロダクト情報が必要な場合は getPaywallProducts(flow) を呼び出してください。ProductReference はパブリック型から削除されました。
webPurchaseUrl?	flow.paywalls[i].webPurchaseUrl	フローから各ペイウォールバリアントへ移動しました。
version?: number	flowVersionId?: string	名前が変更され、型も number から string に変わりました。
requestLocale	削除	ロケールはモデルに含まれなくなりました。
(新規)	paywalls: AdaptyFlowPaywall[]	各エントリはフロー内の1つのペイウォールバリアントです。
(新規)	responseCreatedAt: number	サーバーレスポンスのタイムスタンプ（ミリ秒単位）。

requestLocaleはAdaptyOnboardingに残ります — フローモデルからのみ削除されました。

プロダクト識別子がフローから各バリアントに移動しました：

- const ids = paywall.productIdentifiers;
+ const ids = flow.paywalls[0].productIdentifiers;

コードがまだpaywall.productsを読み取っている場合 — v3で非推奨となり、現在は削除済み — productIdentifiersに切り替えるか、識別子ではなく完全なプロダクトが必要な場合はgetPaywallProducts(flow)を呼び出してください。

Web ペイウォールのメソッド

openWebPaywall と createWebPaywallUrl は名前が変わらず、paywallOrProduct オプションに渡す型が AdaptyPaywall から AdaptyFlowPaywall（フローのバリアント）になります。AdaptyPaywallProduct は引き続き渡せます。最初のエントリを読み取る前に flow.paywalls が空でないことを確認してください。

  const flow = await adapty.getFlow({ placementId: 'YOUR_PLACEMENT_ID' });
- await adapty.openWebPaywall({ paywallOrProduct: paywall });
+ await adapty.openWebPaywall({ paywallOrProduct: flow.paywalls[0] });

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

logShowPaywall → logShowFlow

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

- await adapty.logShowPaywall({ paywall });
+ await adapty.logShowFlow({ flow });

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

フローの表示

createPaywallView → createFlowView

ファクトリー関数の名前を変更し、AdaptyFlow を渡します。返されるコントローラーは PaywallViewController から FlowViewController に名前が変わりますが、そのメソッド（present、dismiss、setEventHandlers、clearEventHandlers、showDialog）は変わりません。パラメーターの型は CreatePaywallViewParamsInput から CreateFlowViewParamsInput に名前が変わります：

- import { createPaywallView } from '@adapty/capacitor';
+ import { createFlowView } from '@adapty/capacitor';

- const view = await createPaywallView(paywall);
+ const view = await createFlowView(flow);
  await view.present();

新しいパラメータ

CreateFlowViewParamsInput は v3 のすべてのパラメータ（prefetchProducts、loadTimeoutMs、customTags、customTimers、customAssets、productPurchaseParams）を引き継ぎ、さらに3つを追加します。

パラメーター	説明
locale	フローのレンダリングに使用するローカライズ。getPaywall から移動しました — getPaywall → getFlow を参照してください。
customLayoutId	フローのレイアウト設定におけるレイアウトのカスタム ID。デバイスの種類や画面サイズから SDK が自動的に選択するレイアウトではなく、指定したレイアウトをレンダリングするために渡します。ID に一致するレイアウトがない場合、no-view-configuration エラーで呼び出しが失敗します。Flow & Paywall Builder はまだカスタムレイアウト ID を割り当てていないため、未設定のままにしてください。
android.enableSafeArea	実行時に Android のセーフエリアパディングを制御します。android キーの下にネストされており、デフォルトは true です。

const view = await createFlowView(flow, {
  locale: 'en',
  customLayoutId: 'tablet_landscape',
  android: { enableSafeArea: true },
});

イベントの処理

イベントハンドラーのインターフェース名が EventHandlers から FlowEventHandlers に変更され、コールバックが1つ改名されました。既存のハンドラー本体はコードの変更不要です。名前だけ変えてください：

- onRenderingFailed: (error) => { /* … */ },
+ onError: (error) => { /* … */ },

他のイベントハンドラーは名前が変わりません。ただし、onAppeared のシグネチャが変更されました。() から (view) になり、view は FlowEventView 型で、表示されたビューに関する情報（使用されたローカライズを含む）を提供します。既存のハンドラーは新しい引数を無視するため、そのまま動作します。完全なリストは フロー＆ペイウォールイベントの処理 を参照してください。

v4 では、オプトインで利用できる新機能もいくつか追加されました：

• adapty.openWebUrl({ url, openIn }) および adapty.requestAppReview() メソッド — これらはデフォルトの onUrlPress および onRequestAppReview ハンドラーのバックエンドとして機能するため、URL やアプリレビューのプロンプトはすぐにネイティブで処理されます。これらのハンドラーをオーバーライドする場合のみ、直接呼び出してください。
• フロー内でのオブザーバーモードの購入処理は、新しい onObserverPurchaseInitiated / onObserverRestoreInitiated ハンドラーを使用します。詳細は オブザーバーモードでのフローの表示 を参照してください。
• onAnalytics: (name, params) — フローが発行するアナリティクスイベントで、ユーザーが開いた各画面のスクリーンビューから始まります。詳細は フローの画面ビューをトラッキングする を参照してください。
• onRequestPermission: (permission, customArgs) — フローからのシステム権限リクエスト（プッシュ通知やカメラアクセスなど）のために予約されています。フローはまだ権限リクエストをトリガーしないため、実装する必要はありません。

Separately, 4.1.1 ではフローハンドラーではなく SDK レベルのイベントとして 'onPromotedPurchaseReceived' が追加されています。このイベントは adapty.addListener を通じて配信されます。リスナーが登録されていない場合、SDK が自動でプロモーション購入を完了させます。リスナーを登録すると、完了処理がアプリに委ねられます。詳しくは App Store のプロモーションアプリ内課金 をご覧ください。

外部アトリビューション API のリネーム

SDK バージョン 4.1.1 から、外部プロバイダー（Adjust、AppsFlyer、Branch、Tenjin、またはカスタム）からアトリビューションデータを渡す API がネイティブ SDK に合わせてリネームされました。廃止済みエイリアスは存在しないため、リネームを行うまで既存の呼び出し箇所は動作しなくなります。

4.1.1以前	4.1.1
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AttributionSource	AdaptyExternalAttributionProvider
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders

updateAttribution → updateExternalAttribution

メソッド名が変更され、source オプションは provider に変更されました。アトリビューションデータは引き続きプレーンオブジェクトです:

- await adapty.updateAttribution({ attribution, source: 'adjust' });
+ await adapty.updateExternalAttribution({ attribution, provider: 'adjust' });

AttributionSource → AdaptyExternalAttributionProvider

プロバイダーの型名が変更されました。引き続きオープンユニオンとして機能し、定義済みの値は 'apple_search_ads'、'adjust'、'appsflyer'、'branch'、'tenjin' です。それ以外の文字列も受け付けるため、Adapty が後から追加したプロバイダーも SDK のアップデートなしに利用できます。

- import type { AttributionSource } from '@adapty/capacitor';
+ import type { AdaptyExternalAttributionProvider } from '@adapty/capacitor';

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

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

- if (profile.appliedAttributionSources?.includes('apple_search_ads')) {
+ if (profile.appliedExternalAttributionProviders?.includes('apple_search_ads')) {
      // Apple Ads attribution has been applied
  }

このプロパティを読み取るコードは更新が必要です — Apple Ads ターゲットペイウォールの表示をご覧ください。

App Store のプロモーション アプリ内課金

4.1.1 より前は、App Store のプロダクトページでプロモーションされたアプリ内課金は自動的に完了し、Adapty がトランザクションを記録していましたが、アプリ側でそれを横断する方法はありませんでした。4.1.1 ではそのフックが追加されたため、これは移行手順ではなく新機能です。独自のコードがなくても、SDK は引き続きプロモーション購入を自動的に完了させます。

プロモーション購入を自分で完了させるコードのみを記述してください（例：最初に画面を表示する場合など）。新しい 'onPromotedPurchaseReceived' イベントのリスナーを登録し、adapty.makePromotedPurchase で購入を完了させます。このリスナーが登録されている間、SDK はプロモーション購入を自動的に完了しなくなります。

デフォルト動作の変更

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

• onAndroidSystemBack: デフォルトの動作が、ビューを閉じる動作から開いたままにする動作に変更されました。以前の動作に戻すには、ハンドラーから true を返してください。
• onPurchaseCompleted: デフォルトの動作が、ビューを閉じる動作（ユーザーが購入をキャンセルした場合を除く）から、常に開いたままにする動作に変更されました。以前の動作に戻すには、ハンドラーから purchaseResult.type !== 'user_cancelled' を返してください。
• onRestoreCompleted: デフォルトの動作が、復元成功後にビューを閉じる動作から開いたままにする動作に変更されました。以前の動作に戻すには、ハンドラーから true を返してください。
• onUrlPress: デフォルトでネイティブレイヤーを通じてURLを開くようになり、ダッシュボードのアプリ内ブラウザまたは外部ブラウザの設定が反映されます。URLを独自に開く場合は、ハンドラーをオーバーライドしてください。
• ビューは使い捨て: dismiss() を呼び出すと、ビューは破棄されます。フローを再度表示するには、createFlowView を再度呼び出してください。

削除された API

削除されたエクスポート

以下のシンボルは @adapty/capacitor からエクスポートされなくなりました。これらのインポートを削除してください：

• AdaptyPaywall: 代わりに AdaptyFlow および AdaptyFlowPaywall を使用してください。
• ProductReference: 代わりに AdaptyProductIdentifier を使用してください。flow.paywalls[i].productIdentifiers から読み取ります。
• AdaptyPaywallBuilder: 削除されました。フローとペイウォールはネイティブでレンダリングされます。
• AdaptyAndroidSubscriptionUpdateParameters: ネストされた android 購入パラメータの形式を使用してください（下記参照）。

activate: lockMethodsUntilReady

lockMethodsUntilReady（v3 ではすでに非推奨の no-op でした）は削除されました。activate の呼び出しから削除してください — そのままではコンパイルが通りません:

- await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY', params: { lockMethodsUntilReady: true } });
+ await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY' });

makePurchase: Android パラメーター

非推奨となっていた MakePurchaseParamsInput のフラットな Android 形式は削除されました。ネストされた形式のみが使用可能です。Android の購入パラメーターは params: { android: { ... } } に移動してください。完全な例については購入の実装を参照してください。

オンボーディング API の非推奨化

レガシーのオンボーディング API は v4 で非推奨となり、Flow & ペイウォールビルダー に置き換えられました。引き続き動作しますが、将来のリリースで削除される予定のため、オンボーディングの Flow & ペイウォールビルダーへの移行を計画してください。

非推奨のシンボル: getOnboarding、getOnboardingForDefaultAudience、createOnboardingView、および OnboardingViewController。