Install & configure Adapty React Native SDK in an Expo project

Hướng dẫn này đề cập đến việc cài đặt và cấu hình Adapty React Native SDK trong một dự án Expo.

Nếu bạn đang sử dụng React Native thuần (không có Expo), hãy làm theo hướng dẫn cài đặt React Native thay thế.

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.

Bạn muốn xem ví dụ thực tế về cách tích hợp Adapty SDK vào ứng dụng Expo? Hãy xem các ứng dụng mẫu của chúng tôi:

Expo dev build sample — đầy đủ chức năng bao gồm mua hàng thực tế và Paywall Builder
Expo Go & Web sample — kiểm thử với chế độ mock

Để 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.

Từ SDK v3.17, Adapty SDK sử dụng Google Play Billing Library v8.0.0 theo mặc định.

Cài đặt SDK là bước 5 trong quá trình thiết lập Adapty. Trước khi các giao dịch mua hàng hoạt động trong ứng dụng, bạn cần kết nối ứng dụng với các cửa hàng, sau đó tạo sản phẩm, paywall và placement trong Adapty Dashboard. Hướng dẫn quickstart sẽ hướng dẫn bạn qua tất cả các bước cần thiết.

Cài đặt Adapty SDK

Kể từ v4, Adapty React Native SDK không còn hỗ trợ cài đặt các thư viện native phụ thuộc qua CocoaPods. Nếu bạn cần v4 trở lên (dành cho Flow Builder), hãy làm theo hướng dẫn Adapty SDK 4.0: enable Swift Package Manager bên dưới.

Expo Dev Client (một bản build phát triển tùy chỉnh) là bắt buộc để sử dụng Adapty trong dự án Expo.

Expo Go không hỗ trợ các native module tùy chỉnh, vì vậy bạn chỉ có thể dùng nó với chế độ mock để phát triển UI/logic (không có giao dịch mua thật và không có AdaptyUI/Paywall Builder).

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
```
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

Khởi động dev server:
```
npx expo start --dev-client
```

Adapty SDK 4.0: bật Swift Package Manager

React Native SDK 4.0 — bổ sung hỗ trợ Flow Builder — yêu cầu React Native 0.75 trở lên. Cài đặt SDK:

npx expo install react-native-adapty@^4.0.0

v4 kéo các iOS SDK gốc (Adapty, AdaptyUI, AdaptyPlugin) thông qua Swift Package Manager thay vì CocoaPods sub-dependencies (Repo spec của CocoaPods sẽ chuyển sang chế độ chỉ đọc vào tháng 12 năm 2026). SPM yêu cầu dynamic frameworks, mà trong Expo bạn bật bằng plugin expo-build-properties. Thêm nó 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:

Truy cập Adapty Dashboard và điều hướng đến App settings → General.
Trong phần Api keys, sao chép Public SDK Key (KHÔNG phải Secret Key).
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');

Hãy đợi activate hoàn tất trước khi gọi bất kỳ phương thức nào khác của Adapty SDK. Xem Thứ tự gọi trong React Native SDK để biết toàn bộ trình tự.

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.

Để tránh lỗi kích hoạt trong môi trường phát triển, hãy xem các mẹo.

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:

Level	Description
`error`	Chỉ ghi lại các lỗi
`warn`	Ghi lại các lỗi và thông báo từ SDK không gây ra lỗi nghiêm trọng nhưng đáng chú ý
`info`	Ghi lại các lỗi, cảnh báo và nhiều thông báo thông tin khác
`verbose`	Ghi lại mọi thông tin bổ sung có thể hữu ích trong quá trình debug, chẳng hạn như lời gọi hàm, truy vấn API, v.v.
Bạn có thể đặt mức độ log trong ứng dụng trước hoặc trong quá trình cấu hình Adapty:

// 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.

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

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

Tham số	Bắt buộc	Mô tả
memoryStorageTotalCostLimit	tùy chọn	Tổng kích thước cache trong bộ nhớ tính bằng byte. Mặc định theo giá trị riêng của từng nền tảng.
memoryStorageCountLimit	tùy chọn	Giới hạn số lượng item trong bộ nhớ cache. Mặc định theo giá trị riêng của từng nền tảng.
diskStorageSizeLimit	tùy chọn	Giới hạn kích thước file trên đĩa tính bằng byte. Mặc định theo giá trị riêng của từng nền tảng.

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.

Chỉ có cache cục bộ của SDK bị xóa. Lịch sử giao dịch với Apple và dữ liệu người dùng trên máy chủ Adapty vẫn không thay đổi.

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.

Chế độ mock không phải là công cụ để kiểm tra giao dịch mua thực tế:

Nó không mở luồng mua hàng của App Store / Google Play và không tạo giao dịch thực.
Nó không hiển thị paywall/onboarding được tạo bằng Adapty Paywall Builder (AdaptyUI).
Các native module của Adapty bị bỏ qua hoàn toàn—ngay cả khi thiếu file native SDK trong Xcode/Android build hoặc API key không hợp lệ cũng sẽ không gây ra lỗi.

Để kiểm tra mua hàng thực và paywall của Paywall Builder, hãy sử dụng Expo Dev Client / production build—ở đó chế độ mock sẽ tự động bị tắt.

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.

Cài đặt plugin:
```
npx expo install expo-build-properties
```
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"
                    }
                }
            ],
        ]
    }
}

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ý.

Cài đặt này chỉ áp dụng các yêu cầu sao lưu cho Adapty, AppsFlyer và expo-secure-store. Nếu các thư viện khác trong dự án của bạn có quy tắc sao lưu tùy chỉnh, bạn sẽ cần tự cấu hình thủ công.