Adapty Unity SDK 4.1 là bản phát hành ổn định đầu tiên của dòng 4.x — 4.0 chỉ được phát hành dưới dạng beta, vì vậy nếu bạn đang dùng 3.x, hãy migrate thẳng lên 4.1. Hướng dẫn này bao gồm toàn bộ quá trình migration: các flow được giới thiệu trong 4.0 và các thay đổi của 4.1 bổ sung thêm.

Dòng 4.x giới thiệu flows và đổi tên các API paywall cho phù hợp. Các API mới hoạt động với flows, đồng thời vẫn tương thích với các paywall từ builder cũ — không cần thay đổi cấu hình nào trên Adapty Dashboard. Ngoài ra, 4.1 đổi tên các API attribution bên ngoài, chuyển Adapty Attribution sang dạng opt-in, bổ sung một phương thức listener bắt buộc, và thay đổi định dạng file fallback.

Tham khảo nhanh

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, với phương thức OnReceivePromotedPurchase bắt buộc mới
AdaptyOnboardingsEventsListener	IAdaptyOnboardingsEventsListener
PaywallViewDidPerformAction, PaywallViewDidAppear, và các callback PaywallView... khác	FlowViewDidPerformAction, FlowViewDidAppear, và các callback FlowView... khác
PaywallViewDidFailRendering	FlowViewDidReceiveError
Adapty.UpdateAttribution(data, source, ...) với nguồn kiểu string	Adapty.UpdateExternalAttribution(jsonString, provider, ...) với AdaptyExternalAttributionProvider
AdaptyProfile.AppliedAttributionSources kiểu IReadOnlyList<string>	AdaptyProfile.AppliedExternalAttributionProviders kiểu IReadOnlyList<AdaptyExternalAttributionProvider>
Attribution của Adapty được bật tự động	tắt theo mặc định — bật bằng Builder.SetAdaptyAttributionEnabled(true)
File dự phòng đã tải xuống cho phiên bản 3.x	định dạng file dự phòng mới — tải xuống lại file
Adapty.SetFallbackPaywalls(...) (đã lỗi thời ở v3)	đã bị xóa — dùng Adapty.SetFallback(fileName, ...)
Builder.SetIDFACollectionDisabled(...) (đã lỗi thời ở v3)	đã bị xóa — dùng Builder.SetAppleIDFACollectionDisabled(...)
paywall.Products (danh sách AdaptyProductReference)	đã bị xóa — dùng ProductIdentifiers hoặc VendorProductIds, hoặc gọi GetPaywallProducts(flow) để lấy đầy đủ sản phẩm
AdaptyProductReference	đã bị xóa khỏi kiểu public — xem Mô hình dữ liệu
paywall.RemoteConfigString	đã bị xóa — dùng flow.RemoteConfig?.Data

AdaptyPaywallProduct giữ nguyên tên — các sản phẩm vẫn thuộc về một flow, và GetPaywallProducts cũng giữ nguyên tên, nay nhận một AdaptyFlow. Các phương thức GetFlow và GetFlowForDefaultAudience không còn nhận tham số locale nữa. Các API mua hàng và hồ sơ người dùng (MakePurchase, RestorePurchases, GetProfile, Identify, UpdateProfile) không thay đổi. SetFallback giữ nguyên chữ ký, nhưng file mà nó đọc phải được tải xuống lại — xem Fallback files. Các phương thức onboarding vẫn hoạt động nhưng đã bị deprecated — xem Onboarding API deprecation. Một số hành vi mặc định đã thay đổi — xem Default behavior changes.

Cài đặt

Để cài đặt SDK 4.1 qua Unity Package Manager, thêm thẻ phiên bản vào URL Git:

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

Nếu cài đặt qua Unity package, tải adapty-unity-plugin-4.1.0.unitypackage từ bản phát hành 4.1.0. Xem Cài đặt Adapty SDK để biết hướng dẫn thiết lập đầy đủ.

Hai thay đổi trong thiết lập build đi kèm với phiên bản 4.x:

• Các dependency iOS chuyển sang Swift Package Manager. SDK Adapty iOS gốc được khai báo là một remote Swift package thay vì CocoaPods pod. Hãy cập nhật External Dependency Manager lên 1.2.188 trở lên — các phiên bản cũ hơn không hỗ trợ dependency Swift Package Manager. Các bước CocoaPods (iOS Resolver -> Install Cocoapods, mở Unity-iPhone.xcworkspace) không còn áp dụng nữa. Để build cho iOS, bây giờ cần Xcode 26 trở lên, vì Swift package được build bằng Swift tools 6.2.
• Deployment target iOS phải là 15.0 trở lên. Một build validator mới trong Unity Editor sẽ dừng quá trình build iOS nếu target thấp hơn mức này.

