Adapty Unity SDK を v4.1 に移行する

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

4.x ラインではフローが導入され、それに伴いペイウォール API の名称が変更されました。新しい API はフローと連携し、旧ビルダーのペイウォールとも引き続き動作します。Adapty ダッシュボード側での設定変更は不要です。さらに、4.1 では外部アトリビューション API の名称変更、Adapty Attribution のオプトイン化、必須リスナーメソッドの追加、フォールバックファイル形式の変更が行われました。

Note

4.0ベータから移行する場合は、ベータタグを4.1.0インストールに置き換えてください。その後、適用されるセクションは新しいリスナーメソッド、外部アトリビューションAPIのリネーム、Adaptyアトリビューションのデフォルト無効化、フォールバックファイルの4つのみです。

クイックリファレンス

v3	v4.1
`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, ...)`
`AdaptyUICreatePaywallViewParameters`	`AdaptyUICreateFlowViewParameters`
`AdaptyUIPaywallView`	`AdaptyUIFlowView`
`AdaptyUI.PresentPaywallView(view, ...)` / `DismissPaywallView(view, ...)`	`AdaptyUI.PresentFlowView(view, ...)` / `DismissFlowView(view, ...)`
`Adapty.SetPaywallsEventsListener(listener)`	`Adapty.SetFlowsEventsListener(listener)`
`AdaptyPaywallsEventsListener`	`IAdaptyFlowsEventsListener`
`AdaptyEventListener`	`IAdaptyEventListener`、新しい必須メソッド `OnReceivePromotedPurchase` が追加
`AdaptyOnboardingsEventsListener`	`IAdaptyOnboardingsEventsListener`
`PaywallViewDidPerformAction`、`PaywallViewDidAppear`、その他の `PaywallView...` コールバック	`FlowViewDidPerformAction`、`FlowViewDidAppear`、その他の `FlowView...` コールバック
`PaywallViewDidFailRendering`	`FlowViewDidReceiveError`
`Adapty.UpdateAttribution(data, source, ...)` (`string` 型の source)	`Adapty.UpdateExternalAttribution(jsonString, provider, ...)` (`AdaptyExternalAttributionProvider` 型)
`AdaptyProfile.AppliedAttributionSources`（`IReadOnlyList<string>` 型）	`AdaptyProfile.AppliedExternalAttributionProviders`（`IReadOnlyList<AdaptyExternalAttributionProvider>` 型）
Adapty アトリビューションはデフォルトで有効	デフォルトで無効 — `Builder.SetAdaptyAttributionEnabled(true)` でオプトイン
3.x 向けフォールバックファイルをダウンロード済み	新しいフォールバックファイル形式 — ファイルを再ダウンロードしてください
`Adapty.SetFallbackPaywalls(...)` (v3 で非推奨)	削除済み — `Adapty.SetFallback(fileName, ...)` を使用してください
`Builder.SetIDFACollectionDisabled(...)` (v3 で非推奨)	削除済み — `Builder.SetAppleIDFACollectionDisabled(...)` を使用してください
`paywall.Products`（`AdaptyProductReference` のリスト）	削除済み — `ProductIdentifiers` または `VendorProductIds` を使用するか、`GetPaywallProducts(flow)` を呼び出してフル情報を取得してください
`AdaptyProductReference`	パブリック型として削除 — データモデルを参照
`paywall.RemoteConfigString`	削除済み — `flow.RemoteConfig?.Data` を使用してください

AdaptyPaywallProduct はその名前を保持します。プロダクトは引き続きフローに属し、GetPaywallProducts もその名前を保持しますが、現在は AdaptyFlow を受け取ります。GetFlow および GetFlowForDefaultAudience メソッドは locale パラメーターを受け取らなくなりました。購入およびプロファイル API（MakePurchase、RestorePurchases、GetProfile、Identify、UpdateProfile）は変更されていません。SetFallback はそのシグネチャを保持しますが、読み込むファイルは再ダウンロードが必要です。詳細はフォールバックファイルを参照してください。オンボーディングメソッドは引き続き動作しますが、非推奨となっています。詳細はオンボーディング API の非推奨を参照してください。一部のデフォルト動作が変更されました。詳細はデフォルト動作の変更を参照してください。

