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

Adapty Capacitor SDK 4.0 (beta) ではフローが導入され、それに伴いペイウォール API の名称が変更されました。新しい API は新しい Flow Builder と既存の Paywall Builder の両方で動作します。Adapty ダッシュボード側の設定変更は不要です。

クイックリファレンス

v3	v4
`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`
`AdaptyPaywallProduct` はその名前を維持します — プロダクトは引き続きフローに属し、`getPaywallProducts` も名前を維持したまま、`AdaptyFlow` を受け取るようになります。`getFlow` および `getFlowForDefaultAudience` メソッドは `locale` パラメータを受け取らなくなりました。購入とプロファイルに関するAPI（`makePurchase`、`restorePurchases`、`getProfile`、`identify`、`updateProfile`）、および `setFallback` によるフォールバックは変更ありません。ビューメソッド `present`、`dismiss`、`setEventHandlers`、`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 4.0.0-beta.2はSwift tools 6.2を使用しています。

v4にはネイティブAdapty SDK iOS 4.0.0-beta.2およびAndroid BOM 4.0.0-beta.1が含まれています。

インストール

パッケージを更新する

v4.0 はプレリリースのため、npm がキャレット/チルダ範囲でプレリリースバージョンを選択しないよう、正確なバージョンを指定してください：

npm install @adapty/capacitor@4.0.0-beta.1

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

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 のインストールをご覧ください。

フローの取得

getPaywall → getFlow

返り値の型が AdaptyPaywall から AdaptyFlow に変わり、locale オプションが削除されました。フローをレンダリングする際、ロケールは自動的に解決されます。カスタムペイウォールの場合、すべてのロケールは flow.remoteConfigs に含まれます：

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

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 });

データモデル

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

v3 `AdaptyPaywall` フィールド	v4 `AdaptyFlow` フィールド	操作
`remoteConfig?`（単一）	`remoteConfigs?: AdaptyRemoteConfig[]`（配列）	フローは設定された言語ごとにリモートコンフィグを1つ持ちます。ユーザーに合致するものを取得してください：`flow.remoteConfigs?.find((c) => c.lang === 'en')`。
`products`	`flow.paywalls[i].productIdentifiers`	プロダクト識別子は、フロー自体ではなく各フローバリアントに移動しました。
`webPurchaseUrl?`	`flow.paywalls[i].webPurchaseUrl`	フローから各ペイウォールバリアントに移動しました。
`version?: number`	`flowVersionId?: string`	リネームされ、型が `number` から `string` に変更されました。
`hasViewConfiguration`	削除	コードから `hasViewConfiguration` のチェックをすべて削除してください — `createFlowView` が代わりにスローするようになりました（フローの表示を参照）。
`requestLocale`	削除	ロケールはモデルの一部ではなくなりました。
（新規）	`paywalls: AdaptyFlowPaywall[]`	各エントリはフロー内のペイウォールバリアント1つを表します。
（新規）	`responseCreatedAt: number`	サーバーレスポンスのタイムスタンプ（ミリ秒単位）。
`hasViewConfiguration` と `requestLocale` は `AdaptyOnboarding` に残ります — フローモデルからのみ削除されます。

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

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

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 がそれらのビューを自動的に追跡します。

フローの表示

createPaywallView → createFlowView

ファクトリー関数名を変更し、AdaptyFlow を渡します。返されるコントローラーは PaywallViewController から FlowViewController に改名されましたが、そのメソッド（present、dismiss、setEventHandlers、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();

createFlowView はビューが設定されていないフローの場合に AdaptyError をスローします — これは v3 の hasViewConfiguration チェックを置き換えるものです：

- if (paywall.hasViewConfiguration) {
-   const view = await createPaywallView(paywall);
-   await view.present();
- }
+ try {
+   const view = await createFlowView(flow);
+   await view.present();
+ } catch (error) {
+   // the flow has no view configured, or view creation failed
+ }

フロービューは使い捨てです。dismiss() を呼び出すとビューは破棄されてイベントハンドラーもクリアされるため、フローを再度表示するには createFlowView を呼び出し直してください。

Android のセーフエリアパディング

CreateFlowViewParamsInput に新しいパラメーター enableSafeArea が追加されました。このパラメーターは Android のセーフエリアパディングを実行時に制御します。android キーの下にネストされており、デフォルト値は true です。

const view = await createFlowView(flow, {
  android: { enableSafeArea: true },
});

イベントの処理

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

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

他のすべてのイベントハンドラーはそのまま名前が変わりません。ただし、2つのハンドラーには第2引数が追加されています。onPurchaseCompleted は (purchaseResult, product)、onPurchaseFailed は (error, product) となり、product は関連する AdaptyPaywallProduct です。詳細はフロー＆ペイウォールイベントの処理を参照してください。

v4 では、オプトインで使用できる機能もいくつか追加されています。

adapty.openWebUrl({ url, openIn }) と adapty.requestAppReview() メソッド — これらはデフォルトの onUrlPress および onRequestAppReview ハンドラーをバックアップするもので、URLやアプリレビューのプロンプトはそのままネイティブで処理されます。これらのハンドラーをオーバーライドする場合にのみ、直接呼び出してください。
オブザーバーモードでのフロー内購入処理は、新しい onObserverPurchaseInitiated / onObserverRestoreInitiated ハンドラーを使用します。詳しくはオブザーバーモードでフローを表示するを参照してください。

デフォルト動作の変更

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

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.0 で非推奨となり、Flow Builder に置き換えられました。現在も動作しますが、将来のリリースで削除される予定です。オンボーディングを Flow Builder へ移行する計画を立ててください。

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