Cài đặt & cấu hình Adapty React Native SDK trong dự án Expo

Adapty SDK bao gồm hai module chính để tích hợp liền mạch vào ứng dụng React Native của bạn:

• Core Adapty: Module này bắt buộc phải có để Adapty hoạt động đúng trong ứng dụng của bạn.
• AdaptyUI: Module này cần thiết nếu bạn sử dụng Adapty Paywall Builder, công cụ no-code thân thiện giúp tạo paywall đa nền tảng dễ dàng. AdaptyUI được kích hoạt tự động cùng với module core.

Nếu bạn muốn xem hướng dẫn đầy đủ về cách triển khai IAP trong ứng dụng React Native, hãy xem tại đây.

Để xem hướng dẫn triển khai đầy đủ, bạn có thể xem video sau:

Yêu cầu

Adapty React Native SDK yêu cầu iOS 15.0+.

Để build cho iOS cần có Swift 6.0 trở lên. Kids Mode yêu cầu Swift 6.1 trở lên.

Cài đặt Adapty SDK

1. Cài đặt Adapty SDK (thao tác này cũng tự động cài @adapty/core):

   npx expo install react-native-adapty
   npx expo prebuild

2. Build ứng dụng cho môi trường phát triển bằng EAS hoặc local build:

# For iOS
eas build --profile development --platform ios

# For Android
eas build --profile development --platform android

# For iOS
npx expo run:ios

# For Android
npx expo run:android

3. Khởi động dev server:

   npx expo start --dev-client

Adapty SDK 4.0 (beta): bật Swift Package Manager

React Native SDK 4.0 — bổ sung hỗ trợ Flow Builder — là phiên bản pre-release yêu cầu React Native 0.75 trở lên. Cài đặt đúng phiên bản (npm không tự phân giải pre-release qua caret/tilde):

npx expo install react-native-adapty@4.0.0-beta.1

v4 kéo các iOS SDK native (Adapty, AdaptyUI, AdaptyPlugin) qua Swift Package Manager thay vì CocoaPods sub-dependencies (spec repo của CocoaPods sẽ chuyển sang chế độ read-only vào tháng 12 năm 2026). SPM yêu cầu dynamic frameworks, và trong Expo bạn bật tính năng này bằng plugin expo-build-properties. Thêm vào app.json (hoặc app.config.js):

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "dynamic"
          }
        }
      ]
    ]
  }
}

Sau đó cài đặt plugin và tạo lại native project:

npx expo install expo-build-properties
npx expo prebuild --clean

Xem Hướng dẫn migration Adapty React Native SDK lên v4 để biết đầy đủ các bước migration.

Kích hoạt module Adapty của Adapty SDK

Để lấy Public SDK Key:

1. Truy cập Adapty Dashboard và điều hướng đến App settings → General.
2. Trong phần Api keys, sao chép Public SDK Key (KHÔNG phải Secret Key).
3. Thay thế "YOUR_PUBLIC_SDK_KEY" trong code.

Hoặc lấy theo cách lập trình, sử dụng Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

Hoặc, trực tiếp:

npx adapty auth login
adapty apps list

• Đảm bảo bạn sử dụng Public SDK key để khởi tạo Adapty, Secret key chỉ nên dùng cho server-side API.
• SDK keys là duy nhất cho mỗi ứng dụng, vì vậy nếu bạn có nhiều ứng dụng, hãy đảm bảo chọn đúng key.

Sao chép đoạn code sau vào App.tsx để kích hoạt Adapty:

adapty.activate('YOUR_PUBLIC_SDK_KEY');

Bây giờ hãy thiết lập paywall trong ứng dụng của bạn:

• Nếu bạn dùng Adapty Paywall Builder, hãy xem hướng dẫn nhanh về Paywall Builder.
• Nếu bạn tự xây dựng giao diện paywall, hãy xem hướng dẫn nhanh cho paywall tùy chỉnh.

Kích hoạt module AdaptyUI của Adapty SDK

Nếu bạn có kế hoạch sử dụng Paywall Builder, bạn cần module AdaptyUI. Module này sẽ được kích hoạt tự động khi bạn kích hoạt module chính; bạn không cần làm gì thêm.

Cài đặt tùy chọn

Ghi log

Thiết lập hệ thống ghi log

Adapty ghi lại các lỗi và thông tin quan trọng để giúp bạn hiểu chuyện gì đang xảy ra. Các mức độ log hiện có như sau:

// Set log level before activation
// 'verbose' is recommended for development and the first production release
adapty.setLogLevel('verbose');

// Or set it during configuration
adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  logLevel: 'verbose',
});

Chính sách dữ liệu

