--- title: "Cài đặt & cấu hình Adapty SDK trong dự án React Native thuần" description: "Hướng dẫn từng bước cài đặt Adapty SDK trên React Native cho ứng dụng có tính năng đăng ký." --- :::important Hướng dẫn này chỉ áp dụng cho **dự án React Native thuần (không dùng Expo)**. Nếu bạn đang dùng **Expo**, hãy làm theo [hướng dẫn cài đặt cho Expo](sdk-installation-react-native-expo). ::: Adapty SDK bao gồm hai module chính để tích hợp 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](adapty-paywall-builder) — công cụ no-code thân thiện để 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. :::tip Muốn xem ví dụ thực tế về cách tích hợp Adapty SDK vào ứng dụng di động? Hãy xem [ứng dụng mẫu](https://github.com/adaptyteam/AdaptySDK-React-Native/tree/master/examples) của chúng tôi, minh họa toàn bộ quy trình thiết lập bao gồm hiển thị paywall, thực hiện mua hàng và các chức năng cơ bản khác. ::: ## Yêu cầu \{#requirements\} Adapty React Native SDK hỗ trợ iOS 13.0 trở lên, nhưng để sử dụng paywall được tạo trong [Adapty paywall builder](adapty-paywall-builder) thì cần iOS 15.0 trở lên. :::info Bắt đầu từ SDK v3.17, Adapty SDK sử dụng Google Play Billing Library v8.0.0 theo mặc định. ::: --- no_index: true --- import Callout from '../../../components/Callout.astro'; 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](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 \{#install-adapty-sdk\} [![Release](https://img.shields.io/github/v/release/adaptyteam/AdaptySDK-React-Native.svg?style=flat&logo=react)](https://github.com/adaptyteam/AdaptySDK-React-Native/releases) 1. Cài đặt Adapty SDK (lệnh này cũng tự động cài `@adapty/core`): ```sh showLineNumbers title="Shell" # using npm npm install react-native-adapty # or using yarn yarn add react-native-adapty ``` 2. Với iOS, cài đặt pods: ```sh showLineNumbers title="Shell" cd ios && pod install ```
Với Android, nếu phiên bản React Native của bạn cũ hơn 0.73.0 (nhấn để mở rộng) Cập nhật file `/android/build.gradle`. Đảm bảo có dependency `kotlin-gradle-plugin:1.8.0` hoặc phiên bản mới hơn: ```groovy showLineNumbers title="/android/build.gradle" ... buildscript { ... dependencies { ... classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0" } } ... ```
## Kích hoạt module Adapty của Adapty SDK \{#activate-adapty-module-of-adapty-sdk\} Để lấy **Public SDK Key**: 1. Vào Adapty Dashboard và điều hướng đến [**App settings → General**](https://app.adapty.io/settings/general). 2. Trong phần **Api keys**, sao chép **Public SDK Key** (KHÔNG phải Secret Key). 3. Thay `"YOUR_PUBLIC_SDK_KEY"` trong code. :::important - Đảm bảo bạn dùng **Public SDK key** để khởi tạo Adapty, còn **Secret key** chỉ dùng cho [server-side API](getting-started-with-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 chắc chắn chọn đúng key. ::: Sao chép đoạn code sau vào `App.tsx` để kích hoạt Adapty: ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY'); ``` :::important Hãy chờ `activate` hoàn thành 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](react-native-sdk-call-order) để 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](adapty-paywall-builder), làm theo [hướng dẫn nhanh về Paywall Builder](react-native-quickstart-paywalls). - Nếu bạn tự xây dựng giao diện paywall, xem [hướng dẫn nhanh cho paywall tùy chỉnh](react-native-quickstart-manual). :::tip Để tránh lỗi kích hoạt trong môi trường phát triển, hãy sử dụng [các mẹo sau](#development-environment-tips). ::: ## Kích hoạt module AdaptyUI của Adapty SDK \{#activate-adaptyui-module-of-adapty-sdk\} Nếu bạn dự định dùng [Paywall Builder](adapty-paywall-builder), bạn cần module AdaptyUI. Module này được kích hoạt tự động khi bạn kích hoạt module core; bạn không cần làm thêm gì nữa. ## Thiết lập tùy chọn \{#optional-setup\} ### Logging \{#logging\} #### Thiết lập hệ thống logging \{#set-up-the-logging-system\} Adapty ghi lại các lỗi và thông tin quan trọng để giúp bạn hiểu những gì đang xảy ra. Các cấp độ log hiện có: | Cấp độ | Mô tả | | ---------- | ------------------------------------------------------------ | | `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à các thông báo thông tin khác nhau | | `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 cấp độ log trong ứng dụng trước hoặc trong quá trình cấu hình Adapty: ```typescript showLineNumbers title="App.tsx" // 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 \{#data-policies\} Adapty không lưu trữ dữ liệu cá nhân của người dùng trừ khi bạn gửi thông tin đó một cách rõ ràng, nhưng bạn có thể triển khai các chính sách bảo mật dữ liệu bổ sung để tuân thủ các 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 \{#disable-ip-address-collection-and-sharing\} Khi kích hoạt module Adapty, đặt `ipAddressCollectionDisabled` thành `true` để tắt 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ư của người dùng, tuân thủ các quy định bảo vệ dữ liệu theo 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ần thiết cho ứng dụng của bạn. ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { ipAddressCollectionDisabled: true, }); ``` #### Tắt thu thập và chia sẻ advertising ID \{#disable-advertising-id-collection-and-sharing\} Khi kích hoạt module Adapty, đặt `ios.idfaCollectionDisabled` (iOS) hoặc `android.adIdCollectionDisabled` (Android) thành `true` để tắt thu thập các mã định danh quảng cáo. 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 lời nhắc App Tracking Transparency, hoặc nếu ứng dụng của bạn không cần attribution quảng cáo hay phân tích dựa trên advertising ID. ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { ios: { idfaCollectionDisabled: true, }, android: { adIdCollectionDisabled: true, }, }); ``` #### Thiết lập cấu hình bộ nhớ đệm media cho AdaptyUI \{#set-up-media-cache-configuration-for-adaptyui\} Theo mặc định, AdaptyUI lưu vào bộ nhớ đệm các media (như hình ảnh và video) để cải thiện hiệu suất và giảm 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. Dùng `mediaCache` để ghi đè cài đặt bộ nhớ đệm mặc định: ```typescript 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ố: | Tham số | Bắt buộc | Mô tả | |-----------|----------|-------------| | memoryStorageTotalCostLimit | tùy chọn | Tổng kích thước bộ nhớ đệm trong RAM tính bằng byte. Mặc định theo giá trị của từng nền tảng. | | memoryStorageCountLimit | tùy chọn | Giới hạn số lượng mục trong bộ nhớ đệm RAM. Mặc định theo giá trị 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ị của từng nền tảng. | ### Bật mức độ truy cập cục bộ (Android) \{#enable-local-access-levels-android\} Theo mặc định, [mức độ truy cập cục bộ](local-access-levels) được bật trên iOS và tắt trên Android. Để bật trên Android, đặt `localAccessLevelAllowed` thành `true`: ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { android: { localAccessLevelAllowed: true, }, }); ``` ### Xóa dữ liệu khi khôi phục backup \{#clear-data-on-backup-restore\} Khi `clearDataOnBackup` được đặt thành `true`, SDK phát hiện khi ứng dụng được khôi phục từ 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 đã cache, chi tiết sản phẩm và paywall. SDK sau đó khởi tạo với trạng thái sạch. Giá trị mặc định là `false`. :::note Chỉ bộ nhớ đệm 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 không bị thay đổi. ::: ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { ios: { clearDataOnBackup: true }, }); ``` ## Mẹo cho môi trường phát triển \{#development-environment-tips\} #### Trì hoãn kích hoạt SDK cho mục đích phát triển \{#delay-sdk-activation-for-development-purposes\} Adapty tải trước tất cả dữ liệu người dùng cần thiết khi kích hoạt 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 sự cố 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 do 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ời gọi activate sẽ được giữ lại cho đến khi bạn thực hiện lời gọi Adapty SDK tiếp theo. Điều này ngăn các lời nhắc xác thực không cần thiết nếu không cần thiết. 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 kích hoạt vì thiết bị thực thường nhớ dữ liệu xác thực và không liên tục yêu cầu thông tin đăng nhập. Đây là cách sử dụng được khuyến nghị: ```typescript showLineNumbers title="Typescript" 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 với Fast Refresh của React Native \{#troubleshoot-sdk-activation-errors-on-react-natives-fast-refresh\} 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.` Lỗi 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. Để ngăn điều này, sử dụng tùy chọn `__ignoreActivationOnFastRefresh` đặt thành `__DEV__` (cờ chế độ phát triển của React Native). ```typescript showLineNumbers title="Typescript" 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 } ``` #### Thiết lập chế độ mock để kiểm thử cục bộ \{#set-up-mock-mode-for-local-testing\} Để phát triển và kiểm thử cục bộ, bạn có thể bật chế độ mock để tránh cần tài khoản sandbox App Store/Google Play và tăng tốc độ lặp. Chế độ mock hoàn toàn bỏ qua các module native của Adapty và trả về dữ liệu mô phỏng. :::important Chế độ mock **không** phải là công cụ để kiểm thử mua hàng thực: - 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 module native của Adapty bị **bỏ qua hoàn toàn** — ngay cả khi thiếu file SDK native trong build Xcode/Android hay API key không hợp lệ cũng sẽ không gây ra lỗi. - Không có dữ liệu nào được gửi đến máy chủ của Adapty. Để kiểm thử mua hàng thực và paywall của Paywall Builder, hãy tắt chế độ mock và sử dụng tài khoản sandbox. ::: Để bật chế độ mock, đặt `enableMock` thành `true`: ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { enableMock: true, }); ``` Khi chế độ mock đang hoạt động: - Tất cả các phương thức Adapty trả về dữ liệu mock mà không thực hiện yêu cầu mạng đến máy chủ 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 lần 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 cách dùng `mockConfig` trong quá trình kích hoạt. Xem định dạng config và các tham số được hỗ trợ [tại đây](https://react-native.adapty.io/interfaces/adaptymockconfig). ```typescript showLineNumbers title="App.tsx" 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 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ả. ```typescript showLineNumbers title="App.tsx" adapty.enableMock(); // Optional: pass mockConfig to customize mock data // Now you can call methods before activation await adapty.activate('YOUR_PUBLIC_SDK_KEY'); ``` ## Xử lý sự cố \{#troubleshooting\} #### Lỗi phiên bản iOS tối thiểu \{#minimum-ios-version-error\} Nếu bạn gặp lỗi về phiên bản iOS tối thiểu, hãy cập nhật Podfile của bạn: ```diff -platform :ios, min_ios_version_supported +platform :ios, '13.0' # For core features only # OR +platform :ios, '15.0' # If using paywalls created in the paywall builder ``` #### Xung đột Android Auto Backup manifest \{#android-auto-backup-manifest-conflict\} Một số SDK (bao gồm Adapty) đi kèm với cấu hình Android Auto Backup riêng. Nếu bạn sử dụng nhiều SDK có định nghĩa backup rules, quá trình merge Android manifest có thể thất bại với lỗi liên quan đến `android:fullBackupContent`, `android:dataExtractionRules`, hoặc `android:allowBackup`. Triệu chứng lỗi thường gặp: `Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)` :::note Những thay đổi này cần được thực hiện trong thư mục platform Android của bạn (thường nằm trong thư mục `android/` của dự án). ::: Để khắc phục, bạn cần: - Yêu cầu manifest merger sử dụng các giá trị của ứng dụng cho các thuộc tính liên quan đến backup. - Tạo các file backup rule kết hợp rules của Adapty với rules từ các SDK khác. #### 1. Thêm namespace `tools` vào manifest \{#1-add-the-tools-namespace-to-your-manifest\} Trong file `AndroidManifest.xml`, hãy đảm bảo thẻ gốc `` có chứa tools: ```xml ... ``` #### 2. Ghi đè các thuộc tính backup trong `` \{#2-override-backup-attributes-in-application\} Trong cùng file `AndroidManifest.xml`, cập nhật thẻ `` để ứng dụng của bạn cung cấp các giá trị cuối cùng và yêu cầu manifest merger thay thế các giá trị từ thư viện: ```xml ... ``` Nếu có SDK nào cũng đặt `android:allowBackup`, hãy thêm nó vào `tools:replace`: ```xml tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules" ``` #### 3. Tạo các file backup rules đã merge \{#3-create-merged-backup-rules-files\} Tạo các file XML trong thư mục `res/xml/` của dự án Android, kết hợp rules của Adapty với rules từ các SDK khác. Android sử dụng các định dạng backup rule khác nhau tùy theo phiên bản OS, vì vậy việc tạo cả hai file đảm bảo tương thích với tất cả các phiên bản Android mà ứng dụng hỗ trợ. :::note Các ví dụ dưới đây sử dụng AppsFlyer làm SDK bên thứ ba mẫu. Hãy thay thế hoặc bổ sung rules cho các SDK khác mà bạn đang dùng trong ứng dụng. ::: **Dành cho Android 12 trở lên** (sử dụng định dạng data extraction rules mới): ```xml title="sample_data_extraction_rules.xml" ``` **Dành cho Android 11 trở xuống** (sử dụng định dạng full backup content cũ): ```xml title="sample_backup_rules.xml" #### Mua hàng thất bại sau khi quay lại từ ứng dụng khác trên Android \{#purchases-fail-after-returning-from-another-app-in-android\} Nếu Activity khởi động luồng mua hàng sử dụng `launchMode` không phải mặc định, Android có thể tạo lại hoặc tái sử dụng nó không đúng cách khi người dùng quay lại từ Google Play, ứng dụng ngân hàng hoặc trình duyệt. Điều này có thể khiến kết quả mua hàng bị mất hoặc bị coi là đã hủy. Để đảm bảo mua hàng hoạt động chính xác, chỉ sử dụng chế độ khởi động `standard` hoặc `singleTop` cho Activity khởi động luồng mua hàng và tránh các chế độ khác. Trong `AndroidManifest.xml`, đảm bảo Activity khởi động luồng mua hàng được đặt thành `standard` hoặc `singleTop`: ```xml ``` #### Lỗi build Swift 6 do Podfile ghi đè SWIFT_VERSION \{#swift-6-build-errors-caused-by-podfile-swift_version-override\} Khi build ứng dụng React Native cho iOS, bạn có thể thấy lỗi biên dịch Swift 6 trên các pod target của Adapty. Các triệu chứng điển hình bao gồm lỗi `@Sendable` không khớp trong `AdaptyUIBuilderLogic`, thiếu conformance `Sendable` trên các kiểu Adapty, hoặc lỗi actor isolation. Các pod Adapty khai báo `s.swift_version = '6.0'` và yêu cầu Swift 6 để build. Code ứng dụng của bạn vẫn có thể dùng Swift 5 — chỉ các pod target của Adapty (`Adapty`, `AdaptyUI`, `AdaptyUIBuilder`, `AdaptyLogger`, `AdaptyPlugin`) cần được build với Swift 6. Nguyên nhân phổ biến nhất là hook `post_install` trong `ios/Podfile` ghi đè `SWIFT_VERSION` cho mọi pod target: ```ruby showLineNumbers title="ios/Podfile" post_install do |installer| installer.pods_project.targets.each do |target| target.build_configurations.each do |config| config.build_settings['SWIFT_VERSION'] = '5.9' end end end ``` **Cách sửa**: Loại trừ các pod target của Adapty khỏi việc ghi đè: ```ruby showLineNumbers title="ios/Podfile" post_install do |installer| installer.pods_project.targets.each do |target| next if %w[Adapty AdaptyUI AdaptyUIBuilder AdaptyLogger AdaptyPlugin].include?(target.name) target.build_configurations.each do |config| config.build_settings['SWIFT_VERSION'] = '5.9' end end end ``` Sau đó chạy `pod install` từ thư mục `ios/` và build lại. Để xác minh, mở `ios/Pods/Pods.xcodeproj`, chọn pod target `Adapty` → **Build Settings** → **Swift Language Version**. Giá trị phải là **Swift 6**.