Các SDK gốc bên dưới được nâng lên phiên bản 4.x trên cả hai nền tảng và được phân giải tự động — không cần thay đổi build nào khác.

Lấy flows

GetPaywall → GetFlow

Kiểu trả về thay đổi từ AdaptyPaywall sang AdaptyFlow, và tham số locale bị loại bỏ — khi bạn render một flow, locale sẽ được tự động xác định; đối với các paywall tùy chỉnh, tất cả các locale được trả về trong 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 được đổi tên theo cách tương tự:

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

GetPaywallProducts(paywall) → GetPaywallProducts(flow)

GetPaywallProducts giữ nguyên tên nhưng giờ nhận vào một AdaptyFlow:

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

Mô hình dữ liệu

GetFlow trả về một AdaptyFlow thay vì AdaptyPaywall, và cấu trúc của đối tượng đã thay đổi:

Thuộc tính v3 AdaptyPaywall	Thuộc tính v4 AdaptyFlow	Hành động
RemoteConfig (đơn lẻ, nullable)	RemoteConfigs (danh sách)	Một flow chứa một remote config cho mỗi ngôn ngữ đã cấu hình. Đọc mục phù hợp với người dùng từ flow.RemoteConfigs. Shortcut flow.RemoteConfig trả về mục đầu tiên.
(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. Các phương thức web paywall nhận vào AdaptyFlowPaywall — xem Phương thức web paywall.
ProductIdentifiers, VendorProductIds	giữ nguyên	Trên AdaptyFlow, các thuộc tính này tổng hợp sản phẩm từ tất cả các biến thể paywall. Mỗi biến thể cũng có ProductIdentifiers và VendorProductIds riêng. Để lấy sản phẩm, tiếp tục gọi GetPaywallProducts(flow).
HasViewConfiguration	đã xóa	Xóa mọi kiểm tra HasViewConfiguration trong code của bạn — CreateFlowView sẽ trả về lỗi thay thế (xem Hiển thị flow).
Products (danh sách AdaptyProductReference)	đã xóa	AdaptyProductReference không còn là public, cùng với đó là các giá trị PromotionalOfferId, WinBackOfferId và AndroidOfferId mà nó mang theo. Sử dụng ProductIdentifiers — danh sách AdaptyProductIdentifier với VendorProductId và BasePlanId chỉ dành cho Android (tương đương AndroidBasePlanId của v3) — hoặc gọi GetPaywallProducts(flow) khi bạn cần các đối tượng AdaptyPaywallProduct đầy đủ với giá và ưu đãi.
RemoteConfigString	đã xóa	Đọc chuỗi trực tiếp từ remote config: flow.RemoteConfig?.Data, hoặc mục tương ứng trong flow.RemoteConfigs.
(mới)	FlowVersionId (nullable)	Định danh phiên bản của flow, hoặc null khi không có.

AdaptyPaywallProduct có thêm một trường: FlowProductId, định danh sản phẩm trong flow, có giá trị null đối với các sản phẩm không thuộc flow nào.

Các phương thức web paywall

OpenWebPaywall và CreateWebPaywallUrl giữ nguyên tên, nhưng tham số paywall giờ nhận một AdaptyFlowPaywall — một trong các biến thể trong flow.Paywalls. Bạn vẫn có thể truyền một AdaptyPaywallProduct thay thế:

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

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 nhận theo cùng một biến thể, nên 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 trên dashboard.

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

Cũng như trong 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 Adapty render — Adapty sẽ tự động theo dõi các lượt xem đó.

Hiển thị flow

CreatePaywallView → CreateFlowView

Đổi tên factory method và truyền vào AdaptyFlow. Kiểu view trả về được đổi tên từ AdaptyUIPaywallView thành AdaptyUIFlowView, nhưng các phương thức của nó (Present, Dismiss) không thay đổi, và đối tượng tham số tùy chọn vẫn giữ nguyên các trường (LoadTimeout, PreloadProducts, CustomTags, CustomTimers, CustomAssets, ProductPurchaseParameters) dưới tên mới AdaptyUICreateFlowViewParameters, cùng với hai trường mới — Locale và EnableSafeAreaPaddings:

- 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 trả về lỗi nếu flow không có view được cấu hình — điều này thay thế kiểm tra HasViewConfiguration trong v3:

- 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 */ });
+ });