Adapty không lưu trữ dữ liệu cá nhân của người dùng trừ khi bạn chủ động gửi lên, nhưng bạn có thể triển khai thêm các chính sách bảo mật dữ liệu để tuân thủ quy định của cửa hàng hoặc từng quốc gia.

Tắt thu thập và chia sẻ địa chỉ IP

Khi kích hoạt module Adapty, đặt ipAddressCollectionDisabled thành true để tắt tính năng thu thập và chia sẻ địa chỉ IP của người dùng. Giá trị mặc định là false. Sử dụng tham số này để tăng cường quyền riêng tư cho người dùng, tuân thủ các quy định bảo vệ dữ liệu khu vực (như GDPR hoặc CCPA), hoặc giảm thu thập dữ liệu không cần thiết khi các tính năng dựa trên IP không được yêu cầu trong ứng dụng của bạn.

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

Vô hiệu hóa việc thu thập và chia sẻ advertising ID

Khi kích hoạt module Adapty, đặt ios.idfaCollectionDisabled (iOS) hoặc android.adIdCollectionDisabled (Android) thành true để tắt tính năng thu thập advertising identifier. Giá trị mặc định là false.

Sử dụng tham số này để tuân thủ chính sách của App Store/Play Store, tránh kích hoạt hộp thoại App Tracking Transparency, hoặc khi ứng dụng của bạn không cần attribution quảng cáo hay analytics dựa trên advertising ID.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ios: {
    idfaCollectionDisabled: true,
  },
  android: {
    adIdCollectionDisabled: true,
  },
});

Cấu hình bộ nhớ đệm media cho AdaptyUI

Theo mặc định, AdaptyUI lưu vào bộ nhớ đệm các tệp media (như hình ảnh và video) để cải thiện hiệu suất và giảm mức sử dụng mạng. Bạn có thể tùy chỉnh cài đặt bộ nhớ đệm bằng cách cung cấp cấu hình tùy chỉnh.

Sử dụng mediaCache để ghi đè các cài đặt bộ nhớ đệm mặc định:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  mediaCache: {
    memoryStorageTotalCostLimit: 200 * 1024 * 1024, // Optional: memory cache size in bytes
    memoryStorageCountLimit: 2147483647,            // Optional: max number of items in memory
    diskStorageSizeLimit: 200 * 1024 * 1024,       // Optional: disk cache size in bytes
  },
});

Bật mức độ truy cập cục bộ (Android)

Theo mặc định, mức độ truy cập cục bộ được bật trên iOS và tắt trên Android. Để bật tính năng này trên Android, hãy đặt localAccessLevelAllowed thành true:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  android: {
     localAccessLevelAllowed: true,
  },
});

Xóa dữ liệu khi khôi phục từ backup

Khi clearDataOnBackup được đặt thành true, SDK sẽ phát hiện khi ứng dụng được khôi phục từ bản backup iCloud và xóa toàn bộ dữ liệu SDK được lưu cục bộ, bao gồm thông tin hồ sơ người dùng được cache, thông tin sản phẩm và paywall. Sau đó SDK sẽ khởi tạo lại với trạng thái sạch. Giá trị mặc định là false.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
   ios: {
       clearDataOnBackup: true
   },
});

Mẹo cho môi trường phát triển

Thiết lập chế độ mock cho Expo Go / Expo Web

Expo Go và Expo Web không có quyền truy cập vào các native module của Adapty. Để tránh lỗi runtime trong khi vẫn có thể build và kiểm tra UI cũng như logic paywall của ứng dụng, Adapty cung cấp chế độ mock.

Theo mặc định, SDK tự động phát hiện môi trường Expo Go và web, rồi bật chế độ mock. Bạn không cần cấu hình gì thêm trừ khi muốn tùy chỉnh dữ liệu mock.

Khi chế độ mock đang hoạt động:

• Tất cả các phương thức Adapty đều trả về dữ liệu mock mà không thực hiện bất kỳ yêu cầu mạng nào đến máy chủ của Adapty.
• Theo mặc định, hồ sơ người dùng mock ban đầu không có gói đăng ký nào đang hoạt động.
• Theo mặc định, makePurchase(...) mô phỏng một giao dịch mua thành công và cấp quyền truy cập premium. Bạn có thể tùy chỉnh dữ liệu mock bằng mockConfig trong quá trình kích hoạt. Xem định dạng cấu hình và các tham số được hỗ trợ tại đây.

