ÿÿ Migration lên Adapty Flutter SDK v4.0 | Tài liệu Adapty
English 中文TürkçeРуÑÑкийEspañol日本語Tiếng Việt

Migrate Adapty Flutter SDK sang phiên bản 4.0

Adapty Flutter SDK 4.0 giới thiệu flow và đổi tên các API paywall tương ứng. Các API mới hoạt động với cả Flow Builder mới và Paywall Builder hiện có — không cần thay đổi cấu hình nào trên Adapty Dashboard.

Tham khảo nhanh

v3v4
Adapty().getPaywall(placementId: id)Adapty().getFlow(placementId: id)
Adapty().getPaywallForDefaultAudience(placementId: id)Adapty().getFlowForDefaultAudience(placementId: id)
Adapty().getPaywallProducts(paywall: paywall)Adapty().getPaywallProducts(flow: flow)
Adapty().logShowPaywall(paywall: paywall)Adapty().logShowFlow(flow: flow)
AdaptyPaywall (kiểu)AdaptyFlow
AdaptyPaywallFetchPolicy (kiểu)AdaptyFlowFetchPolicy
AdaptyUI().createPaywallView(paywall: paywall)AdaptyUI().createFlowView(flow: flow)
AdaptyUIPaywallView (kiểu)AdaptyUIFlowView
AdaptyUIPaywallPlatformView (widget)AdaptyUIFlowPlatformView
AdaptyUI().presentPaywallView(view) / dismissPaywallView(view)AdaptyUI().presentFlowView(view) / dismissFlowView(view)
AdaptyUIPaywallsEventsObserverAdaptyUIFlowsEventsObserver
AdaptyUI().setPaywallsEventsObserver(observer)AdaptyUI().setFlowsEventsObserver(observer)
callback paywallViewDid*callback flowViewDid*
paywallViewDidFailRenderingflowViewDidReceiveError
AdaptyPaywallProduct vẫn giữ nguyên tên — các sản phẩm vẫn thuá»™c vá» má»™t flow, và getPaywallProducts giá» nhận vào má»™t AdaptyFlow. Bạn không còn cần truyá»n locale khi lấy má»™t flow nữa. Các API mua hàng và hồ sÆ¡ ngÆ°á»i dùng (makePurchase, restorePurchases, getProfile, identify, v.v.) không thay đổi, tÆ°Æ¡ng tá»± vá»›i các phÆ°Æ¡ng thức giao diện present, dismiss và showDialog. Má»™t số hành vi mặc định đã thay đổi — xem Thay đổi hành vi mặc định.

Phiên bản tối thiểu

Adapty Flutter SDK 4.0 nâng cao yêu cầu tối thiểu:

  • iOS 15.0 — deployment target iOS tối thiểu, tăng từ iOS 13.0.
  • Xcode 26 trở lên — iOS SDK native sá»­ dụng Swift tools 6.2.
  • Flutter 3.32.0 (Dart 3.8.0) trở lên.

Cài đặt

Cập nhật package

Package bạn cài đặt phụ thuộc vào việc ứng dụng có sử dụng Kids Mode hay không.

Với hầu hết các ứng dụng, hãy cập nhật adapty_flutter lên v4.0 trong pubspec.yaml:

dependencies:
  adapty_flutter: 4.0.0

Nếu ứng dụng sử dụng Kids Mode, hãy chỉ định adapty_flutter_kids thay thế:

dependencies:
  adapty_flutter_kids: 4.0.0

Gói Ä‘á»™c lập này loại bá» mã IDFA và theo dõi quảng cáo để tuân thủ các yêu cầu của App Store. Cập nhật Ä‘Æ°á»ng dẫn import Dart thành package:adapty_flutter_kids/adapty_flutter.dart. Ngoài ra, quá trình migration hoàn toàn giống vá»›i gói thông thÆ°á»ng.

Kids Mode cũng yêu cầu bạn tắt tính năng thu thập địa chỉ IP trong Adapty Dashboard — xem Kids Mode để biết hướng dẫn cài đặt đầy đủ.

iOS: SDK iOS native giỠđược phân phối qua Swift Package Manager

Repo spec của CocoaPods sẽ chuyển sang chế Ä‘á»™ chỉ Ä‘á»c vào tháng 12 năm 2026, vì vậy bắt đầu từ v4, SDK iOS native không còn được phân phối qua CocoaPods nữa — plugin sẽ kéo nó qua Swift Package Manager mà thôi.

