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

Adapty Flutter SDK 4.1 では、Adapty Attribution の有効化方法が変更され、外部アトリビューション API の名称が変更され、フォールバックファイルのフォーマットが変更されました。また、App Store のプロモートされたアプリ内課金をアプリに引き渡す機能が追加され、フローのビューを閉じた後も維持する方法が追加されました。

Warning

名前変更されたAPIは完全な変更です。古い名前は完全に削除されており、移行用の非推奨エイリアスはありません。4.0.xに対してコンパイルできていたコードも、以下に記載されたすべての呼び出し箇所を変更しない限り4.1ではビルドに失敗します。

まだ3.xをお使いの場合は、まずv4.0への移行を行ってから、このガイドに従ってください。

クイックリファレンス

v4.0	v4.1
Adapty アトリビューションはデフォルトで有効	Adapty アトリビューションはデフォルトで無効。`withAdaptyAttributionEnabled(true)` でオプトイン
`Adapty().updateAttribution(attribution, source: source)`	`Adapty().updateExternalAttribution(attribution, provider: provider)`
`AdaptyAttributionSource`	`AdaptyExternalAttributionProvider`（新しい `custom` 値を追加）
`AdaptyProfile.appliedAttributionSources`	`AdaptyProfile.appliedExternalAttributionProviders`
4.0 用のフォールバックファイル	新しいフォールバックファイル形式。ファイルを再ダウンロードしてください
プロモートされたアプリ内課金は自動で完了	`didReceivePromotedPurchaseStream` からアプリが完了処理を行う
`dismissFlowView(view)` は常にビューを解放	`destroy: false` を指定するとビューを保持して再表示できる

購入、プロファイル、フロー表示の各 API に変更はありません。

インストール

pubspec.yaml の adapty_flutter を v4.1 に更新してください：

dependencies:
  adapty_flutter: 4.1.0

アプリで Kids Mode を使用している場合は、代わりに adapty_flutter_kids を指定してください：

dependencies:
  adapty_flutter_kids: 4.1.0

動作要件は 4.0 から変更なし：Flutter 3.32.0（Dart 3.8.0）および iOS 15.0。詳細なセットアップ手順は Adapty SDK のインストールを参照してください。

4.1では、ネイティブ iOS SDK を 4.1.3 に、ネイティブ Android SDK を 4.1.1 にピン留めしています。iOS のリリースでは、フローアナリティクスイベントの数値パラメーターも修正されています。修正前は、すべての 0 と 1 が flowViewDidReceiveAnalyticEvent に false と true として渡されていました。

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

Warning

SDK 4.1 にアップデートしてオプトインしない場合、Adapty アトリビューションは通知なく停止します — インストールの記録が止まっても、何も警告されません。

4.0以前のバージョンでは、SDKはAdapty Attributionのインストールを自動的に登録していました。4.1以降、これはデフォルトでオフになっています。SDKはインストールを登録せず、onUpdateInstallationDetailsSuccessStreamとonUpdateInstallationDetailsFailStreamはイベントを発行しません。また、getCurrentInstallationStatusはAdaptyInstallationStatusNotAvailableを返します。

Adapty Attributionを使用する場合は、SDKの設定時に有効にしてください：

  await Adapty().activate(
-   configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'),
+   configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
+     ..withAdaptyAttributionEnabled(true),
  );

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

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

外部プロバイダー（Adjust、AppsFlyer、Branch、Tenjin、またはカスタムプロバイダー）からアトリビューションデータを渡す API が、ネイティブ SDK に合わせてリネームされました。

updateAttribution → updateExternalAttribution

メソッド名が変更され、source パラメーターが provider に改名されました。このパラメーターは文字列の代わりに AdaptyExternalAttributionProvider を受け取るようになりました。アトリビューションデータは引き続きマップ形式です。

- await Adapty().updateAttribution(attribution, source: 'adjust');
+ await Adapty().updateExternalAttribution(attribution, provider: AdaptyExternalAttributionProvider.adjust);

AdaptyAttributionSource → AdaptyExternalAttributionProvider

