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

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 dùng để hiển thị các flow, ngoài ra còn hỗ trợ các paywall được tạo bằng builder cũ. AdaptyUI sẽ tự động được kích hoạt cùng với module core.

Yêu cầu

Phụ thuộc

Adapty SDK hoạt động với các phiên bản Google Play Billing Library sau trên Android:

Cài đặt Adapty SDK

Chúng tôi luôn khuyến nghị cài đặt phiên bản SDK mới nhất hiện có — phiên bản này bao gồm các bản sửa lỗi ổn định và cải tiến mới nhất.

Thêm package vào dự án của bạn:

# using npm
npm install react-native-adapty

# or using yarn
yarn add react-native-adapty

Thiết lập dự án iOS của bạn

Adapty phân phối các iOS SDK native (Adapty, AdaptyUI, AdaptyPlugin) dưới dạng Swift package — v4 đã ngừng hỗ trợ CocoaPods (kho spec của CocoaPods sẽ chuyển sang chế độ chỉ đọc vào tháng 12 năm 2026). Cả hai tùy chọn đều cài đặt các Swift package đó; điểm khác biệt nằm ở cách thức thực hiện việc cài đặt.

• CocoaPods (mặc định, SDK 4.0 trở lên): Dự án iOS của bạn vẫn giữ Podfile, và helper spm_dependency của React Native thêm các Swift package của Adapty vào Pods project. Swift package link động, vì vậy Podfile phải chuyển sang dynamic frameworks.
• Tích hợp SPM của React Native (SDK 4.1 trở lên): Dự án iOS của bạn bỏ CocoaPods, và React Native tự giải quyết các Swift package từ manifest Package.swift mà Adapty cung cấp. React Native đã thêm tích hợp này trong phiên bản 0.87 dưới dạng bản xem trước và chưa khuyến nghị dùng cho production.

use_frameworks! :linkage => :dynamic

cd ios && pod install --repo-update

cd ios && npx react-native spm

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 các paywall trong ứng dụng của bạn:

• Nếu bạn sử dụng Flow & Paywall Builder, hãy xem quickstart.
• Nếu bạn tự xây dựng giao diện paywall, hãy xem quickstart 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 Flow & 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 cốt lõi; bạn không cần thực hiện thêm bất kỳ thao tác nào khác.

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 khác để giúp bạn hiểu chuyện gì đang xảy ra. Các cấp độ ghi log hiện có như sau:

Bạn có thể thiết lập 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, nhưng bạn có thể áp dụng 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 theo khu vực (như GDPR hoặc CCPA), hoặc giảm thiểu việc 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,
});

Tắt tính năng 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 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 lời nhắc 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,
  },
});

Thiết lập cấu hình bộ nhớ đệm media cho AdaptyUI

Theo mặc định, AdaptyUI lưu vào bộ nhớ đệm các file media (như hình ảnh và video) để cải thiện hiệu suất và giảm lưu lượng mạng. Bạn có thể tùy chỉnh các 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 trữ cục bộ, bao gồm thông tin hồ sơ người dùng đã cache, chi tiết sản phẩm và các 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
   },
});

Bật Adapty Attribution

Nếu bạn sử dụng Adapty Attribution, hãy đặt adaptyAttributionEnabled thành true khi kích hoạt SDK. Giá trị mặc định là false: nếu không có tham số này, SDK sẽ không đăng ký lượt cài đặt cũng như không cung cấp thông tin chi tiết về cài đặt cho ứng dụng của bạn. Trong các phiên bản SDK dưới 4.1, Adapty Attribution được bật tự động.

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

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

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 ngay khi SDK được kích hoạt, 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 đề trong iOS simulator, nơi 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 SDK tiếp theo. Điều này giúp tránh các thông báo yêu cầu dữ liệu xác thực không cần thiết khi 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 phủ tất cả các tình huống người dùng tiềm năng. 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 thông tin đăng nhập.

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

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __debugDeferActivation: isSimulator(), // 'isSimulator' từ thư viện bên thứ ba bất kỳ
  });
} catch (error) {
  console.error('Không thể kích hoạt Adapty SDK:', error);
  // Xử lý lỗi phù hợp với ứng dụng của bạn
}

