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 用のフォールバックファイルをダウンロード済み	新しいフォールバックファイル形式。ファイルを再ダウンロードしてください
プロモートされたアプリ内課金は非対応	対応済み。SDK が処理するか、`didReceivePromotedPurchaseStream` からアプリ側で処理できます
`dismissFlowView(view)` は常にビューを解放	`destroy: false` を指定するとビューを保持し、再表示できます

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

インストール

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

dependencies:
  adapty_flutter: ^4.1.1

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

dependencies:
  adapty_flutter_kids: ^4.1.1

動作要件は 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 が古いファイルを拒否し、すべてのプレースメントでフォールバックが機能しなくなります。

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

Flutter SDK 4.0 は、App Store プロダクトページでプロモートされたアプリ内課金をサポートしていませんでした。これは、ベースとなるネイティブ iOS SDK にその API がなかったためです。4.1 ではこの機能が追加されましたが、新たな機能追加であり、移行手順ではありません。新しいコードを追加しなければ、アップデートしてもアプリの動作に変化はありません。

デフォルトでは、SDKがプロモーション購入を自動的に完了します。たとえば先に画面を表示したい場合など、自分で完了させるには、didReceivePromotedPurchaseStream をサブスクライブして、プロダクトを makePromotedPurchase に渡してください。このストリームにサブスクライバーが存在する間、SDKはプロモーション購入を自動的に完了しなくなります。

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

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

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

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

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