プロバイダーの型名が変更されました。文字列のオープンラッパーのままであり、事前定義された値は appleAds、adjust、appsflyer、branch、tenjin、そしてAdaptyが直接統合していないプロバイダー向けの新しい custom です。任意の文字列からも構築できるため、Adaptyが後から追加したプロバイダーもSDKのアップデートなしに動作します。

final provider = AdaptyExternalAttributionProvider('my_provider');

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

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

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

シリアライズされたプロファイルフィールドの名前は applied_attribution_sources のままなので、生のプロファイルを読み取るバックエンドに変更は不要です。ただし、プロパティを読み取るコードは変更が必要です。詳細はApple Ads向けターゲットペイウォールの表示をご覧ください。

フォールバックファイル

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

Warning

この手順を省略してもビルドエラーは発生しません。ただし省略した場合、SDK が古いファイルを拒否し、すべてのプレースメントでフォールバックが機能しなくなります。

⚠️ プロモーションされたアプリ内課金がアプリの応答を待つようになりました

Warning

これは利便性に合わせて採用する新機能ではなく、動作の変更です。4.0では、App Storeのプロダクトページでプロモーションされたアプリ内課金は単独で完了していました。4.1では、アプリがそれをリッスンしている場合にのみ完了します。以下のコードなしに4.1をリリースすると、それらの購入が発生しなくなります — App Storeはプロダクトをアプリに渡しますが、それ以降何も起こりません。

4.0では、AdaptyはプロモートされたAndroid向けの購入を他のトランザクションと同様に記録しており、アプリ側でインターセプトする手段はありませんでした。4.1では、アプリがその制御を持てるようになり、購入を完了させる責任も生じます。

didReceivePromotedPurchaseStream を購読し、プロダクトを makePromotedPurchase に渡してください：

Adapty().didReceivePromotedPurchaseStream.listen((product) async {
  try {
    final result = await Adapty().makePromotedPurchase(product: product);
    // process the purchase result
  } on AdaptyError catch (e) {
    // handle the error
  }
});

activate の直後、アプリ起動時にプロモーション購入が届く前にストリームを購読してください。このストリームはブロードキャストストリームであり、再生機能はありません。リスナーがいない間に配信されたプロダクトはドロップされ、購入は失われます。

makePromotedPurchase は購入パラメーターを受け取りません。プロモーション対象プロダクトはペイウォールではなく App Store から届くため、ペイウォールのコンテキストを持たないためです。戻り値は makePurchase と同じ AdaptyPurchaseResult です。

Warning

このストリームは StoreKit 2 上に構築されており、iOS 16.4 以降が必要です。iOS 16.4 未満および Android では、このストリームはイベントを発火しません。

プロモーション対象のプロダクトにサブスクリプションオファーが含まれている場合、SDKは購入時に自動的にそのオファーを適用します。オファーはApp Storeの購入インテントから読み取られますが、これはiOS 18.0以降でのみ利用可能です。iOS 16.4〜17.xでは、購入は通常価格で処理されます。

フローのビューを非表示後も維持する

AdaptyUI().dismissFlowView と AdaptyUIFlowView.dismiss は destroy フラグを受け取ります:

await AdaptyUI().dismissFlowView(view, destroy: false);

デフォルト値は true で、これまでどおりビューを解放します。destroy: false を指定するとビューがメモリ上に残るため、再度表示したときにユーザーが離脱した画面へ戻り、フローが積み上げてきた状態も保持されます。

この方法で保持したビューは、destroy: true で非表示にするまで保持され続けます。解放済みのビューを再表示しようとすると失敗するため、そのフローをもう一度表示したい場合は createFlowView を再度呼び出してください。

hasViewConfiguration

AdaptyFlow.hasViewConfiguration は、フローがUIスキーマを持つことも必要になりました。これにより、AdaptyUI がレンダリングできるフローに対してのみ true を返します。スキーマなしでアプリに届いたフローは、4.0 では true を返していましたが、現在は false を返します。詳しくはビュー設定の取得を参照してください。