インストール

Unity Package Manager から SDK 4.1 をインストールするには、Git URL にバージョンタグを付加してください：

https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.1.0

Unity パッケージからインストールする場合は、4.1.0 リリースから adapty-unity-plugin-4.1.0.unitypackage をダウンロードしてください。完全なセットアップ手順は Adapty SDK のインストールを参照してください。

4.x にはビルドセットアップに関する変更が 2 点あります：

iOS の依存関係が Swift Package Manager に移行しました。 ネイティブの Adapty iOS SDK は、CocoaPods の pod ではなくリモートの Swift パッケージとして宣言されるようになりました。External Dependency Manager を 1.2.188 以降にアップデートしてください。それより古いバージョンは Swift Package Manager の依存関係をサポートしていません。CocoaPods の手順（iOS Resolver -> Install Cocoapods、Unity-iPhone.xcworkspace を開くなど）は不要になりました。iOS 向けのビルドには Xcode 26 以降が必要です。Swift パッケージは Swift tools 6.2 でビルドされるためです。
iOS のデプロイターゲットは 15.0 以降にする必要があります。 Unity Editor に新しいビルドバリデーターが追加され、ターゲットがそれより低い場合は iOS ビルドが停止されます。

The underlying native Adapty SDKs are bumped to 4.x on both platforms and are resolved automatically — no other build changes are needed.

フローの取得

GetPaywall → GetFlow

戻り値の型が AdaptyPaywall から AdaptyFlow に変わり、locale パラメーターが削除されます — フローをレンダリングする際、ロケールは自動的に解決されます。カスタムペイウォールの場合、すべてのロケールは flow.RemoteConfigs に返されます。