Padding vùng an toàn trên Android

AdaptyUICreateFlowViewParameters có thêm EnableSafeAreaPaddings, dùng để kiểm soát padding vùng an toàn trên Android tại runtime. Tùy chọn này bị bỏ qua trên iOS và mặc định là true:

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

Xử lý sự kiện

Các interface listener hiện tuân theo quy ước tiền tố I của C#, và không còn giữ các alias cũ nữa — hãy đổi tên AdaptyEventListener thành IAdaptyEventListener và AdaptyOnboardingsEventsListener thành IAdaptyOnboardingsEventsListener ở những nơi bạn triển khai chúng.

Trình lắng nghe sự kiện flow được đổi tên từ AdaptyPaywallsEventsListener thành IAdaptyFlowsEventsListener, phương thức đăng ký từ SetPaywallsEventsListener thành SetFlowsEventsListener, và các callback thay đổi tiền tố PaywallView thành FlowView. Phần thân của các handler hiện có không cần thay đổi code — chỉ cần đổi tên interface và các phương thức:

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

Một callback được đổi tên: PaywallViewDidFailRendering thành FlowViewDidReceiveError. Callback này được kích hoạt cho các lỗi render như trước, cộng thêm các lỗi runtime không liên quan đến mua hàng:

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

Xem Xử lý sự kiện flow & paywall để biết danh sách đầy đủ các callback.

Phương thức bắt buộc mới: OnReceivePromotedPurchase

Bắt đầu từ SDK phiên bản 4.1, IAdaptyEventListener có thêm một phương thức mới, do đó mọi class implement nó sẽ không thể biên dịch cho đến khi bạn thêm:

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) => { /* ... */ });
}

Phương thức này dành cho in-app purchase được quảng bá trên App Store và không bao giờ được gọi trên Android. Đừng để thân hàm trống: trên iOS 16.4 trở lên, SDK chuyển giao giao dịch mua tại đây và chờ bạn hoàn tất, nên nếu thân hàm trống sẽ làm mất giao dịch mà người dùng đã bắt đầu. Các phiên bản trước đó tự động hoàn tất các giao dịch như vậy. Xem In-app purchase được quảng bá từ App Store.

API mới

• Adapty.SetObserverModeResolver(...) với IAdaptyUIObserverModeResolver — 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ỉ khả dụng trong SDK iOS và Android gốc. Xem Hiển thị flow trong chế độ Observer.
• Adapty.SetSystemRequestsHandler(...) với IAdaptyUISystemRequestsHandler — dành cho các yêu cầu hệ thống từ flow: lời nhắc cấp quyền của OS (FlowViewDidAskPermission) và yêu cầu đánh giá ứng dụng (FlowViewDidRequestAppReview). Hiện tại flow chưa kích hoạt các yêu cầu này, nên bạn chưa cần đăng ký handler.
• AdaptyUICreateFlowViewParameters.Locale (đặt bằng SetLocale) — hiển thị flow hoặc paywall với một bản địa hóa Builder cụ thể thay vì bản mặc định của flow. Flow được bản địa hóa khi view của nó được tạo, vì vậy đây là nơi duy nhất để chọn bản địa hóa, và view được tạo sẽ báo cáo bản địa hóa mà nó được xây dựng bằng thuộc tính view.Locale. Xem Sử dụng bản địa hóa và mã locale.
• Callback FlowViewDidReceiveAnalyticEvent mới trên IAdaptyFlowsEventsListener báo cáo các sự kiện analytics từ flow, bắt đầu bằng sự kiện xem màn hình cho mỗi màn hình người dùng mở. Xem Theo dõi lượt xem màn hình flow.
• AdaptyUI.OpenUrl(url, openIn, ...) và AdaptyUI.RequestAppReview(...) — xử lý gốc cho các hành động open_url và yêu cầu đánh giá ứng dụng. Gọi OpenUrl từ FlowViewDidPerformAction để giữ nguyên hành vi URL mặc định; RequestAppReview hỗ trợ lời nhắc đánh giá ứng dụng mặc định, mà hiện tại flow chưa kích hoạt.

Đổi tên API attribution từ nguồn ngoài

Bắt đầu từ SDK phiên bản 4.1, các API dùng để truyền dữ liệu attribution từ nhà cung cấp bên ngoài (Adjust, AppsFlyer, Branch, Tenjin hoặc nguồn tùy chỉnh) được đổi tên để khớp với các native SDK, và tham số nhà cung cấp chuyển từ kiểu string sang kiểu type. Không có alias deprecated nào, vì vậy các đoạn code hiện tại sẽ không biên dịch được cho đến khi bạn cập nhật chúng:

Trước 4.1	4.1
Adapty.UpdateAttribution(data, source, ...)	Adapty.UpdateExternalAttribution(jsonString, provider, ...)
source là string	provider là AdaptyExternalAttributionProvider
AdaptyProfile.AppliedAttributionSources là IReadOnlyList<string>	AdaptyProfile.AppliedExternalAttributionProviders là IReadOnlyList<AdaptyExternalAttributionProvider>

Chỉ đổi tên phương thức thôi chưa đủ — hãy đổi luôn đối số provider trong cùng một lần chỉnh sửa:

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

AdaptyExternalAttributionProvider chứa định danh mà backend dùng để nhận biết nhà cung cấp, với sáu instance dùng chung: AppleAds (apple_search_ads), Adjust, Appsflyer, Branch, Tenjin, và Custom. Đối với nhà cung cấp mà Adapty bổ sung sau lần phát hành SDK này, hãy khởi tạo từ định danh của nó — new AdaptyExternalAttributionProvider("your_provider") — và dữ liệu sẽ được gửi đến backend nguyên vẹn. Khoảng trắng ở đầu và cuối sẽ được tự động loại bỏ.

Dữ liệu attribution được truyền vào dưới dạng chuỗi JSON đã được serialize. Nếu bạn đang giữ dữ liệu dưới dạng dictionary, hãy serialize trước:

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

Về phía hồ sơ người dùng, đọc các provider đã được áp dụng thông qua kiểu mới:

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

Adapty Attribution bị tắt theo mặc định

Ở các phiên bản trước, SDK tự động ghi nhận lượt cài đặt cho Adapty Attribution. Kể từ SDK phiên bản 4.1, tính năng này bị tắt theo mặc định: SDK không ghi nhận lượt cài đặt, các callback listener OnInstallationDetailsSuccess và OnInstallationDetailsFail sẽ không bao giờ được gọi, và GetCurrentInstallationStatus trả về trạng thái NotAvailable.

Nếu bạn sử dụng Adapty Attribution, hãy bật tính năng này khi khởi tạo SDK:

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

Nếu bạn không sử dụng Adapty Attribution, không cần thay đổi gì.

Tệp dự phòng

Định dạng tệp dự phòng đã thay đổi trong SDK 4.1. Hãy tải lại tệp dự phòng cho iOS và Android từ Placements > Fallbacks và thay thế các tệp hiện có trong Assets/StreamingAssets, dù bạn đã tải chúng cho phiên bản trước đó.

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 tại runtime:

• Hoàn tất mua hàng: Ở v3, view tự động đóng sau khi mua thành công. Ở v4, flow vẫn mở sau khi mua hàng hoặc xảy ra lỗi cho đến khi bạn đóng nó — SDK không áp dụng hành vi mặc định nào. Hãy tự gọi view.Dismiss(...) trong FlowViewDidFinishPurchase khi người dùng có quyền truy cập.
• Nút back trên Android: Nút back hệ thống (hoặc thao tác vuốt back) được chuyển đến FlowViewDidPerformAction dưới dạng action SystemBack và không còn tự đóng flow nữa — giống với iOS, nơi flow không thể bị đóng bằng thao tác hệ thống. Hãy cung cấp cho người dùng cách thoát rõ ràng (nút Close hoặc action on_device_back), hoặc tự đóng view khi xử lý action đó.
• View chỉ dùng một lần: Sau khi gọi Dismiss, view sẽ bị hủy. Gọi lại CreateFlowView nếu muốn hiển thị flow thêm lần nữa.
• Giao dịch ở Observer mode: ReportTransaction không còn trả về lỗi giải mã khi thành công nữa — ở v3, response thành công bị phân tích sai, khiến mọi báo cáo thành công đều kết thúc với lỗi.

Ngừng hỗ trợ Onboarding API

Onboarding API cũ đã bị ngừng hỗ trợ trong v4, thay thế bằng Flow & Paywall Builder. API này vẫn hoạt động, nhưng sẽ bị xóa trong một phiên bản tương lai, vì vậy hãy lên kế hoạch migrate các onboarding của bạn sang Flow & Paywall Builder.

Các ký hiệu đã ngừng hỗ trợ: GetOnboarding, GetOnboardingForDefaultAudience, AdaptyUI.CreateOnboardingView, AdaptyUI.PresentOnboardingView, AdaptyUI.DismissOnboardingView, và Adapty.SetOnboardingsEventsListener.