Nếu bạn đang dùng Flutter 3.32–3.43, hãy bật hỗ trợ Swift Package Manager một lần:

flutter config --enable-swift-package-manager

Flutter 3.44 trở lên đã bật Swift Package Manager theo mặc định, nên bạn không cần làm gì thêm.

Lấy flows

getPaywall → getFlow

Kiểu trả vá» thay đổi từ AdaptyPaywall sang AdaptyFlow, và bạn không cần truyá»n locale nữa — khi render má»™t flow, localization sẽ được tá»± Ä‘á»™ng xá»­ lý; vá»›i các paywall tùy chỉnh, tất cả locale đã cấu hình sẽ được trả vá» trong flow.remoteConfigs:

- final paywall = await Adapty().getPaywall(placementId: 'YOUR_PLACEMENT_ID', locale: 'en');
+ final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');

getPaywallForDefaultAudience cũng được đổi tên theo cách tương tự:

- final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID', locale: 'en');
+ final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');

Kiểu fetch policy được đổi tên từ AdaptyPaywallFetchPolicy thành AdaptyFlowFetchPolicy; các tùy chá»n của nó (reloadRevalidatingCacheData, returnCacheDataElseLoad, returnCacheDataIfNotExpiredElseLoad) không thay đổi.

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts giữ nguyên tên nhưng giỠnhận một AdaptyFlow qua tham số flow:

- final products = await Adapty().getPaywallProducts(paywall: paywall);
+ final products = await Adapty().getPaywallProducts(flow: flow);

Mô hình dữ liệu

getFlow trả vỠAdaptyFlow thay vì AdaptyPaywall, và cấu trúc đối tượng đã thay đổi:

Thành viên AdaptyPaywall v3Thành viên AdaptyFlow v4Hành động
remoteConfig (Ä‘Æ¡n, nullable)remoteConfigs (danh sách)Má»™t flow chứa má»™t remote config cho má»—i ngôn ngữ được cấu hình. Getter remoteConfig vẫn tồn tại và trả vá» mục đầu tiên; để chá»n má»™t ngôn ngữ cụ thể, hãy tìm trong remoteConfigs theo locale của nó.
productIdentifiersproductIdentifiersÄược giữ lại, nhÆ°ng hiện được thu thập từ tất cả các biến thể paywall trong flow. Các identifier theo từng biến thể nằm ở flow.paywalls[i].productIdentifiers.
hasViewConfigurationhasViewConfigurationKhông thay đổi.
placementId (deprecated)đã xóaDùng flow.placement.id.
revision (deprecated)đã xóaDùng flow.placement.revision.
vendorProductIds (deprecated)đã xóaDùng productIdentifiers.
(mới)paywalls (danh sách AdaptyFlowPaywall)Mỗi mục là một biến thể paywall trong flow, với name, variationId và productIdentifiers riêng.
AdaptyPaywallViewConfiguration is no longer exposed — the view configuration is now opaque. Remove any references to this type.

Phương thức paywall web

openWebPaywall và createWebPaywallUrl giữ nguyên tên, nhÆ°ng tham số paywall giá» nhận AdaptyFlowPaywall (má»™t biến thể flow) thay vì AdaptyPaywall. Bạn vẫn có thể truyá»n AdaptyPaywallProduct nhÆ° trÆ°á»›c.

  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
- await Adapty().openWebPaywall(paywall: paywall);
+ if (flow.paywalls.isNotEmpty) {
+   await Adapty().openWebPaywall(paywall: flow.paywalls[0]);
+ }

Theo dõi lượt xem flow

logShowPaywall → logShowFlow

logShowPaywall được đổi tên thành logShowFlow và nhận vào má»™t AdaptyFlow. Sá»± kiện vẫn được ghi lại đối vá»›i cùng má»™t biến thể, vì vậy các chỉ số funnel và A/B test hiện có vẫn hoạt Ä‘á»™ng bình thÆ°á»ng mà không cần thay đổi gì trên dashboard.

- await Adapty().logShowPaywall(paywall: paywall);
+ await Adapty().logShowFlow(flow: flow);