try {
  await adapty.activate('YOUR_PUBLIC_SDK_KEY', {
    mockConfig: {
      // Customize the initial mock profile (optional)
    },
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
}

Nếu bạn cần gọi các phương thức SDK trước khi kích hoạt (chẳng hạn như isActivated() hoặc setLogLevel()), hãy sử dụng enableMock() trước activate(). Nếu bridge đã được khởi tạo, phương thức này sẽ không làm gì cả.

adapty.enableMock(); // Optional: pass mockConfig to customize mock data

// Now you can call methods before activation

await adapty.activate('YOUR_PUBLIC_SDK_KEY');

Trì hoãn kích hoạt SDK cho mục đích phát triển

Adapty tải trước tất cả dữ liệu người dùng cần thiết khi khởi động SDK, giúp truy cập dữ liệu mới nhanh hơn.

Tuy nhiên, điều này có thể gây ra vấn đề trên iOS Simulator, vì simulator thường xuyên yêu cầu xác thực trong quá trình phát triển. Mặc dù Adapty không thể kiểm soát luồng xác thực StoreKit, nhưng có thể trì hoãn các yêu cầu mà SDK thực hiện để lấy dữ liệu người dùng mới.

Bằng cách bật thuộc tính __debugDeferActivation, lệnh gọi activate sẽ được giữ lại cho đến khi bạn thực hiện lệnh gọi Adapty SDK tiếp theo. Điều này giúp tránh các lần nhắc xác thực không cần thiết nếu không cần dùng đến. Cần lưu ý rằng tính năng này chỉ dành cho mục đích phát triển, vì nó không bao gồm tất cả các tình huống người dùng có thể xảy ra. Trong môi trường production, không nên trì hoãn việc kích hoạt, vì các thiết bị thực thường ghi nhớ dữ liệu xác thực và không liên tục yêu cầu nhập lại thông tin đăng nhập.

Dưới đây là cách sử dụng được khuyến nghị:

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __debugDeferActivation: isSimulator(), // 'isSimulator' from any 3rd party library
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

Khắc phục lỗi kích hoạt SDK trên Fast Refresh của React Native

Khi phát triển với Adapty SDK trong React Native, bạn có thể gặp lỗi: Adapty can only be activated once. Ensure that the SDK activation call is not made more than once. Điều này xảy ra vì tính năng fast refresh của React Native kích hoạt nhiều lần gọi activation trong quá trình phát triển. Để tránh điều này, hãy sử dụng tùy chọn __ignoreActivationOnFastRefresh với giá trị __DEV__ (cờ chế độ phát triển của React Native).

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __ignoreActivationOnFastRefresh: __DEV__,
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

Khắc phục sự cố

Lỗi phiên bản iOS tối thiểu

Khi build cho iOS, bạn có thể gặp lỗi về phiên bản iOS tối thiểu hoặc deployment target. Adapty yêu cầu iOS 15.0+.

Vì Expo tạo ra dự án iOS (bao gồm cả Podfile) trong quá trình expo prebuild, bạn không nên chỉnh sửa Podfile trực tiếp. Thay vào đó, hãy cấu hình deployment target thông qua config plugin expo-build-properties.

1. Cài đặt plugin:

   npx expo install expo-build-properties

2. Cập nhật cấu hình Expo (app.json hoặc app.config.js) để đặt iOS deployment target:

{
    "expo": {
        // ...other Expo config...
        "plugins": [
            [
                "expo-build-properties",
                {
                    "ios": {
                        // Adapty requires iOS 15.0+.
                        "deploymentTarget": "15.0"
                    }
                }
            ],
        ]
    }
}

3. Tạo lại native iOS project và build lại:

npx expo prebuild --clean
npx expo run:ios      # or `eas build -p ios` on your CI

Xung đột Android Auto Backup manifest

Khi sử dụng Expo với nhiều SDK cùng cấu hình Android Auto Backup (chẳng hạn như Adapty, AppsFlyer, hoặc expo-secure-store), bạn có thể gặp lỗi xung đột khi merge manifest.

Lỗi thường gặp trông như sau: Manifest merger failed : Attribute application@fullBackupContent value=(@xml/secure_store_backup_rules) from AndroidManifest.xml:24:248-306 is also present at [io.adapty:android-sdk:3.12.0] AndroidManifest.xml:9:18-70 value=(@xml/adapty_backup_rules). Để giải quyết xung đột này, bạn cần để plugin Adapty quản lý cấu hình Android backup. Nếu dự án của bạn cũng sử dụng expo-secure-store, hãy tắt thiết lập backup của nó để tránh bị trùng lặp.

Đây là cách cấu hình app.json của bạn:

{
  "expo": {
    "plugins": [
      ["react-native-adapty", { "replaceAndroidBackupConfig": true }],
      ["expo-secure-store", { "configureAndroidBackup": false }]
    ]
  }
}

Tùy chọn replaceAndroidBackupConfig mặc định là false. Khi được bật, nó cho phép plugin Adapty kiểm soát các quy tắc sao lưu Android. Thêm "configureAndroidBackup": false nếu bạn sử dụng expo-secure-store để tránh cảnh báo, vì cấu hình sao lưu của SecureStore sẽ được Adapty xử lý.