Migrate Adapty React Native SDK sang v4.1

Adapty React Native SDK 4.1 thay đổi cách bật Adapty Attribution, đổi tên các API attribution bên ngoài, và thay đổi định dạng file dự phòng. SDK cũng cho phép ứng dụng của bạn tiếp quản các in-app purchase được quảng bá trên App Store và khôi phục cờ hasViewConfiguration trên AdaptyFlow.

Nếu bạn vẫn đang dùng 3.x, hãy bắt đầu với Migrate sang v4.0 rồi làm theo hướng dẫn này.

Tham khảo nhanh

Cài đặt

Cập nhật gói react-native-adapty:

npm install react-native-adapty@latest
# or
yarn add react-native-adapty@latest

Yêu cầu runtime không thay đổi so với 4.0: iOS 15.0 và React Native 0.75. Xem Cài đặt Adapty SDK để biết hướng dẫn cài đặt đầy đủ.

4.1 cũng hỗ trợ tích hợp SPM của React Native, thay thế CocoaPods cho dự án iOS của bạn và yêu cầu React Native 0.87 trở lên. Tính năng này chỉ áp dụng cho các dự án React Native thuần túy, CocoaPods vẫn là mặc định, và việc chuyển đổi là tùy chọn — xem Thiết lập dự án iOS của bạn. Nếu ứng dụng của bạn sử dụng Kids Mode, mỗi trình quản lý gói sẽ áp dụng theo cách khác nhau.

⚠️ Adapty Attribution mặc định bị tắt

Trong phiên bản 4.0 trở về trước, SDK tự động đăng ký lượt cài đặt cho Adapty Attribution. Bắt đầu từ 4.1, tính năng này bị tắt theo mặc định: SDK không đăng ký lượt cài đặt, các sự kiện 'onInstallationDetailsSuccess' và 'onInstallationDetailsFail' sẽ không bao giờ được kích hoạt, và getCurrentInstallationStatus trả về trạng thái not_available.

Nếu bạn sử dụng Adapty Attribution, hãy bật tính năng này khi kích hoạt SDK:

  adapty.activate('YOUR_PUBLIC_SDK_KEY', {
+   adaptyAttributionEnabled: true,
  });

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

Đổi tên các API attribution từ bên ngoài

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 tùy chỉnh) đã được đổi tên để phù hợp với các SDK gốc.

updateAttribution → updateExternalAttribution

Phương thức được đổi tên và tham số thứ hai được đổi từ source thành provider. Dữ liệu attribution vẫn là một plain object:

- await adapty.updateAttribution(attribution, 'adjust');
+ await adapty.updateExternalAttribution(attribution, 'adjust');

AttributionSource → AdaptyExternalAttributionProvider

Kiểu provider được đổi tên. Nó vẫn là một union mở — các giá trị được định sẵn là 'apple_search_ads', 'adjust', 'appsflyer', 'branch', 'tenjin', và 'custom' mới cho các provider mà Adapty không tích hợp trực tiếp. Bất kỳ chuỗi nào khác cũng được chấp nhận, vì vậy một provider mà Adapty thêm sau này sẽ hoạt động mà không cần cập nhật SDK:

- import type { AttributionSource } from 'react-native-adapty';
+ import type { AdaptyExternalAttributionProvider } from 'react-native-adapty';

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

Thuộc tính của hồ sơ người dùng liệt kê các nhà cung cấp attribution đã được áp dụng cho hồ sơ được đổi tên, và kiểu phần tử của nó cũng thay đổi tương ứng:

- if (profile.appliedAttributionSources?.includes('apple_search_ads')) {
+ if (profile.appliedExternalAttributionProviders?.includes('apple_search_ads')) {
      // Apple Ads attribution has been applied
  }

Code đọc thuộc tính này cần được cập nhật — xem Hiển thị paywall nhắm mục tiêu Apple Ads.

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 từ Placements > Fallbacks và đóng gói vào ứng dụng, kể cả khi bạn đã tải tệp cho phiên bản 4.0 trước đó.

hasViewConfiguration được khôi phục trong AdaptyFlow

Phiên bản 4.0 đã loại bỏ hasViewConfiguration khi AdaptyPaywall được đổi tên thành AdaptyFlow. Phiên bản 4.1 khôi phục lại thuộc tính này trên AdaptyFlow, vì vậy một nhánh hasViewConfiguration từ thời v3 sẽ hoạt động trở lại sau khi bạn đổi tên hàm và đối tượng mà nó đọc:

- if (paywall.hasViewConfiguration) {
-   const view = await createPaywallView(paywall);
+ if (flow.hasViewConfiguration) {
+   const view = await createFlowView(flow);
    await view.present();
  }

Trên phiên bản 4.0, khi flag này không có, createFlowView sẽ ném ra AdaptyError cho một flow không có cấu hình view. Điều này vẫn đúng trên 4.1 — flag này là một lựa chọn thay thế cho việc bắt lỗi, không phải thay thế hoàn toàn. Xem Lấy cấu hình view.

In-app purchase được quảng bá trên App Store

Ở phiên bản 4.0, một in-app purchase được quảng bá trên trang sản phẩm App Store của bạn sẽ tự động hoàn tất và Adapty ghi lại giao dịch như bình thường, nhưng ứng dụng của bạn không có cách nào để chặn nó. Phiên bản 4.1 bổ sung hook đó, vì vậy đây là tính năng mới chứ không phải bước migration: nếu không có code riêng của bạn, SDK vẫn tự động hoàn tất các purchase được quảng bá.

Tự viết code để kiểm soát quá trình hoàn tất giao dịch — ví dụ để hiển thị một màn hình trước. Đăng ký listener cho sự kiện 'onPromotedPurchaseReceived' mới, và hoàn tất giao dịch bằng adapty.makePromotedPurchase. Khi listener đó được đăng ký, SDK sẽ ngừng tự động hoàn tất các giao dịch được đề xuất thay bạn.