Khắc phục lỗi kích hoạt SDK khi sử dụng 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. Để ngăn chặn đ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
}

Thiết lập chế độ mock để kiểm tra cục bộ

Trong quá trình phát triển và kiểm tra cục bộ, bạn có thể bật chế độ mock để không cần tài khoản sandbox App Store/Google Play và tăng tốc quá trình lặp lại. Chế độ mock hoàn toàn bỏ qua các module gốc của Adapty và trả về dữ liệu giả lập.

Để bật chế độ mock, đặt enableMock thành true:

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

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

• Tất cả các phương thức của Adapty 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');

Xử lý sự cố

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

Nếu bạn gặp lỗi phiên bản iOS tối thiểu, hãy cập nhật Podfile:

-platform :ios, min_ios_version_supported
+platform :ios, '15.0'

Xung đột manifest Android Auto Backup

Một số SDK (bao gồm Adapty) có cấu hình Android Auto Backup riêng. Nếu bạn dùng nhiều SDK cùng đị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)

Để khắc phục, bạn cần:

• Yêu cầu manifest merger sử dụng 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

Trong file AndroidManifest.xml, đảm bảo thẻ root <manifest> có chứa tools:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. Ghi đè các thuộc tính backup trong <application>

Trong cùng file AndroidManifest.xml, cập nhật thẻ <application> để ứng dụng của bạn cung cấp giá trị cuối cùng và yêu cầu manifest merger thay thế các giá trị từ thư viện:

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

Nếu có SDK nào đó cũng đặt android:allowBackup, hãy thêm nó vào tools:replace:

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. Tạo các file backup rules đã gộp

Tạo các file XML trong thư mục res/xml/ của Android project, 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 hệ điều hành, 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ợ.

Dành cho Android 12 trở lên (sử dụng định dạng data extraction rules mới):

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

Dành cho Android 11 trở xuống (sử dụng định dạng full backup content cũ):

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    

Giao dịch mua thất bại sau khi quay lại từ ứng dụng khác trên Android

Nếu Activity khởi động flow 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ả giao dịch bị mất hoặc bị xử lý như đã hủy.

Để đảm bảo việc mua hàng hoạt động đúng, hãy chỉ sử dụng chế độ khởi chạy standard hoặc singleTop cho Activity khởi động flow mua hàng, và tránh các chế độ khác.

Trong AndroidManifest.xml, hãy đảm bảo Activity khởi động flow mua hàng được đặt thành standard hoặc singleTop:

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />

Lỗi phiên bản Kotlin Gradle plugin trên React Native dưới 0.73

Trên React Native phiên bản cũ hơn 0.73.0, Android build sẽ thất bại do phiên bản Kotlin Gradle plugin. Hãy cập nhật file /android/build.gradle. Đảm bảo có dependency kotlin-gradle-plugin:1.8.0 hoặc mới hơn:

...
buildscript {
  ...
  dependencies {
    ...
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0"
  }
}
...

Lỗi build Swift 6 do Podfile ghi đè SWIFT_VERSION

Khi build ứng dụng React Native cho iOS, bạn có thể gặp lỗi biên dịch Swift 6 trên các target pod của Adapty. Các triệu chứng điển hình bao gồm lỗi không khớp @Sendable trong AdaptyUIBuilderLogic, thiếu conformance Sendable trên các kiểu Adapty, hoặc lỗi actor isolation.

Các pods Adapty khai báo s.swift_version = '6.0' và yêu cầu Swift 6 để build. Code của ứng dụng bạn vẫn có thể dùng Swift 5 — chỉ các pod target của Adapty (Adapty, AdaptyUI, AdaptyUIBuilder, AdaptyLogger, AdaptyPlugin) mới cần build với Swift 6.

Nguyên nhân phổ biến nhất là một post_install hook trong ios/Podfile ghi đè SWIFT_VERSION cho mọi pod target:

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 khắc phục: Loại trừ các pod target của Adapty khỏi phần ghi đè:

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 nhận, mở ios/Pods/Pods.xcodeproj, chọn target pod Adapty → Build Settings → Swift Language Version. Giá trị phải là Swift 6.