Giống nhÆ° ở v3, bạn không cần gá»i phÆ°Æ¡ng thức này khi hiển thị các flow hoặc paywall được dá»±ng bởi Flow Builder hay Paywall Builder — Adapty tá»± Ä‘á»™ng theo dõi các lượt xem đó.

Hiển thị flows

createPaywallView → createFlowView

Äổi tên phÆ°Æ¡ng thức và truyá»n AdaptyFlow qua tham số flow. Các tham số khác (loadTimeout, preloadProducts, customTags, customTimers, customAssets, productPurchaseParams) không thay đổi, cÅ©ng nhÆ° các phÆ°Æ¡ng thức của view là present, dismiss, và showDialog:

- final view = await AdaptyUI().createPaywallView(paywall: paywall);
+ final view = await AdaptyUI().createFlowView(flow: flow);
  await view.present();

AdaptyUIPaywallView → AdaptyUIFlowView

Kiểu view được đổi tên. Thuộc tính paywallVariationId đã bị xóa — hãy dùng variationId thay thế:

- void flowViewDidAppear(AdaptyUIPaywallView view) {
+ void flowViewDidAppear(AdaptyUIFlowView view) {

AdaptyUIPaywallPlatformView → AdaptyUIFlowPlatformView

Nếu bạn nhúng view dÆ°á»›i dạng widget trong widget tree, hãy đổi tên nó và truyá»n tham số flow. Các callback sá»± kiện (onDidAppear, onDidFinishPurchase, v.v.) vẫn giÿÿữ nguyên tên:

- AdaptyUIPaywallPlatformView(
-   paywall: paywall,
+ AdaptyUIFlowPlatformView(
+   flow: flow,
    onDidFinishPurchase: (view, product, purchaseResult) { /* … */ },
  )

Má»™t flow view được tạo bằng createFlowView chỉ dùng được má»™t lần: sau khi bạn gá»i dismiss(), view đó sẽ được giải phóng khá»i bá»™ nhá»› và không thể hiển thị lại — hãy gá»i createFlowView má»™t lần nữa nếu muốn hiển thị flow lại.

Xử lý sự kiện

Tên lớp observer được đổi từ AdaptyUIPaywallsEventsObserver thành AdaptyUIFlowsEventsObserver, phương thức đăng ký từ setPaywallsEventsObserver thành setFlowsEventsObserver, và tất cả các callback paywallViewDid* thành flowViewDid*:

- class MyObserver extends AdaptyUIPaywallsEventsObserver {
+ class MyObserver extends AdaptyUIFlowsEventsObserver {
    @override
-   void paywallViewDidPerformAction(AdaptyUIPaywallView view, AdaptyUIAction action) {
+   void flowViewDidPerformAction(AdaptyUIFlowView view, AdaptyUIAction action) {
      // …
    }
  }

- AdaptyUI().setPaywallsEventsObserver(this);
+ AdaptyUI().setFlowsEventsObserver(this);

Ba callback sau đây là bắt buộc — observer của bạn sẽ không biên dịch được nếu thiếu chúng:

  • flowViewDidFinishPurchase: TrÆ°á»›c đây là tùy chá»n trong v3, mặc định sẽ dismiss view sau khi mua hàng. Giá» bạn tá»± quyết định: tiếp tục flow hay gá»i view.dismiss().
  • flowViewDidFinishRestore: Bắt buá»™c, giống nhÆ° trong v3.
  • flowViewDidReceiveError: Thay thế paywallViewDidFailRendering và giá» cÅ©ng nhận các lá»—i view khác.

Hai thay đổi nhỠhơn:

  • setFlowsEventsObserver (và setOnboardingsEventsObserver) giá» chấp nhận null để gỡ bá» observer đã đặt trÆ°á»›c đó, giúp SDK không còn giữ tham chiếu đến nó nữa.
  • Callback tùy chá»n má»›i flowViewDidReceiveAnalyticEvent được dành riêng cho các sá»± kiện analytic tùy chỉnh từ má»™t flow. Hiện tại các flow chÆ°a phát ra sá»± kiện này đến code của bạn, nên bạn không cần implement nó.

v4 cÅ©ng bổ sung các tính năng bạn có thể chá»n dùng:

  • AdaptyUI().setObserverModeResolver(...) vá»›i má»™t AdaptyUIObserverModeResolver — xá»­ lý các giao dịch mua và khôi phục được khởi tạo từ flow khi SDK chạy ở chế Ä‘á»™ Observer. TrÆ°á»›c đây tính năng này chỉ có trong SDK iOS và Android gốc. Xem Hiển thị flow trong chế Ä‘á»™ Observer.
  • AdaptyUI().setSystemRequestsHandler(...) vá»›i má»™t AdaptyUISystemRequestsHandler — dành riêng cho các yêu cầu hệ thống từ flow (lá»i nhắc cấp quyá»n của hệ Ä‘iá»u hành và yêu cầu đánh giá App Store). Hiện tại flow chÆ°a kích hoạt các yêu cầu này, nên bạn không cần đăng ký handler.

Các API đã bị xóa

Các ký hiệu này đã bị deprecated trong 3.x và bị xóa trong v4:

setFallbackPaywalls → setFallback

- await Adapty().setFallbackPaywalls(assetId);
+ await Adapty().setFallback(assetId);

withIdfaCollectionDisabled → withAppleIdfaCollectionDisabled

  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
-   ..withIdfaCollectionDisabled(true),
+   ..withAppleIdfaCollectionDisabled(true),

Các thành phần đã bị xóa khác

  • AdaptyPurchaseResultSuccess.jwsTransaction: Sá»­ dụng appleJwsTransaction.
  • AdaptyUIFlowView.paywallVariationId: Sá»­ dụng variationId.
  • AdaptyUIObserver và AdaptyUI().setObserver(...): Sá»­ dụng AdaptyUIFlowsEventsObserver và setFlowsEventsObserver(...).

Thay đổi hành vi mặc định

Những thay đổi này không gây ra lỗi biên dịch, vì vậy hãy kiểm tra chúng ở runtime:

  • Mua hàng thành công: Trong v3, paywallViewDidFinishPurchase mặc định sẽ đóng view. Trong v4, flowViewDidFinishPurchase là bắt buá»™c và không có hành vi mặc định — bạn cần tá»± đóng view nếu muốn.
  • Nút back hệ thống Android: Nút này không còn đóng flow theo mặc định nữa. Hành Ä‘á»™ng sẽ được gá»­i đến flowViewDidPerformAction dÆ°á»›i dạng AndroidSystemBackAction — hãy xá»­ lý ở đó nếu muốn nút back đóng flow.
  • Mở URL: flowViewDidPerformAction mặc định hiện xá»­ lý OpenUrlAction bằng cách mở URL theo cách native (tôn trá»ng cài đặt trình duyệt in-app hoặc bên ngoài từ dashboard), ngoài việc đóng view khi nhận CloseAction. Ghi đè callback này nếu bạn muốn tá»± xá»­ lý URL.
  • Lá»—i view: flowViewDidReceiveError là bắt buá»™c, và việc đóng view tùy thuá»™c vào cách bạn triển khai. Nếu tích hợp v3 của bạn phụ thuá»™c vào việc view tá»± đóng khi có lá»—i render, hãy gá»i view.dismiss() trong callback này.
  • Vòng Ä‘á»i view: Äóng má»™t flow hoặc onboarding view sẽ giải phóng nó khá»i bá»™ nhá»›. View đã đóng không thể hiển thị lại — hãy tạo má»™t view má»›i thay thế.

Onboarding API đã bị deprecated

Onboarding API cÅ© đã bị deprecated trong v4.0, thay thế bằng Flow Builder. API này vẫn hoạt Ä‘á»™ng bình thÆ°á»ng, và IDE của bạn sẽ đánh dấu các ký hiệu deprecated thông qua annotation @Deprecated — không có cảnh báo nào ở runtime. Các ký hiệu này sẽ bị xóa trong bản phát hành tÆ°Æ¡ng lai, vì vậy hãy lên kế hoạch migrate các onboarding của bạn sang Flow Builder. Các ký hiệu không còn được há»— trợ: getOnboarding, getOnboardingForDefaultAudience, createOnboardingView, presentOnboardingView, dismissOnboardingView, setOnboardingsEventsObserver, AdaptyOnboarding, AdaptyUIOnboardingView, AdaptyUIOnboardingPlatformView, AdaptyUIOnboardingsEventsObserver, và các model state, input, analytics của onboarding.

ÿÿÿÿ