- Adapty.GetPaywall("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
+ Adapty.GetFlow("YOUR_PLACEMENT_ID", (flow, error) => {
      if (error != null) {
          // handle the error
          return;
      }
-     // use the paywall
+     // use the flow
  });

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

- Adapty.GetPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", (paywall, error) => { /* ... */ });
+ Adapty.GetFlowForDefaultAudience("YOUR_PLACEMENT_ID", (flow, error) => { /* ... */ });

GetPaywallProducts(paywall) → GetPaywallProducts(flow)

GetPaywallProducts は名前を維持したまま、AdaptyFlow を受け取るように変わります:

- Adapty.GetPaywallProducts(paywall, (products, error) => {
+ Adapty.GetPaywallProducts(flow, (products, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      // use the products
  });

データモデル

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

v3 `AdaptyPaywall` プロパティ	v4 `AdaptyFlow` プロパティ	アクション
`RemoteConfig`（単一、nullable）	`RemoteConfigs`（リスト）	フローは設定された言語ごとに1つのリモートコンフィグを持ちます。`flow.RemoteConfigs` からユーザーに一致するものを読み取ってください。`flow.RemoteConfig` ショートカットは最初のエントリを返します。
（新規）	`Paywalls`（`AdaptyFlowPaywall` のリスト）	各エントリはフロー内の1つのペイウォールバリエーションで、独自の `Name`、`VariationId`、`ProductIdentifiers` を持ちます。Web ペイウォールのメソッドは `AdaptyFlowPaywall` を受け取ります。詳しくは Web ペイウォールメソッドを参照してください。
`ProductIdentifiers`、`VendorProductIds`	維持	`AdaptyFlow` では、これらはすべてのペイウォールバリエーションをまたいでプロダクトを集約します。各バリエーションも独自の `ProductIdentifiers` と `VendorProductIds` を持ちます。プロダクトを取得するには、引き続き `GetPaywallProducts(flow)` を呼び出してください。
`HasViewConfiguration`	削除	コードから `HasViewConfiguration` のチェックをすべて削除してください。代わりに `CreateFlowView` がエラーを返します（フローの表示を参照）。
`Products`（`AdaptyProductReference` のリスト）	削除	`AdaptyProductReference` は非公開になり、それとともに `PromotionalOfferId`、`WinBackOfferId`、`AndroidOfferId` の値も使えなくなりました。`ProductIdentifiers`（`VendorProductId` と Android 専用の `BasePlanId`（v3 の `AndroidBasePlanId`）を持つ `AdaptyProductIdentifier` のリスト）を使用するか、価格やオファーを含む完全な `AdaptyPaywallProduct` オブジェクトが必要な場合は `GetPaywallProducts(flow)` を呼び出してください。
`RemoteConfigString`	削除	リモートコンフィグ自体から文字列を読み取ってください: `flow.RemoteConfig?.Data`、または `flow.RemoteConfigs` の該当エントリから取得します。
（新規）	`FlowVersionId`（nullable）	フローのバージョン識別子。利用できない場合は `null`。

AdaptyPaywallProduct に新しいフィールドが追加されました: FlowProductId は、フロー内でのプロダクトの識別子で、フローに属さないプロダクトの場合は null になります。

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

OpenWebPaywall と CreateWebPaywallUrl はメソッド名はそのままですが、paywall 引数に AdaptyFlowPaywall を渡すようになりました。これは flow.Paywalls 内のいずれかのバリアントです。引き続き AdaptyPaywallProduct を渡すこともできます:

- Adapty.OpenWebPaywall(paywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ var flowPaywall = flow.Paywalls.FirstOrDefault();
+ if (flowPaywall != null) {
+     Adapty.OpenWebPaywall(flowPaywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ }

フローのビュー数を計測する

LogShowPaywall → LogShowFlow

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

- Adapty.LogShowPaywall(paywall, (error) => { /* ... */ });
+ Adapty.LogShowFlow(flow, (error) => { /* ... */ });

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

フローの表示

CreatePaywallView → CreateFlowView

ファクトリーメソッドの名前を変更し、AdaptyFlow を渡します。返されるビューの型は AdaptyUIPaywallView から AdaptyUIFlowView に変更されていますが、そのメソッド（Present、Dismiss）は変更されておらず、省略可能なパラメーターオブジェクトは AdaptyUICreateFlowViewParameters という新しい名前になり、同じフィールド（LoadTimeout、PreloadProducts、CustomTags、CustomTimers、CustomAssets、ProductPurchaseParameters）に加え、Locale と EnableSafeAreaPaddings の2つの新しいフィールドが追加されています：

Note

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

- AdaptyUI.CreatePaywallView(paywall, parameters, (view, error) => {
+ AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      view.Present((error) => { /* handle the error */ });
  });

CreateFlowView はビューが設定されていないフローに対してエラーを返します — これにより v3 の HasViewConfiguration チェックが不要になります：

- if (paywall.HasViewConfiguration) {
-     AdaptyUI.CreatePaywallView(paywall, null, (view, error) => { /* ... */ });
- }
+ AdaptyUI.CreateFlowView(flow, (view, error) => {
+     if (error != null) {
+         // the flow has no view configured, or view creation failed
+         return;
+     }
+     view.Present((error) => { /* handle the error */ });
+ });

Note

フロービューはシングルユース（使い捨て）です。Dismiss を呼び出すとビューが破棄されるため、再度フローを表示するには CreateFlowView を再度呼び出してください。

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

AdaptyUICreateFlowViewParameters には EnableSafeAreaPaddings が追加されており、実行時に Android のセーフエリアパディングを制御します。iOS では無視され、デフォルト値は true です。

var parameters = new AdaptyUICreateFlowViewParameters()
    .SetEnableSafeAreaPaddings(false);

イベントの処理

リスナーインターフェースは C# の I プレフィックス規則に準拠するようになりました。レガシーのエイリアスは保持されていないため、実装箇所で AdaptyEventListener を IAdaptyEventListener に、AdaptyOnboardingsEventsListener を IAdaptyOnboardingsEventsListener にそれぞれ名前変更してください。

フローイベントリスナーの名前が AdaptyPaywallsEventsListener から IAdaptyFlowsEventsListener に変更され、登録メソッドが SetPaywallsEventsListener から SetFlowsEventsListener に変更されました。また、コールバックの PaywallView プレフィックスが FlowView に変更されています。既存のハンドラー本体のコードを変更する必要はありません。インターフェースとメソッドの名前を変更するだけです。

- public class MyListener : MonoBehaviour, AdaptyPaywallsEventsListener {
-     public void PaywallViewDidFinishPurchase(
-         AdaptyUIPaywallView view,
+ public class MyListener : MonoBehaviour, IAdaptyFlowsEventsListener {
+     public void FlowViewDidFinishPurchase(
+         AdaptyUIFlowView view,
          AdaptyPaywallProduct product,
          AdaptyPurchaseResult purchasedResult
      ) {
          // custom logic after purchase
      }
      // ...
  }

- Adapty.SetPaywallsEventsListener(myListener);
+ Adapty.SetFlowsEventsListener(myListener);

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

- public void PaywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) { }
+ public void FlowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) { }

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

新しい必須メソッド: OnReceivePromotedPurchase

SDK バージョン 4.1 以降、IAdaptyEventListener にメソッドが 1 つ追加されました。このインターフェースを実装しているすべてのクラスは、以下のメソッドを追加するまでコンパイルエラーになります:

public void OnReceivePromotedPurchase(AdaptyPromotedProduct product) {
    // The user tapped one of your in-app purchases on your App Store product page.
    // Complete the purchase through Adapty:
    Adapty.MakePromotedPurchase(product, (result, error) => { /* ... */ });
}

このメソッドはApp Storeのプロモーションアプリ内課金専用であり、Androidでは呼び出されません。本体を空にしないでください。iOS 16.4以降では、SDKがここでの購入処理を完了するまで待機するため、本体が空だとユーザーがすでに開始した購入が破棄されます。それより前のバージョンでは、このような購入は自動的に完了していました。詳細はApp Storeのプロモーションアプリ内課金を参照してください。

新しい API

Adapty.SetObserverModeResolver(...) と IAdaptyUIObserverModeResolver — SDKがObserverモードで動作している間、フローから開始された購入と復元を処理します。以前はネイティブのiOSおよびAndroid SDKでのみ利用可能でした。Observerモードでのフローの表示を参照してください。
Adapty.SetSystemRequestsHandler(...) と IAdaptyUISystemRequestsHandler — フローからのシステムリクエスト用に予約されています：OSの権限プロンプト（FlowViewDidAskPermission）とアプリレビューリクエスト（FlowViewDidRequestAppReview）。フローはこれらのリクエストをまだトリガーしないため、ハンドラーを登録する必要はありません。
AdaptyUICreateFlowViewParameters.Locale（SetLocaleで設定）— フローのデフォルトではなく、特定のビルダーのローカライズでフローまたはペイウォールをレンダリングします。フローはビューが作成されるときにローカライズされるため、ここがローカライズを選択できる唯一の場所であり、作成されたビューはview.Localeでビルド時のローカライズを報告します。ローカライズとロケールコードの使用を参照してください。
IAdaptyFlowsEventsListenerの新しいFlowViewDidReceiveAnalyticEventコールバックは、フローからのアナリティクスイベントを報告します。ユーザーが開いたすべての画面のスクリーンビューから始まります。フロースクリーンビューのトラッキングを参照してください。
AdaptyUI.OpenUrl(url, openIn, ...) と AdaptyUI.RequestAppReview(...) — open_urlアクションとアプリレビューリクエストの背後にあるネイティブ処理。デフォルトのURL動作を維持するにはFlowViewDidPerformActionからOpenUrlを呼び出してください。RequestAppReviewはデフォルトのアプリレビュープロンプトをバックアップしますが、フローはまだこれをトリガーしません。

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

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

4.1以前	4.1
`Adapty.UpdateAttribution(data, source, ...)`	`Adapty.UpdateExternalAttribution(jsonString, provider, ...)`
`source`（`string`型）	`provider`（`AdaptyExternalAttributionProvider`型）
`AdaptyProfile.AppliedAttributionSources`（`IReadOnlyList<string>`型）	`AdaptyProfile.AppliedExternalAttributionProviders`（`IReadOnlyList<AdaptyExternalAttributionProvider>`型）

メソッド名を変更するだけでは不十分です。同じ編集でプロバイダー引数も入れ替えてください：

- Adapty.UpdateAttribution(attributionJsonString, "adjust", (error) => { /* ... */ });
+ Adapty.UpdateExternalAttribution(attributionJsonString, AdaptyExternalAttributionProvider.Adjust, (error) => { /* ... */ });

AdaptyExternalAttributionProviderは、バックエンドがプロバイダーを識別するための識別子を持っており、6つの共有インスタンスがあります：AppleAds（apple_search_ads）、Adjust、Appsflyer、Branch、Tenjin、Custom。このSDKリリース後にAdaptyが追加したプロバイダーの場合は、識別子から直接インスタンスを生成してください — new AdaptyExternalAttributionProvider("your_provider") — そのままバックエンドに送信されます。前後の空白は自動的に削除されます。

アトリビューションデータはシリアライズされたJSON文字列として渡します。ディクショナリとして保持している場合は、先にシリアライズしてください：

var attributionJsonString = Newtonsoft.Json.JsonConvert.SerializeObject(attribution);

プロファイル側では、新しい型を通じて適用済みプロバイダーを読み取ります：

- if (profile.AppliedAttributionSources.Contains("apple_search_ads")) {
+ if (profile.AppliedExternalAttributionProviders.Contains(AdaptyExternalAttributionProvider.AppleAds)) {
      // Apple Ads attribution has been applied
  }

Adapty アトリビューションはデフォルトで無効

Warning

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

以前のバージョンでは、SDK は Adapty アトリビューションのインストールを自動的に登録していました。SDK バージョン 4.1 以降、これはデフォルトでオフになっています。SDK はインストールを登録せず、OnInstallationDetailsSuccess および OnInstallationDetailsFail リスナーコールバックは一切呼び出されず、GetCurrentInstallationStatus は NotAvailable ステータスを返します。

Adapty アトリビューションを使用する場合は、SDK をアクティベートする際に有効化してください：

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAdaptyAttributionEnabled(true);

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

フォールバックファイル

フォールバックファイルのフォーマットはSDK 4.1で変更されました。iOSおよびAndroidのフォールバックファイルを Placements > Fallbacks から再度ダウンロードし、Assets/StreamingAssets 内の既存ファイルと置き換えてください（以前のバージョン向けにダウンロード済みの場合も同様です）。

Warning

この手順を省略してもコンパイルエラーは発生しません。ただし省略した場合、SetFallback が DecodingFailed（adapty_code: 2006）を返し、すべてのプレースメントでフォールバックが機能しなくなります。

デフォルト動作の変更

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

購入完了時の動作: v3 では購入成功後にビューが自動的に閉じられていました。v4 では、購入またはエラーの後もフローは開いたまま維持され、明示的に閉じるまで SDK は何も行いません。ユーザーがアクセスを取得したら、FlowViewDidFinishPurchase 内で自ら view.Dismiss(...) を呼び出してください。
Android のシステムバック: システムの戻るボタン（または戻るジェスチャー）は、SystemBack アクションとして FlowViewDidPerformAction に渡されるようになり、フローを自動的に閉じなくなりました。これは、システムジェスチャーでフローを閉じられない iOS の動作に合わせたものです。ユーザーが明示的に離脱できるよう（Close ボタンや on_device_back アクションなど）、またはアクション処理時に自分でビューを閉じてください。
ビューは使い捨て: Dismiss を呼び出すとビューは破棄されます。フローを再度表示するには CreateFlowView を再度呼び出してください。
オブザーバーモードのトランザクション: ReportTransaction は成功時にデコードエラーを返さなくなりました。v3 では成功レスポンスのパースに誤りがあり、成功した報告が常にエラーで完了していました。

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

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

非推奨のシンボル: GetOnboarding、GetOnboardingForDefaultAudience、AdaptyUI.CreateOnboardingView、AdaptyUI.PresentOnboardingView、AdaptyUI.DismissOnboardingView、Adapty.SetOnboardingsEventsListener。