# REACT-NATIVE - Adapty Documentation (Full Content)

This file contains the complete content of all documentation pages for this platform.

Locale: vi

Generated on: 2026-06-24T14:36:38.789Z
Total files: 44

---


# File: sdk-installation-react-native-expo
---

---
title: "Cài đặt & cấu hình Adapty React Native SDK trong dự án Expo"
description: "Hướng dẫn từng bước cài đặt Adapty React Native SDK trong dự án Expo cho ứng dụng dựa trên gói đăng ký."
---

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

Nếu bạn đang sử dụng **pure React Native (không dùng Expo)**, hãy làm theo [hướng dẫn cài đặt React Native](sdk-installation-react-native-pure) 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 để 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 với người dùng để dễ dàng tạo paywall đa nền tảng. AdaptyUI được kích hoạt tự động cùng với module core.

Nếu bạn cần hướng dẫn đầy đủ về cách triển khai IAP trong ứng dụng React Native, hãy xem [bài viết này](https://adapty.io/blog/react-native-in-app-purchases-tutorial/).

:::tip
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](https://github.com/adaptyteam/AdaptySDK-React-Native/tree/master/examples/FocusJournalExpo) cho đầy đủ chức năng bao gồm mua hàng thực và Paywall Builder
- [Expo Go & Web sample](https://github.com/adaptyteam/AdaptySDK-React-Native/tree/master/examples/ExpoGoWebMock) để kiểm thử với chế độ mock
:::

Để xem hướng dẫn triển khai đầy đủ, bạn cũng có thể xem video:
<div style={{ textAlign: 'center' }}>
<iframe width="560" height="315" src="https://www.youtube.com/embed/TtCJswpt2ms?si=FlFJGvpj-U33yoNK" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share; fullscreen" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div>

## Yêu cầu \{#requirements\}

Adapty React Native SDK hỗ trợ iOS 13.0 trở lên, nhưng để sử dụng paywall tạo trong [Adapty paywall builder](adapty-paywall-builder) cần iOS 15.0 trở lên.

:::info
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';

<Callout type="info">
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.
</Callout>

## 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)

:::important
[Expo Dev Client](https://docs.expo.dev/versions/latest/sdk/dev-client/) (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ể sử dụng nó với [**chế độ mock**](#set-up-mock-mode-for-expo-go--expo-web) để phát triển UI/logic (không có mua hàng thực và không có AdaptyUI/Paywall Builder rendering).
:::

1. Cài đặt Adapty SDK (thao tác này cũng tự động cài đặt `@adapty/core`):
   ```sh
   npx expo install react-native-adapty
   npx expo prebuild
   ```
2. Build ứng dụng để phát triển bằng EAS hoặc local build:

   <Tabs>
   <TabItem value="eas" label="EAS build" default>
      ```sh
      # For iOS
      eas build --profile development --platform ios

   # For Android
   eas build --profile development --platform android
      ```
   </TabItem>

   <TabItem value="local" label="Local build">
      ```sh
      # For iOS
      npx expo run:ios

      # For Android
      npx expo run:android
      ```
   </TabItem>
   </Tabs>
3. Khởi động dev server:
   ```sh
   npx expo start --dev-client
   ```

## 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 đợi `activate` hoàn tất trước khi gọi bất kỳ phương thức Adapty SDK nào khác. 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), hãy làm theo [hướng dẫn nhanh Paywall Builder](react-native-quickstart-paywalls).
- Nếu bạn tự xây dựng UI paywall, hãy 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 dùng các [mẹo](#development-environment-tips).
:::

## Kích hoạt module AdaptyUI của Adapty SDK \{#activate-adaptyui-module-of-adapty-sdk\}

Nếu bạn định sử 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 core module; bạn không cần làm thêm gì khác.

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

| 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 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 loại thông báo thông tin |
| `verbose`  | Ghi lại mọi thông tin bổ sung có thể hữu ích khi debug, chẳng hạn như các lần 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 khi 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 chủ động gửi, 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ủ quy định của cửa hàng hoặc 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`.

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ầ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 advertising identifier. Giá trị mặc định là `false`.

Dùng tham số này để tuân thủ chính sách App Store/Play Store, tránh kích hoạt yêu cầu App Tracking Transparency, hoặc nếu ứng dụng của bạn không cần attribution quảng cáo hay analytics 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 media cache cho AdaptyUI \{#set-up-media-cache-configuration-for-adaptyui\}

Theo mặc định, AdaptyUI cache 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 cache bằng cách cung cấp cấu hình tùy chỉnh.

Dùng `mediaCache` để ghi đè cài đặt cache 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
  },
});
```

Các tham số:
| 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ị cụ thể của nền tảng. |
| memoryStorageCountLimit | tùy chọn | Giới hạn số lượng item trong memory storage. Mặc định theo giá trị cụ thể của 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ụ thể của nền tảng. |

### Bật local access levels (Android) \{#enable-local-access-levels-android\}

Theo mặc định, [local access levels](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 từ backup \{#clear-data-on-backup-restore\}

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 tất cả 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. Sau đó SDK sẽ khởi tạo lại với trạng thái mới. Giá trị mặc định là `false`.

:::note
Chỉ có cache SDK cục bộ 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.
:::

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

#### Thiết lập chế độ mock cho Expo Go / Expo Web \{#set-up-mock-mode-for-expo-go--expo-web\}

Môi trường 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 thử UI và logic paywall của ứng dụng, Adapty cung cấp **chế độ mock**.

::::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 render** 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 thử mua hàng thực và paywall 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ì 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 trả về dữ liệu mock mà không gửi yêu cầu mạng tới máy chủ Adapty.
- Theo mặc định, hồ sơ người dùng mock ban đầu không có gói đăng ký đang hoạt động.
- Theo mặc định, `makePurchase(...)` mô phỏng một lần mua hàng 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 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');
```

#### 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ố trong iOS Simulator, vốn 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 nó 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 ngăn các yêu cầu xác thực không cần thiết nếu không cần thiết.

Điều quan trọng cần lưu ý là **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 tiềm năng. 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 ghi 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 tiếp cận đượ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 kích hoạt trong quá trình phát triển. Để ngăn điều này, hãy dùng tùy chọn `__ignoreActivationOnFastRefresh` đặt thành `__DEV__` (flag 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
}
```

## Xử lý sự cố \{#troubleshooting\}

#### Lỗi phiên bản iOS tối thiểu \{#minimum-ios-version-error\}

Khi build cho iOS, bạn có thể thấy lỗi về **phiên bản iOS tối thiểu** hoặc deployment target, đặc biệt nếu bạn dùng paywall được tạo trong [Adapty paywall builder](adapty-paywall-builder), yêu cầu **iOS 15.0 trở lên**.

Vì Expo tạo dự án iOS (bao gồm `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:

   ```sh
   npx expo install expo-build-properties
   ```
2. Cập nhật Expo config (`app.json` hoặc `app.config.js`) để đặt iOS deployment target:

```
{
    "expo": {
        // ...other Expo config...
        "plugins": [
            [
                "expo-build-properties",
                {
                    "ios": {
                        // Use "13.0" for core Adapty features only,
                        // or "15.0" if you use paywalls created in the paywall builder.
                        "deploymentTarget": "15.0"
                    }
                }
            ],
        ]
    }
}
```

3. Tạo lại dự án iOS native và rebuild:

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

#### Xung đột Android Auto Backup manifest \{#android-auto-backup-manifest-conflict\}

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

Lỗi thường thấy 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 dùng `expo-secure-store`, hãy tắt thiết lập backup của nó để tránh trùng lặp.

Đây là cách cấu hình `app.json`:

```json title="app.json"
{
  "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 Android backup.
Thêm `"configureAndroidBackup": false` nếu bạn dùng `expo-secure-store` để tránh cảnh báo, vì cấu hình backup của SecureStore sẽ được Adapty xử lý.

:::important
Thiết lập này chỉ áp dụng các yêu cầu backup cho Adapty, AppsFlyer và expo-secure-store.
Nếu các thư viện khác trong dự án của bạn định nghĩa các quy tắc backup tùy chỉnh, bạn sẽ cần cấu hình thủ công cho những thư viện đó.
:::

---


# File: sdk-installation-react-native-pure
---

---
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';

<Callout type="info">
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.
</Callout>

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

<details>
   <summary>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)</summary>

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"
     }
   }
   ...
   ```

</details>

## 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 `<manifest>` có chứa tools:

```xml
<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>` \{#2-override-backup-attributes-in-application\}

Trong cùng file `AndroidManifest.xml`, cập nhật thẻ `<application>` để ứ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
<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`:

```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"
<?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 title="sample_backup_rules.xml"
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.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
<activity
    android:name=".MainActivity"
    android:launchMode="standard" />
```

#### 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**.

---


# File: react-native-quickstart-paywalls
---

---
title: "Kích hoạt mua hàng bằng cách sử dụng paywall trong React Native SDK"
description: "Tìm hiểu cách hiển thị paywall trong ứng dụng React Native của bạn với Adapty SDK."
---

Để kích hoạt in-app purchase, bạn cần nắm ba khái niệm chính:

- [**Sản phẩm**](product) – bất cứ thứ gì người dùng có thể mua (gói đăng ký, consumable, quyền truy cập trọn đời)
- [**Paywall**](paywalls) là các cấu hình xác định những sản phẩm nào sẽ được hiển thị. Trong Adapty, paywall là cách duy nhất để lấy sản phẩm, nhưng thiết kế này cho phép bạn thay đổi ưu đãi, giá cả và kết hợp sản phẩm mà không cần chỉnh sửa code.
- [**Placement**](placements) – nơi và thời điểm hiển thị paywall trong ứng dụng (như `main`, `onboarding`, `settings`). Bạn thiết lập paywall cho các placement trên dashboard, sau đó gọi chúng bằng placement ID trong code. Điều này giúp dễ dàng chạy A/B test và hiển thị các paywall khác nhau cho các nhóm người dùng khác nhau.

Adapty cung cấp ba cách để kích hoạt mua hàng trong ứng dụng. Hãy chọn một trong số đó tùy theo yêu cầu của ứng dụng:

| Cách triển khai           | Độ phức tạp | Khi nào nên dùng                                                                                                                                                                                                                                |
|---------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Adapty Paywall Builder    | ✅ Dễ        | Bạn [tạo một paywall hoàn chỉnh, sẵn sàng thanh toán trong trình tạo no-code](quickstart-paywalls). Adapty tự động render và xử lý toàn bộ flow mua hàng phức tạp, xác thực receipt và quản lý gói đăng ký. |
| Paywall tự tạo            | 🟡 Trung bình | Bạn tự xây dựng UI paywall trong code ứng dụng, nhưng vẫn lấy đối tượng paywall từ Adapty để duy trì sự linh hoạt trong danh mục sản phẩm. Xem [hướng dẫn](react-native-quickstart-manual).                                                |
| Observer mode             | 🔴 Khó      | Bạn đã có cơ sở hạ tầng xử lý mua hàng riêng và muốn tiếp tục sử dụng. Lưu ý rằng observer mode có những hạn chế nhất định trong Adapty. Xem [bài viết](observer-vs-full-mode).                                                 |

:::important
**Các bước dưới đây hướng dẫn cách triển khai paywall được tạo trong Adapty Paywall Builder.**

Nếu bạn không muốn dùng Paywall Builder, hãy xem [hướng dẫn xử lý mua hàng trong paywall tự tạo](react-native-making-purchases).
:::

Để hiển thị paywall được tạo trong Adapty Paywall Builder, trong code ứng dụng bạn chỉ cần:

1. **Lấy paywall**: Lấy paywall từ Adapty.
2. **Hiển thị paywall và Adapty sẽ xử lý mua hàng cho bạn**: Hiển thị container paywall bạn đã lấy trong ứng dụng.
3. **Xử lý các hành động nút**: Liên kết tương tác của người dùng với paywall với phản hồi tương ứng trong ứng dụng. Ví dụ, mở link hoặc đóng paywall khi người dùng nhấn nút.

## Trước khi bắt đầu \{#before-you-start\}

Trước khi bắt đầu, hãy hoàn thành các bước sau:

1. Kết nối ứng dụng với [App Store](initial_ios) và/hoặc [Google Play](initial-android) trong Adapty Dashboard.
2. [Tạo sản phẩm](create-product) trong Adapty.
3. [Tạo paywall và thêm sản phẩm vào đó](create-paywall).
4. [Tạo placement và thêm paywall vào đó](create-placement).
5. [Cài đặt và kích hoạt Adapty SDK](sdk-installation-reactnative) trong code ứng dụng.

:::tip
Cách nhanh nhất để hoàn thành các bước này là làm theo [hướng dẫn quickstart](quickstart) hoặc tạo paywall và placement bằng [Developer CLI](developer-cli-quickstart).
:::

## 1. Lấy paywall \{#1-get-the-paywall\}

Các paywall của bạn được liên kết với các placement được cấu hình trong dashboard. Placement cho phép bạn chạy các paywall khác nhau cho các đối tượng khác nhau hoặc chạy [A/B test](ab-tests).

Để lấy paywall được tạo trong Adapty Paywall Builder, bạn cần:

1. Lấy đối tượng `paywall` theo [placement](placements) ID bằng phương thức `getPaywall` và kiểm tra xem đó có phải là paywall được tạo trong builder hay không thông qua thuộc tính `hasViewConfiguration`.

2. Tạo paywall view bằng phương thức `createPaywallView`. View chứa các phần tử UI và style cần thiết để hiển thị paywall.

:::important
Để lấy cấu hình view, bạn phải bật toggle **Show on device** trong Paywall Builder. Nếu không, bạn sẽ nhận được cấu hình view rỗng và paywall sẽ không được hiển thị.
:::

```typescript showLineNumbers title="React Native"

try {
    const placementId = 'YOUR_PLACEMENT_ID';

    const paywall = await adapty.getPaywall(placementId);
  // the requested paywall
} catch (error) {
    // handle the error
}

if (paywall.hasViewConfiguration) {
    try {
        const view = await createPaywallView(paywall);
    } catch (error) {
        // handle the error
    }
} else {
    //use your custom logic
}
```

## 2. Hiển thị paywall \{#2-display-the-paywall\}

Khi đã có cấu hình paywall, bạn chỉ cần thêm vài dòng code để hiển thị paywall.

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

Để nhúng paywall vào cây component hiện có của bạn, hãy sử dụng component `AdaptyPaywallView` trực tiếp trong cấu trúc component React Native:

```typescript showLineNumbers title="React Native (TSX)"

function MyPaywall({ paywall }) {
  const onCloseButtonPress = useCallback<EventHandlers['onCloseButtonPress']>(() => {}, []);
  const onUrlPress = useCallback<EventHandlers['onUrlPress']>((url) => {
    Linking.openURL(url);
  }, []);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      style={styles.container}
      onCloseButtonPress={onCloseButtonPress}
      onUrlPress={onUrlPress}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Để hiển thị paywall như một màn hình độc lập, hãy sử dụng phương thức `view.present()` trên `view` được tạo bởi phương thức `createPaywallView`. Mỗi `view` chỉ có thể được dùng một lần. Nếu bạn cần hiển thị lại paywall, hãy gọi `createPaywallView` thêm một lần nữa để tạo một instance `view` mới.

```typescript showLineNumbers title="React Native"
try {
  await view.present();
} catch (error) {
  // handle the error
}
```

</TabItem>
</Tabs>

:::tip
Để biết thêm chi tiết về cách hiển thị paywall, hãy xem [hướng dẫn](react-native-present-paywalls) của chúng tôi.
:::

## 3. Xử lý các hành động nút \{#3-handle-button-actions\}

Khi người dùng nhấn các nút trong paywall, React Native SDK tự động xử lý mua hàng, khôi phục, đóng paywall và mở URL.

Tuy nhiên, các nút khác có ID tùy chỉnh hoặc được định nghĩa sẵn và cần xử lý hành động trong code của bạn. Hoặc bạn có thể muốn ghi đè hành động mặc định của chúng.

Ví dụ, đây là hành động mặc định cho nút đóng. Bạn không cần thêm nó vào code, nhưng ở đây bạn có thể thấy cách thực hiện nếu cần.

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

Với React component, hãy xử lý các hành động trực tiếp trong component `AdaptyPaywallView`:

```typescript showLineNumbers title="React Native (TSX)"

function MyPaywall({ paywall }) {
  const onUrlPress = useCallback<EventHandlers['onUrlPress']>((url) => {
    Linking.openURL(url);
  }, []);
  const onCloseButtonPress = useCallback<EventHandlers['onCloseButtonPress']>(() => {}, []);
  const onCustomAction = useCallback<EventHandlers['onCustomAction']>((actionId) => {}, []);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      style={styles.container}
      onUrlPress={onUrlPress}
      onCloseButtonPress={onCloseButtonPress}
      onCustomAction={onCustomAction}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Với modal presentation, hãy triển khai các event handler bằng `setEventHandlers`:

```typescript showLineNumbers title="React Native"
const unsubscribe = view.setEventHandlers({
    onCloseButtonPress() {
        return true; // allow paywall closing
    }
});
```

</TabItem>
</Tabs>

:::tip
Đọc các hướng dẫn của chúng tôi về cách xử lý [hành động](react-native-handle-paywall-actions) và [sự kiện](react-native-handling-events-1) của nút.
:::

## Các bước tiếp theo \{#next-steps\}

---
no_index: true
---
import Callout from '../../../components/Callout.astro';

<Callout type="tip">
Bạn có câu hỏi hoặc gặp sự cố? Hãy xem [diễn đàn hỗ trợ](https://adapty.featurebase.app/) của chúng tôi — nơi bạn có thể tìm câu trả lời cho các câu hỏi thường gặp hoặc đặt câu hỏi của riêng mình. Đội ngũ và cộng đồng của chúng tôi luôn sẵn sàng giúp đỡ!
</Callout>

Paywall của bạn đã sẵn sàng để hiển thị trong ứng dụng. Hãy kiểm tra mua hàng trong [App Store sandbox](test-purchases-in-sandbox) hoặc trong [Google Play Store](testing-on-android) để đảm bảo bạn có thể hoàn tất một giao dịch mua thử từ paywall.

Tiếp theo, bạn cần [kiểm tra mức độ truy cập của người dùng](react-native-check-subscription-status) để đảm bảo bạn hiển thị paywall hoặc cấp quyền truy cập vào các tính năng trả phí cho đúng người dùng.

## Ví dụ đầy đủ \{#full-example\}

Đây là cách tất cả các bước đó có thể được tích hợp trong ứng dụng của bạn.

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

```javascript showLineNumbers title="React Native (TSX)"

export default function PaywallScreen() {
  const [paywall, setPaywall] = useState(null);

  const loadPaywall = async () => {
    try {
      const paywallData = await adapty.getPaywall('YOUR_PLACEMENT_ID');

      if (paywallData.hasViewConfiguration) {
        setPaywall(paywallData);
      }
    } catch (error) {
      console.warn('Error loading paywall:', error);
    }
  };

  const onUrlPress = useCallback<EventHandlers['onUrlPress']>((url) => {
    Linking.openURL(url);
  }, []);

  const onCloseButtonPress = useCallback<EventHandlers['onCloseButtonPress']>(() => {
    // Handle close button press
  }, []);

  useEffect(() => {
    loadPaywall();
  }, []);

  return (
    <View style={{ flex: 1 }}>
      {paywall ? (
        <AdaptyPaywallView
          paywall={paywall}
          style={{ flex: 1 }}
          onUrlPress={onUrlPress}
          onCloseButtonPress={onCloseButtonPress}
        />
      ) : (
        <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
          <Button title="Load Paywall" onPress={loadPaywall} />
        </View>
      )}
    </View>
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

```javascript showLineNumbers title="React Native"

export default function PaywallScreen() {
  const showPaywall = async () => {
    try {
      const paywall = await adapty.getPaywall('YOUR_PLACEMENT_ID');

      if (!paywall.hasViewConfiguration) {
        // use your custom logic
        return;
      }

      const view = await createPaywallView(paywall);

      view.setEventHandlers({
          onCloseButtonPress() {
              return true;
        },
      });

      await view.present();
    } catch (error) {
      // handle any error that may occur during the process
      console.warn('Error showing paywall:', error);
    }
  };

  // you can add a button to manually trigger the paywall for testing purposes
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button title="Show Paywall" onPress={showPaywall} />
    </View>
  );
}
```

</TabItem>
</Tabs>

---


# File: react-native-check-subscription-status
---

---
title: "Kiểm tra trạng thái gói đăng ký trong React Native SDK"
description: "Tìm hiểu cách kiểm tra trạng thái gói đăng ký trong ứng dụng React Native với Adapty."
---

Để quyết định xem người dùng có thể truy cập nội dung trả phí hay cần xem paywall hay không, bạn cần kiểm tra [mức độ truy cập](access-level) của họ trong hồ sơ người dùng.

Bài viết này hướng dẫn bạn cách đọc trạng thái hồ sơ người dùng để quyết định nên hiển thị gì — paywall hay nội dung trả phí.

## Lấy trạng thái gói đăng ký \{#get-subscription-status\}

Khi quyết định hiển thị paywall hay nội dung trả phí cho người dùng, bạn kiểm tra [mức độ truy cập](access-level) trong hồ sơ của họ. Bạn có hai lựa chọn:

- Gọi `getProfile` nếu cần dữ liệu hồ sơ mới nhất ngay lập tức (ví dụ khi khởi chạy ứng dụng) hoặc muốn ép buộc cập nhật.
- Thiết lập **cập nhật hồ sơ tự động** để giữ một bản sao cục bộ được tự động làm mới mỗi khi trạng thái gói đăng ký thay đổi.

### Lấy hồ sơ người dùng \{#get-profile\}

Cách đơn giản nhất để lấy trạng thái gói đăng ký là dùng phương thức `getProfile`:

```typescript showLineNumbers
try {
    const profile = await adapty.getProfile();
} catch (error) {
  // handle the error
}
```

### Lắng nghe cập nhật gói đăng ký \{#listen-to-subscription-updates\}

Để tự động nhận cập nhật hồ sơ trong ứng dụng:

1. Dùng `adapty.addEventListener('onLatestProfileLoad')` để lắng nghe các thay đổi hồ sơ — Adapty sẽ tự động gọi phương thức này mỗi khi trạng thái gói đăng ký của người dùng thay đổi.
2. Lưu dữ liệu hồ sơ được cập nhật khi phương thức này được gọi, để bạn có thể sử dụng xuyên suốt ứng dụng mà không cần thực hiện thêm các yêu cầu mạng.

```javascript
class SubscriptionManager {
    private currentProfile: any = null;
    
    constructor() {
        // Listen for profile updates
        adapty.addEventListener('onLatestProfileLoad', (profile) => {
            this.currentProfile = profile;
            // Update UI, unlock content, etc.
        });
    }
    
    // Use stored profile instead of calling getProfile()
    hasAccess(): boolean {
        return this.currentProfile?.accessLevels?.['premium']?.isActive ?? false;
    }
}
```

:::note
Adapty tự động gọi event listener `onLatestProfileLoad` khi ứng dụng khởi động, cung cấp dữ liệu gói đăng ký đã được cache ngay cả khi thiết bị offline.
:::

## Kết nối hồ sơ với logic paywall \{#connect-profile-with-paywall-logic\}

Khi cần đưa ra quyết định ngay lập tức về việc hiển thị paywall hay cấp quyền truy cập vào tính năng trả phí, bạn có thể kiểm tra hồ sơ người dùng trực tiếp. Cách tiếp cận này hữu ích cho các tình huống như khi khởi chạy ứng dụng, khi vào các phần premium, hoặc trước khi hiển thị nội dung cụ thể.

```javascript
const checkAccessLevel = async () => {
  try {
    const profile = await adapty.getProfile();
    return profile.accessLevels['YOUR_ACCESS_LEVEL']?.isActive === true;
  } catch (error) {
    console.warn('Error checking access level:', error);
    return false; // Show paywall if access check fails
  }
};

const initializePaywall = async () => {
  try {
    await loadPaywall();
    
    const hasAccess = await checkAccessLevel();
    if (!hasAccess) {
      // Show paywall if no access
    }
  } catch (error) {
    console.warn('Error initializing paywall:', error);
  }
};
``` 

## Bước tiếp theo \{#next-steps\}

Bây giờ khi bạn đã biết cách theo dõi trạng thái gói đăng ký, hãy tìm hiểu cách [làm việc với hồ sơ người dùng](react-native-quickstart-identify) để đảm bảo họ có thể truy cập những gì đã thanh toán.

---


# File: react-native-quickstart-identify
---

---
title: "Xác định người dùng trong React Native SDK"
description: "Hướng dẫn nhanh để thiết lập Adapty cho việc quản lý gói đăng ký in-app trong React Native."
---

:::important
Hướng dẫn này dành cho bạn nếu bạn có hệ thống xác thực riêng. Tại đây, bạn sẽ học cách làm việc với hồ sơ người dùng trong Adapty để đảm bảo nó phù hợp với hệ thống xác thực hiện có của bạn.
:::

Cách bạn quản lý giao dịch mua của người dùng phụ thuộc vào mô hình xác thực của ứng dụng:
- Nếu ứng dụng không sử dụng xác thực backend và không lưu trữ dữ liệu người dùng, xem [phần về người dùng ẩn danh](#anonymous-users).
- Nếu ứng dụng có (hoặc sẽ có) xác thực backend, xem [phần về người dùng đã xác định](#identified-users).

**Các khái niệm chính**:
- **Hồ sơ người dùng** là các thực thể cần thiết để SDK hoạt động. Adapty tự động tạo chúng.
- Chúng có thể là ẩn danh **(không có customer user ID)** hoặc đã xác định **(có customer user ID)**.
- Bạn cung cấp **customer user ID** để đối chiếu hồ sơ người dùng trong Adapty với hệ thống xác thực nội bộ của bạn.

Dưới đây là sự khác biệt giữa người dùng ẩn danh và người dùng đã xác định:

|                         | Người dùng ẩn danh                                   | Người dùng đã xác định                                                        |
|-------------------------|------------------------------------------------------|-------------------------------------------------------------------------------|
| **Quản lý giao dịch mua** | Khôi phục giao dịch mua ở cấp độ cửa hàng          | Duy trì lịch sử giao dịch mua trên các thiết bị thông qua customer user ID   |
| **Quản lý hồ sơ người dùng** | Hồ sơ mới sau mỗi lần cài đặt lại              | Cùng một hồ sơ người dùng trên các phiên và thiết bị                         |
| **Lưu trữ dữ liệu**    | Dữ liệu người dùng ẩn danh gắn với lần cài đặt ứng dụng | Dữ liệu người dùng đã xác định tồn tại qua các lần cài đặt ứng dụng         |

## Người dùng ẩn danh \{#anonymous-users\}

Nếu bạn không có xác thực backend, **bạn không cần xử lý xác thực trong code ứng dụng**:

1. Khi SDK được kích hoạt lần đầu tiên khởi chạy ứng dụng, Adapty **tạo một hồ sơ người dùng mới**.
2. Khi người dùng mua bất cứ thứ gì trong ứng dụng, giao dịch mua này được **liên kết với hồ sơ Adapty và tài khoản cửa hàng của họ**.
3. Khi người dùng **cài đặt lại** ứng dụng hoặc cài đặt từ **thiết bị mới**, Adapty **tạo một hồ sơ ẩn danh mới khi kích hoạt**.
4. Nếu người dùng đã thực hiện giao dịch mua trước đó trong ứng dụng của bạn, theo mặc định, các giao dịch mua của họ sẽ tự động được đồng bộ từ App Store khi SDK kích hoạt.

Vì vậy, với người dùng ẩn danh, các hồ sơ mới sẽ được tạo sau mỗi lần cài đặt, nhưng điều đó không phải là vấn đề vì trong phần analytics của Adapty, bạn có thể [cấu hình những gì sẽ được tính là lần cài đặt mới](general#4-installs-definition-for-analytics).

:::note
Khôi phục từ bản sao lưu hoạt động khác với cài đặt lại. Theo mặc định, khi người dùng khôi phục từ bản sao lưu, SDK giữ nguyên dữ liệu đã cache và không tạo hồ sơ mới. Bạn có thể cấu hình hành vi này bằng cài đặt `clearDataOnBackup`. [Tìm hiểu thêm](sdk-installation-react-native-pure#clear-data-on-backup-restore).
:::

Đối với người dùng ẩn danh, bạn cần đếm lượt cài đặt theo **device ID**. Trong trường hợp này, mỗi lần cài đặt ứng dụng trên một thiết bị được tính là một lượt cài đặt, kể cả cài đặt lại.

## Người dùng đã xác định \{#identified-users\}

Bạn có hai tùy chọn để xác định người dùng trong ứng dụng:

- [**Trong quá trình đăng nhập/đăng ký:**](#during-loginsignup) Nếu người dùng đăng nhập sau khi ứng dụng khởi động, hãy gọi `identify()` với customer user ID khi họ xác thực.

- [**Trong quá trình kích hoạt SDK:**](#during-the-sdk-activation) Nếu bạn đã có customer user ID được lưu trữ khi ứng dụng khởi chạy, hãy gửi nó khi gọi `activate()`.

:::important
Theo mặc định, khi Adapty nhận được một giao dịch mua từ một Customer User ID hiện đang được liên kết với Customer User ID khác, mức độ truy cập sẽ được chia sẻ, vì vậy cả hai hồ sơ đều có quyền truy cập trả phí. Bạn có thể cấu hình cài đặt này để chuyển quyền truy cập trả phí từ hồ sơ này sang hồ sơ khác hoặc vô hiệu hóa hoàn toàn việc chia sẻ. Xem [bài viết](general#6-sharing-paid-access-between-user-accounts) để biết thêm chi tiết.
:::

  <img src="/assets/shared/img/identify-diagram.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

### Trong quá trình đăng nhập/đăng ký \{#during-loginsignup\}

Nếu bạn đang xác định người dùng sau khi ứng dụng khởi chạy (ví dụ: sau khi họ đăng nhập vào ứng dụng hoặc đăng ký), hãy sử dụng phương thức `identify` để đặt customer user ID của họ.

- Nếu bạn **chưa sử dụng customer user ID này trước đây**, Adapty sẽ tự động liên kết nó với hồ sơ hiện tại.
- Nếu bạn **đã sử dụng customer user ID này để xác định người dùng trước đây**, Adapty sẽ chuyển sang làm việc với hồ sơ được liên kết với customer user ID này.

:::important
Customer user ID phải là duy nhất cho mỗi người dùng. Nếu bạn hardcode giá trị tham số, tất cả người dùng sẽ được coi là một người.
:::

Luôn `await` `identify` trước khi gọi các phương thức SDK khác. Các lần gọi đồng thời sẽ tạo ra `#3006 profileWasChanged` hoặc rơi vào hồ sơ ẩn danh. Xem [Thứ tự gọi trong React Native SDK](react-native-sdk-call-order).

```typescript showLineNumbers
try {
    await adapty.identify("YOUR_USER_ID"); // Unique for each user
    // successfully identified
} catch (error) {
    // handle the error
}
```

### Trong quá trình kích hoạt SDK \{#during-the-sdk-activation\}

Nếu bạn đã biết customer user ID khi kích hoạt SDK, bạn có thể gửi nó trong phương thức `activate` thay vì gọi `identify` riêng biệt.

Nếu bạn biết customer user ID nhưng chỉ đặt nó sau khi kích hoạt, điều đó có nghĩa là khi kích hoạt, Adapty sẽ tạo một hồ sơ ẩn danh mới và chỉ chuyển sang hồ sơ hiện có sau khi bạn gọi `identify`.

Bạn có thể truyền customer user ID hiện có (cái bạn đã sử dụng trước đây) hoặc một cái mới. Nếu bạn truyền một cái mới, hồ sơ mới được tạo khi kích hoạt sẽ tự động được liên kết với customer user ID đó.

:::note
Theo mặc định, việc tạo hồ sơ ẩn danh không ảnh hưởng đến các dashboard analytics, vì lượt cài đặt được đếm dựa trên device ID.

Device ID đại diện cho một lần cài đặt ứng dụng từ cửa hàng trên một thiết bị và chỉ được tạo lại sau khi ứng dụng được cài đặt lại.  
Nó không phụ thuộc vào việc đây là lần cài đặt đầu tiên hay lần cài đặt lại, hoặc liệu có sử dụng customer user ID hiện có hay không.

Việc tạo hồ sơ (khi kích hoạt SDK hoặc đăng xuất), đăng nhập, hoặc nâng cấp ứng dụng mà không cài đặt lại không tạo ra các sự kiện cài đặt bổ sung.

Nếu bạn muốn đếm lượt cài đặt dựa trên người dùng duy nhất thay vì thiết bị, hãy vào **App settings** và cấu hình [**Installs definition for analytics**](general#4-installs-definition-for-analytics).
:::

```typescript showLineNumbers
adapty.activate("PUBLIC_SDK_KEY", {
    customerUserId: "YOUR_USER_ID" // Customer user IDs must be unique for each user. If you hardcode the parameter value, all users will be considered as one.
});
```

### Đăng xuất người dùng \{#log-users-out\}

Nếu bạn có nút để đăng xuất người dùng, hãy sử dụng phương thức `logout`.

:::important
Đăng xuất người dùng sẽ tạo một hồ sơ ẩn danh mới cho người dùng đó.
:::

```typescript showLineNumbers
try {
    await adapty.logout();
    // successful logout
} catch (error) {
    // handle the error
}
```

:::info
Để đăng nhập lại người dùng vào ứng dụng, hãy sử dụng phương thức `identify`.
:::

### Cho phép mua hàng không cần đăng nhập \{#allow-purchases-without-login\}

Nếu người dùng của bạn có thể mua hàng cả trước và sau khi đăng nhập vào ứng dụng, bạn cần đảm bảo rằng họ sẽ giữ được quyền truy cập sau khi đăng nhập:

1. Khi người dùng chưa đăng nhập thực hiện giao dịch mua, Adapty gắn nó với ID hồ sơ ẩn danh của họ.
2. Khi người dùng đăng nhập vào tài khoản, Adapty chuyển sang làm việc với hồ sơ đã xác định của họ.
    - Nếu đây là customer user ID mới (ví dụ: giao dịch mua đã được thực hiện trước khi đăng ký), Adapty gán customer user ID cho hồ sơ hiện tại, vì vậy toàn bộ lịch sử giao dịch mua được duy trì.
    - Nếu đây là customer user ID đã tồn tại (customer user ID đã được liên kết với một hồ sơ), bạn cần lấy mức độ truy cập thực tế sau khi chuyển đổi hồ sơ. Bạn có thể gọi [`getProfile`](react-native-check-subscription-status) ngay sau khi xác định, hoặc [lắng nghe các cập nhật hồ sơ](react-native-check-subscription-status) để dữ liệu tự động đồng bộ.

## Bước tiếp theo \{#next-steps\}

Xin chúc mừng! Bạn đã triển khai logic thanh toán in-app trong ứng dụng của mình! Chúc bạn thành công với việc kiếm tiền từ ứng dụng!

Để khai thác Adapty tốt hơn nữa, bạn có thể khám phá các chủ đề sau:
- [**Kiểm thử**](troubleshooting-test-purchases): Đảm bảo mọi thứ hoạt động như mong đợi
- [**Onboarding**](react-native-onboardings): Thu hút người dùng với onboarding và thúc đẩy giữ chân người dùng
- [**Tích hợp**](configuration): Tích hợp với các dịch vụ attribution marketing và analytics chỉ trong một dòng code
- [**Đặt thuộc tính hồ sơ tùy chỉnh**](react-native-setting-user-attributes): Thêm thuộc tính tùy chỉnh vào hồ sơ người dùng và tạo phân khúc, để bạn có thể chạy A/B test hoặc hiển thị các paywall khác nhau cho các nhóm người dùng khác nhau

---


# File: adapty-sdk-integration-skill-react-native
---

---
title: "Tích hợp Adapty vào ứng dụng React Native với kỹ năng tích hợp SDK"
description: "Sử dụng kỹ năng adapty-sdk-integration để tích hợp Adapty SDK vào ứng dụng React Native của bạn từ đầu đến cuối với công cụ AI coding."
---

:::important
Kỹ năng này đang trong giai đoạn beta. Nếu nó bị treo hoặc hoạt động không như mong đợi, hãy làm theo [hướng dẫn tích hợp từng bước](adapty-cursor-react-native) — hướng dẫn này sẽ dẫn dắt công cụ AI của bạn qua từng giai đoạn với tài liệu phù hợp.
:::

---
no_index: true
---

[Skill adapty-sdk-integration](https://github.com/adaptyteam/adapty-sdk-integration-skill) tự động hóa toàn bộ quá trình tích hợp Adapty: thiết lập dashboard, cài đặt SDK, paywall và xác minh từng giai đoạn. Skill tự động nhận diện nền tảng của bạn và tải tài liệu Adapty phù hợp ở mỗi giai đoạn.

**Công cụ được hỗ trợ**: Claude Code, GitHub Copilot CLI, OpenAI Codex, Gemini CLI.

Để cài đặt, chọn lệnh phù hợp với công cụ của bạn. Danh sách đầy đủ có trong [README của skill](https://github.com/adaptyteam/adapty-sdk-integration-skill).

**Claude Code**

```
claude plugin marketplace add adaptyteam/adapty-sdk-integration-skill
claude plugin install adapty-sdk-integration@adapty
```

**GitHub Copilot CLI**

```
gh skill install adaptyteam/adapty-sdk-integration-skill
```

**Gemini CLI**

```
gemini skills install https://github.com/adaptyteam/adapty-sdk-integration-skill
```

**OpenAI Codex hoặc bất kỳ công cụ nào khác**: Clone repo và sao chép thư mục `plugins/adapty-sdk-integration/skills/adapty-sdk-integration/` vào thư mục skills của công cụ bạn đang dùng.

Sau khi cài đặt, chạy skill trong dự án của bạn:

```
/adapty-sdk-integration
```

Skill sẽ hỏi một vài câu hỏi thiết lập, sau đó hướng dẫn bạn qua các bước: thiết lập dashboard, cài đặt SDK, paywall và xác minh.

---


# File: adapty-cursor-react-native
---

---
title: "Tích hợp Adapty vào ứng dụng React Native của bạn với sự hỗ trợ của AI"
description: "Hướng dẫn từng bước tích hợp Adapty vào ứng dụng React Native của bạn bằng Cursor, Context7, ChatGPT, Claude hoặc các công cụ AI khác."
---

Hướng dẫn này sẽ dẫn bạn qua từng bước tích hợp Adapty vào ứng dụng React Native của bạn với sự hỗ trợ của công cụ AI — bạn chỉ cần cung cấp đúng tài liệu Adapty theo đúng thứ tự.

For a fully automated integration, use the [adapty-sdk-integration skill](https://github.com/adaptyteam/adapty-sdk-integration-skill): it runs the whole integration from your AI coding tool in one command.

## Trước khi bắt đầu: thiết lập trên dashboard \{#before-you-start-dashboard-setup\}

Adapty yêu cầu một số cấu hình trên dashboard trước khi bạn viết bất kỳ mã SDK nào. Bạn có thể thực hiện điều này thông qua một skill LLM tương tác, hoặc thủ công qua Dashboard.

### Cách dùng Skill (khuyến nghị) \{#skill-approach-recommended\}

Skill Adapty CLI cho phép LLM của bạn thiết lập ứng dụng, sản phẩm, mức độ truy cập, paywall và placement trực tiếp — mà không cần mở Dashboard cho từng bước. Bạn chỉ cần [kết nối cửa hàng của mình](integrate-payments) trong Dashboard.

```
npx skills add adaptyteam/adapty-cli --skill adapty-cli
```

Sau khi thêm skill, chạy `/adapty-cli` trong agent của bạn. Nó sẽ hướng dẫn bạn qua từng bước — kể cả khi nào cần mở Dashboard để kết nối cửa hàng.

### Cách thiết lập thủ công trên Dashboard \{#dashboard-approach\}

Nếu bạn muốn tự cấu hình mọi thứ, dưới đây là những gì bạn cần trước khi viết bất kỳ mã nào. LLM của bạn không thể tra cứu các giá trị từ dashboard — bạn sẽ phải cung cấp chúng.

1. **Kết nối cửa hàng ứng dụng của bạn**: Trong Adapty Dashboard, vào **App settings → General**. Kết nối cả App Store và Google Play nếu ứng dụng của bạn nhắm đến cả hai nền tảng. Đây là điều kiện bắt buộc để mua hàng hoạt động.
   [Kết nối cửa hàng ứng dụng](integrate-payments)

2. **Sao chép Public SDK key của bạn**: Trong Adapty Dashboard, vào **App settings → General**, sau đó tìm phần **API keys**. Trong mã, đây là chuỗi bạn truyền vào `adapty.activate("YOUR_PUBLIC_SDK_KEY")`.

3. **Tạo ít nhất một sản phẩm**: Trong Adapty Dashboard, vào trang **Products**. Bạn không tham chiếu sản phẩm trực tiếp trong mã — Adapty phân phối chúng thông qua paywall.
   [Thêm sản phẩm](quickstart-products)

4. **Tạo một paywall và một placement**: Trong Adapty Dashboard, tạo paywall trên trang **Paywalls**, sau đó gán nó cho một placement trên trang **Placements**. Trong mã, placement ID là chuỗi bạn truyền vào `adapty.getPaywall("YOUR_PLACEMENT_ID")`.
   [Tạo paywall](quickstart-paywalls)

5. **Thiết lập mức độ truy cập**: Trong Adapty Dashboard, cấu hình theo từng sản phẩm trên trang **Products**. Trong mã, đây là chuỗi được kiểm tra trong `profile.accessLevels['premium']?.isActive`. Mức độ truy cập `premium` mặc định phù hợp với hầu hết các ứng dụng. Nếu người dùng trả phí được truy cập các tính năng khác nhau tùy theo sản phẩm (ví dụ: gói `basic` so với gói `pro`), [hãy tạo thêm mức độ truy cập](assigning-access-level-to-a-product) trước khi bắt đầu viết mã.

:::tip
Khi bạn có đủ năm mục trên, bạn đã sẵn sàng viết mã. Hãy cho LLM của bạn biết: "Public SDK key của tôi là X, placement ID của tôi là Y" để nó có thể tạo mã khởi tạo và lấy paywall chính xác.
:::

### Thiết lập khi sẵn sàng \{#set-up-when-ready\}

Những mục này không bắt buộc để bắt đầu viết mã, nhưng bạn sẽ cần chúng khi tích hợp trưởng thành hơn:

- **A/B test**: Cấu hình trên trang **Placements**. Không cần thay đổi mã.
  [A/B test](ab-tests)
- **Thêm paywall và placement**: Thêm nhiều lời gọi `getPaywall` với các placement ID khác nhau.
- **Tích hợp analytics**: Cấu hình trên trang **Integrations**. Cách thiết lập tùy theo từng tích hợp. Xem [tích hợp analytics](analytics-integration) và [tích hợp attribution](attribution-integration).

## Cung cấp tài liệu Adapty cho LLM của bạn \{#feed-adapty-docs-to-your-llm\}

### Dùng Context7 (khuyến nghị) \{#use-context7-recommended\}

[Context7](https://context7.com) là một MCP server cho phép LLM của bạn truy cập trực tiếp vào tài liệu Adapty luôn cập nhật. LLM của bạn sẽ tự động lấy đúng tài liệu dựa trên câu hỏi của bạn — không cần dán URL thủ công.

Context7 hoạt động với **Cursor**, **Claude Code**, **Windsurf** và các công cụ tương thích MCP khác. Để thiết lập, chạy:

```
npx ctx7 setup
```

Lệnh này sẽ phát hiện trình soạn thảo của bạn và cấu hình Context7 server. Để thiết lập thủ công, xem [repository GitHub của Context7](https://github.com/upstash/context7).

Sau khi cấu hình xong, tham chiếu thư viện Adapty trong prompt của bạn:

```
Use the adaptyteam/adapty-docs library to look up how to install the React Native SDK
```

:::warning
Dù Context7 giúp bạn không cần dán link tài liệu thủ công, thứ tự triển khai vẫn rất quan trọng. Hãy làm theo [hướng dẫn triển khai](#implementation-walkthrough) bên dưới từng bước để đảm bảo mọi thứ hoạt động đúng.
:::

### Dùng tài liệu dạng văn bản thuần \{#use-plain-text-docs\}

Bạn có thể truy cập bất kỳ tài liệu Adapty nào dưới dạng Markdown thuần. Thêm `.md` vào cuối URL của nó, hoặc nhấp **Copy for LLM** bên dưới tiêu đề bài viết. Ví dụ: [adapty-cursor-react-native.md](https://adapty.io/docs/vi/adapty-cursor-react-native.md).

Mỗi giai đoạn trong [hướng dẫn triển khai](#implementation-walkthrough) bên dưới đều có một khối "Gửi cho LLM của bạn" với các link `.md` để dán vào.

Để có thêm tài liệu cùng lúc, xem [file index và các tập con theo nền tảng](#plain-text-doc-index-files) bên dưới.

## Hướng dẫn triển khai \{#implementation-walkthrough\}

Phần còn lại của hướng dẫn này sẽ đi qua việc tích hợp Adapty theo đúng thứ tự triển khai. Mỗi giai đoạn bao gồm tài liệu cần gửi cho LLM, kết quả mong đợi khi hoàn thành và các vấn đề thường gặp.

### Lập kế hoạch tích hợp \{#plan-your-integration\}

Trước khi bắt đầu viết mã, hãy yêu cầu LLM của bạn phân tích dự án và tạo kế hoạch triển khai. Nếu công cụ AI của bạn hỗ trợ chế độ lập kế hoạch (như chế độ plan của Cursor hoặc Claude Code), hãy sử dụng nó để LLM có thể đọc cả cấu trúc dự án của bạn lẫn tài liệu Adapty trước khi viết bất kỳ mã nào.

Hãy cho LLM biết cách bạn xử lý mua hàng — điều này ảnh hưởng đến các hướng dẫn nó cần theo:

- [**Adapty Paywall Builder**](adapty-paywall-builder): Bạn tạo paywall trong trình tạo no-code của Adapty, và SDK sẽ hiển thị chúng tự động.
- [**Paywall tự tạo**](react-native-making-purchases): Bạn tự xây dựng giao diện paywall trong mã nhưng vẫn dùng Adapty để lấy sản phẩm và xử lý mua hàng.
- [**Observer mode**](observer-vs-full-mode): Bạn giữ nguyên cơ sở hạ tầng mua hàng hiện có và chỉ dùng Adapty cho analytics và tích hợp.

Chưa chắc nên chọn cái nào? Đọc [bảng so sánh trong quickstart](react-native-quickstart-paywalls).

### Cài đặt và cấu hình SDK \{#install-and-configure-the-sdk\}

Thêm dependency Adapty SDK bằng npm (hoặc yarn) và kích hoạt nó với Public SDK key của bạn. Đây là nền tảng — mọi thứ khác đều không hoạt động nếu thiếu bước này.

Chúng tôi có hướng dẫn cài đặt riêng cho dự án Expo và bare React Native — hãy chọn cái phù hợp với thiết lập của bạn.

**Hướng dẫn:**
- [Cài đặt với Expo](sdk-installation-react-native-expo)
- [Cài đặt với bare React Native](sdk-installation-react-native-pure)

Gửi cho LLM của bạn (chọn cái phù hợp với thiết lập của bạn, hoặc gửi cả hai):
```
Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/sdk-installation-react-native-expo.md
- https://adapty.io/docs/vi/sdk-installation-react-native-pure.md
```

:::tip[Kiểm tra]
- **Kết quả mong đợi:** Ứng dụng build và chạy được trên cả iOS và Android. Log của Metro bundler hiển thị log kích hoạt Adapty.
- **Lưu ý:** "Public API key is missing" → kiểm tra xem bạn đã thay thế placeholder bằng key thật từ App settings chưa.
:::

### Hiển thị paywall và xử lý mua hàng \{#show-paywalls-and-handle-purchases\}

Lấy paywall theo placement ID, hiển thị nó và xử lý các sự kiện mua hàng. Các hướng dẫn bạn cần phụ thuộc vào cách bạn xử lý mua hàng.

Hãy kiểm tra từng giao dịch trong sandbox khi thực hiện — đừng đợi đến cuối. Xem [Kiểm tra mua hàng trong sandbox](test-purchases-in-sandbox) để biết hướng dẫn thiết lập.

<Tabs groupId="paywall-approach">

<TabItem value="builder" label="Paywall Builder" default>

**Hướng dẫn:**
- [Bật mua hàng bằng paywall (quickstart)](react-native-quickstart-paywalls)
- [Lấy paywall từ Paywall Builder và cấu hình của chúng](react-native-get-pb-paywalls)
- [Hiển thị paywall](react-native-present-paywalls)
- [Xử lý sự kiện paywall](react-native-handling-events-1)
- [Phản hồi các thao tác nút](react-native-handle-paywall-actions)

Gửi cho LLM của bạn:
```
Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/react-native-quickstart-paywalls.md
- https://adapty.io/docs/vi/react-native-get-pb-paywalls.md
- https://adapty.io/docs/vi/react-native-present-paywalls.md
- https://adapty.io/docs/vi/react-native-handling-events-1.md
- https://adapty.io/docs/vi/react-native-handle-paywall-actions.md
```

:::tip[Kiểm tra]
- **Kết quả mong đợi:** Paywall xuất hiện với các sản phẩm bạn đã cấu hình. Nhấn vào một sản phẩm sẽ kích hoạt hộp thoại mua hàng sandbox.
- **Lưu ý:** Paywall trống hoặc lỗi `getPaywall` → xác minh placement ID khớp chính xác với dashboard và placement có đối tượng được gán.
:::

</TabItem>

<TabItem value="manual" label="Paywall tự tạo">

**Hướng dẫn:**
- [Bật mua hàng trong paywall tùy chỉnh của bạn (quickstart)](react-native-quickstart-manual)
- [Lấy paywall và sản phẩm](fetch-paywalls-and-products-react-native)
- [Hiển thị paywall được thiết kế bằng remote config](present-remote-config-paywalls-react-native)
- [Thực hiện mua hàng](react-native-making-purchases)
- [Khôi phục mua hàng](react-native-restore-purchase)

Gửi cho LLM của bạn:
```
Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/react-native-quickstart-manual.md
- https://adapty.io/docs/vi/fetch-paywalls-and-products-react-native.md
- https://adapty.io/docs/vi/present-remote-config-paywalls-react-native.md
- https://adapty.io/docs/vi/react-native-making-purchases.md
- https://adapty.io/docs/vi/react-native-restore-purchase.md
```

:::tip[Kiểm tra]
- **Kết quả mong đợi:** Paywall tùy chỉnh của bạn hiển thị các sản phẩm lấy từ Adapty. Nhấn vào một sản phẩm sẽ kích hoạt hộp thoại mua hàng sandbox.
- **Lưu ý:** Mảng sản phẩm trống → xác minh paywall đã có sản phẩm được gán trong dashboard và placement có đối tượng.
:::

</TabItem>

<TabItem value="observer" label="Observer mode">

**Hướng dẫn:**
- [Tổng quan về Observer mode](observer-vs-full-mode)
- [Triển khai Observer mode](implement-observer-mode-react-native)
- [Báo cáo giao dịch trong Observer mode](report-transactions-observer-mode-react-native)

Gửi cho LLM của bạn:
```
Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/observer-vs-full-mode.md
- https://adapty.io/docs/vi/implement-observer-mode-react-native.md
- https://adapty.io/docs/vi/report-transactions-observer-mode-react-native.md
```

:::tip[Kiểm tra]
- **Kết quả mong đợi:** Sau khi mua hàng trong sandbox bằng flow mua hàng hiện có của bạn, giao dịch sẽ xuất hiện trong **Event Feed** trên Adapty dashboard.
- **Lưu ý:** Không có sự kiện → xác minh bạn đang báo cáo giao dịch cho Adapty và thông báo server đã được cấu hình cho cả hai cửa hàng.
:::

</TabItem>

</Tabs>

### Kiểm tra trạng thái gói đăng ký \{#check-subscription-status\}

Sau khi mua hàng, kiểm tra hồ sơ người dùng để xem có mức độ truy cập đang hoạt động hay không nhằm giới hạn nội dung premium.

**Hướng dẫn:** [Kiểm tra trạng thái gói đăng ký](react-native-check-subscription-status)

Gửi cho LLM của bạn:
```
Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/react-native-check-subscription-status.md
```

:::tip[Kiểm tra]
- **Kết quả mong đợi:** Sau khi mua hàng trong sandbox, `profile.accessLevels['premium']?.isActive` trả về `true`.
- **Lưu ý:** `accessLevels` trống sau khi mua → kiểm tra sản phẩm đã được gán mức độ truy cập trong dashboard chưa.
:::

### Xác định người dùng \{#identify-users\}

Liên kết tài khoản người dùng trong ứng dụng của bạn với hồ sơ Adapty để mua hàng được duy trì trên nhiều thiết bị.

:::important
Bỏ qua bước này nếu ứng dụng của bạn không có xác thực.
:::

**Hướng dẫn:** [Xác định người dùng](react-native-quickstart-identify)

Gửi cho LLM của bạn:
```
Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/react-native-quickstart-identify.md
```

:::tip[Kiểm tra]
- **Kết quả mong đợi:** Sau khi gọi `adapty.identify("your-user-id")`, phần **Profiles** trong dashboard sẽ hiển thị ID người dùng tùy chỉnh của bạn.
- **Lưu ý:** Gọi `identify` sau khi kích hoạt nhưng trước khi lấy paywall để tránh attribution hồ sơ ẩn danh.
:::

### Chuẩn bị phát hành \{#prepare-for-release\}

Sau khi tích hợp hoạt động trong sandbox, hãy xem qua danh sách kiểm tra phát hành để đảm bảo mọi thứ sẵn sàng cho môi trường production.

**Hướng dẫn:** [Danh sách kiểm tra phát hành](release-checklist)

Gửi cho LLM của bạn:
```
Read these Adapty docs before releasing:
- https://adapty.io/docs/vi/release-checklist.md
```

:::tip[Kiểm tra]
- **Kết quả mong đợi:** Tất cả các mục trong danh sách đã được xác nhận: kết nối cửa hàng, thông báo server, flow mua hàng, kiểm tra mức độ truy cập và yêu cầu về quyền riêng tư.
- **Lưu ý:** Thiếu thông báo server → cấu hình App Store Server Notifications trong **App settings → iOS SDK** và Google Play Real-Time Developer Notifications trong **App settings → Android SDK**.
:::

## File index tài liệu dạng văn bản thuần \{#plain-text-doc-index-files\}

Nếu bạn cần cung cấp cho LLM ngữ cảnh rộng hơn ngoài các trang riêng lẻ, chúng tôi có các file index liệt kê hoặc kết hợp toàn bộ tài liệu Adapty:

- [`llms.txt`](https://adapty.io/docs/vi/llms.txt): Liệt kê tất cả các trang với các link `.md`. Đây là [tiêu chuẩn đang nổi lên](https://llmstxt.org/) để làm cho các trang web có thể truy cập được bởi LLM. Lưu ý rằng với một số AI agent (ví dụ: ChatGPT), bạn sẽ cần tải `llms.txt` xuống và tải lên chat dưới dạng file.
- [`llms-full.txt`](https://adapty.io/docs/vi/llms-full.txt): Toàn bộ trang tài liệu Adapty được kết hợp thành một file duy nhất. Rất lớn — chỉ dùng khi bạn cần toàn bộ bức tranh.
- Các file dành riêng cho React Native [`react-native-llms.txt`](https://adapty.io/docs/vi/react-native-llms.txt) và [`react-native-llms-full.txt`](https://adapty.io/docs/vi/react-native-llms-full.txt): Các tập con theo nền tảng giúp tiết kiệm token so với toàn bộ trang.

---


# File: react-native-get-pb-paywalls
---

---
title: "Lấy paywalls Paywall Builder và cấu hình của chúng trong React Native SDK"
description: "Tìm hiểu cách truy xuất PB paywalls trong Adapty để kiểm soát gói đăng ký tốt hơn trong ứng dụng React Native của bạn."
---

Sau khi [bạn đã thiết kế phần giao diện cho paywall của mình](adapty-paywall-builder) bằng Paywall Builder mới trong Adapty Dashboard, bạn có thể hiển thị nó trong ứng dụng di động của mình. Bước đầu tiên trong quá trình này là lấy paywall liên kết với placement và cấu hình view của nó như mô tả bên dưới.

:::warning
Paywall Builder mới hoạt động với React Native SDK phiên bản 3.0 trở lên.
:::

Lưu ý rằng chủ đề này đề cập đến các paywall được tùy chỉnh bằng Paywall Builder. Nếu bạn đang triển khai paywall thủ công, hãy tham khảo chủ đề [Lấy paywalls và sản phẩm cho remote config paywalls trong ứng dụng di động của bạn](fetch-paywalls-and-products-react-native).

:::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](sample-apps) của chúng tôi, nơi minh họa toàn bộ quá 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.

:::

<details>
   <summary>Trước khi bắt đầu hiển thị paywalls trong ứng dụng di động của bạn (nhấp để mở rộng)</summary>

1. [Tạo sản phẩm của bạn](create-product) trong Adapty Dashboard.
2. [Tạo paywall và tích hợp các sản phẩm vào đó](create-paywall) trong Adapty Dashboard.
3. [Tạo placements và tích hợp paywall của bạn vào đó](create-placement) trong Adapty Dashboard.
4. Cài đặt [Adapty SDK](sdk-installation-reactnative) trong ứng dụng di động của bạn.
</details>

## Lấy paywall được thiết kế bằng Paywall Builder \{#fetch-paywall-designed-with-paywall-builder\}

Nếu bạn đã [thiết kế paywall bằng Paywall Builder](adapty-paywall-builder), bạn không cần phải lo lắng về việc render nó trong code ứng dụng di động để hiển thị cho người dùng. Paywall như vậy chứa cả nội dung cần hiển thị và cách thức hiển thị. Tuy nhiên, bạn cần lấy ID của nó qua placement, cấu hình view, rồi hiển thị nó trong ứng dụng di động của mình.

Để đảm bảo hiệu suất tối ưu, điều quan trọng là phải truy xuất paywall và [cấu hình view](react-native-get-pb-paywalls#fetch-the-view-configuration-of-paywall-designed-using-paywall-builder) càng sớm càng tốt, để có đủ thời gian tải ảnh trước khi hiển thị cho người dùng.

Để lấy paywall, sử dụng phương thức `getPaywall`:

```typescript showLineNumbers
try {
    const placementId = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywall(placementId, locale);
  // the requested paywall
} catch (error) {
    // handle the error
}
```
Tham số:

| Tham số           | Bắt buộc | Mô tả |
|-------------------|--------|-----------|
| **placementId**   | bắt buộc | Định danh của [Placement](placements) mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard. |
| **locale**        | <p>tùy chọn</p><p>mặc định: `en`</p> | <p>Định danh của [bản địa hóa paywall](add-paywall-locale-in-adapty-paywall-builder). Tham số này được kỳ vọng là mã ngôn ngữ gồm một hoặc hai thẻ phụ được phân tách bằng dấu trừ (**-**). Thẻ phụ đầu tiên là ngôn ngữ, thẻ phụ thứ hai là khu vực.</p><p></p><p>Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha Brazil.</p><p>Xem [Bản địa hóa và mã locale](localizations-and-locale-codes) để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng chúng.</p> |
| **fetchPolicy**   | mặc định: `.reloadRevalidatingCacheData` | <p>Theo mặc định, SDK sẽ cố tải dữ liệu từ server và trả về dữ liệu đã cache trong trường hợp thất bại. Chúng tôi khuyến nghị cách này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.</p><p></p><p>Tuy nhiên, nếu bạn cho rằng người dùng của mình thường xuyên gặp kết nối internet không ổn định, hãy cân nhắc sử dụng `.returnCacheDataElseLoad` để trả về dữ liệu đã cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất hoàn toàn, nhưng họ sẽ trải nghiệm thời gian tải nhanh hơn, bất kể kết nối internet của họ như thế nào. Cache được cập nhật thường xuyên nên an toàn để sử dụng trong phiên nhằm tránh các yêu cầu mạng.</p><p></p><p>Lưu ý rằng cache vẫn còn nguyên sau khi khởi động lại ứng dụng và chỉ bị xóa khi ứng dụng được cài đặt lại hoặc thông qua dọn dẹp thủ công.</p><p></p><p>Adapty SDK lưu trữ paywalls cục bộ theo hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và [paywall dự phòng](fallback-paywalls). Chúng tôi cũng sử dụng CDN để lấy paywalls nhanh hơn và một server dự phòng độc lập trong trường hợp CDN không thể truy cập được. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản mới nhất của paywalls trong khi vẫn đảm bảo độ tin cậy ngay cả khi kết nối internet kém.</p> |
| **loadTimeoutMs** | mặc định: 5 giây | <p>Giá trị này giới hạn timeout cho phương thức này. Nếu timeout được đạt đến, dữ liệu đã cache hoặc fallback cục bộ sẽ được trả về.</p><p>Lưu ý rằng trong một số trường hợp hiếm gặp, phương thức này có thể timeout muộn hơn một chút so với giá trị được chỉ định trong `loadTimeout`, vì thao tác có thể bao gồm các yêu cầu khác nhau bên dưới.</p><p>Với Android: Bạn có thể tạo `TimeInterval` với các extension function (như `5.seconds`, trong đó `.seconds` là từ `import com.adapty.utils.seconds`), hoặc `TimeInterval.seconds(5)`. Để không giới hạn, sử dụng `TimeInterval.INFINITE`.</p> |

Tham số phản hồi:

| Tham số | Mô tả                                                                                                                                                                                  |
| :-------- |:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Paywall   | Một đối tượng [`AdaptyPaywall`](https://react-native.adapty.io/interfaces/adaptypaywall) với danh sách ID sản phẩm, định danh paywall, remote config và một số thuộc tính khác. |

## Lấy cấu hình view của paywall được thiết kế bằng Paywall Builder \{#fetch-the-view-configuration-of-paywall-designed-using-paywall-builder\}

:::important
Đảm bảo bật toggle **Show on device** trong paywall builder. Nếu tùy chọn này không được bật, cấu hình view sẽ không có sẵn để truy xuất.
:::

Sau khi lấy paywall, hãy kiểm tra xem nó có bao gồm `ViewConfiguration` hay không, điều này cho biết nó được tạo bằng Paywall Builder. Điều này sẽ hướng dẫn bạn cách hiển thị paywall. Nếu `ViewConfiguration` có mặt, hãy xử lý nó như một Paywall Builder paywall; nếu không, [xử lý nó như một remote config paywall](present-remote-config-paywalls-react-native).

Trong React Native SDK, hãy gọi trực tiếp phương thức `createPaywallView` mà không cần lấy cấu hình view theo cách thủ công trước.

:::warning
Kết quả của phương thức `createPaywallView` chỉ có thể được sử dụng một lần. Nếu bạn cần sử dụng lại, hãy gọi phương thức `createPaywallView` lần nữa. Gọi hai lần mà không tạo lại có thể dẫn đến lỗi `AdaptyUIError.viewAlreadyPresented`.
:::

```typescript showLineNumbers
// for the Adapty SDK < 3.14 – import {createPaywallView} from 'react-native-adapty/dist/ui';

if (paywall.hasViewConfiguration) {
  try {
    const view = await createPaywallView(paywall);
  } catch (error) {
    // handle the error
  }
} else {
    //use your custom logic
}
```

Tham số:

| Tham số              | Bắt buộc | Mô tả                                                        |
| :------------------- | :------- | :----------------------------------------------------------- |
| **paywall**          | bắt buộc | Một đối tượng `AdaptyPaywall` để lấy controller cho paywall mong muốn. |
| **customTags**       | tùy chọn | Định nghĩa một dictionary các custom tag và giá trị đã được xử lý của chúng. Custom tag đóng vai trò là placeholder trong nội dung paywall, được thay thế động bằng các chuỗi cụ thể để cá nhân hóa nội dung trong paywall. Tham khảo chủ đề Custom tags in paywall builder để biết thêm chi tiết. |
| **prefetchProducts** | tùy chọn | Bật để tối ưu hóa thời gian hiển thị sản phẩm trên màn hình. Khi `true`, AdaptyUI sẽ tự động lấy các sản phẩm cần thiết. Mặc định: `false`. |

:::note
Nếu bạn đang sử dụng nhiều ngôn ngữ, hãy tìm hiểu cách thêm [bản địa hóa Paywall Builder](add-paywall-locale-in-adapty-paywall-builder) và cách sử dụng mã locale đúng cách [tại đây](react-native-localizations-and-locale-codes).
:::

Sau khi có view, hãy [hiển thị paywall](react-native-present-paywalls).

## Lấy paywall cho đối tượng mặc định để tải nhanh hơn \{#get-a-paywall-for-a-default-audience-to-fetch-it-faster\}

Thông thường, paywalls được tải gần như ngay lập tức, vì vậy bạn không cần lo lắng về việc tăng tốc quá trình này. Tuy nhiên, trong những trường hợp bạn có nhiều đối tượng và paywalls, và người dùng của bạn có kết nối internet yếu, việc tải paywall có thể mất nhiều thời gian hơn mong muốn. Trong những tình huống như vậy, bạn có thể muốn hiển thị paywall mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị paywall nào.

Để giải quyết vấn đề này, bạn có thể sử dụng phương thức `getPaywallForDefaultAudience`, phương thức này lấy paywall của placement được chỉ định cho đối tượng **All Users**. Tuy nhiên, điều quan trọng cần hiểu là cách tiếp cận được khuyến nghị là lấy paywall bằng phương thức `getPaywall`, như được mô tả chi tiết trong phần [Lấy thông tin Paywall](#fetch-paywall-designed-with-paywall-builder) ở trên.

:::warning
Lý do chúng tôi khuyến nghị sử dụng `getPaywall`

Phương thức `getPaywallForDefaultAudience` có một số nhược điểm đáng kể:

- **Vấn đề khả năng tương thích ngược tiềm ẩn**: Nếu bạn cần hiển thị các paywalls khác nhau cho các phiên bản ứng dụng khác nhau (hiện tại và tương lai), bạn có thể gặp khó khăn. Bạn sẽ phải thiết kế paywalls hỗ trợ phiên bản hiện tại (cũ) hoặc chấp nhận rằng người dùng có phiên bản hiện tại (cũ) có thể gặp sự cố với paywalls không được render.
- **Mất khả năng nhắm mục tiêu**: Tất cả người dùng sẽ thấy cùng một paywall được thiết kế cho đối tượng **All Users**, nghĩa là bạn mất khả năng nhắm mục tiêu cá nhân hóa (bao gồm theo quốc gia, marketing attribution hoặc các thuộc tính tùy chỉnh của riêng bạn).

Nếu bạn sẵn sàng chấp nhận những nhược điểm này để hưởng lợi từ việc tải paywall nhanh hơn, hãy sử dụng phương thức `getPaywallForDefaultAudience` như sau. Nếu không, hãy sử dụng `getPaywall` được mô tả [ở trên](#fetch-paywall-designed-with-paywall-builder).
:::

```typescript showLineNumbers
try {
    const id = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywallForDefaultAudience(id, locale);
  // the requested paywall
} catch (error) {
    // handle the error
}
```

:::note
Phương thức `getPaywallForDefaultAudience` có sẵn từ React Native SDK phiên bản 2.11.2 trở lên.
:::

| Tham số | Bắt buộc | Mô tả                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **placementId** | bắt buộc | Định danh của [Placement](placements). Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard của bạn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **locale** | <p>tùy chọn</p><p>mặc định: `en`</p> | <p>Định danh của [bản địa hóa paywall](add-remote-config-locale). Tham số này được kỳ vọng là mã ngôn ngữ gồm một hoặc nhiều thẻ phụ được phân tách bằng dấu trừ (**-**). Thẻ phụ đầu tiên là ngôn ngữ, thẻ phụ thứ hai là khu vực.</p><p></p><p>Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha Brazil.</p><p></p><p>Xem [Bản địa hóa và mã locale](react-native-localizations-and-locale-codes) để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng chúng.</p>                                                                                                                                                                                                                                                                                          |
| **fetchPolicy** | mặc định: `.reloadRevalidatingCacheData` | <p>Theo mặc định, SDK sẽ cố tải dữ liệu từ server và trả về dữ liệu đã cache trong trường hợp thất bại. Chúng tôi khuyến nghị cách này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.</p><p></p><p>Tuy nhiên, nếu bạn cho rằng người dùng của mình thường xuyên gặp kết nối internet không ổn định, hãy cân nhắc sử dụng `.returnCacheDataElseLoad` để trả về dữ liệu đã cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất hoàn toàn, nhưng họ sẽ trải nghiệm thời gian tải nhanh hơn, bất kể kết nối internet của họ như thế nào. Cache được cập nhật thường xuyên nên an toàn để sử dụng trong phiên nhằm tránh các yêu cầu mạng.</p><p></p><p>Lưu ý rằng cache vẫn còn nguyên sau khi khởi động lại ứng dụng và chỉ bị xóa khi ứng dụng được cài đặt lại hoặc thông qua dọn dẹp thủ công.</p> |

## Tùy chỉnh assets \{#customize-assets\}

Để tùy chỉnh hình ảnh và video trong paywall của bạn, hãy triển khai custom assets.

Hình ảnh hero và video có ID được xác định trước: `hero_image` và `hero_video`. Trong một custom asset bundle, bạn nhắm mục tiêu các phần tử này bằng ID của chúng và tùy chỉnh hành vi của chúng.

Đối với các hình ảnh và video khác, bạn cần [đặt custom ID](custom-media) trong Adapty dashboard.

Ví dụ, bạn có thể:

- Hiển thị hình ảnh hoặc video khác cho một số người dùng.
- Hiển thị hình ảnh preview cục bộ trong khi hình ảnh chính từ xa đang tải.
- Hiển thị hình ảnh preview trước khi chạy video.

:::important
Để sử dụng tính năng này, hãy cập nhật Adapty React Native SDK lên phiên bản 3.8.0 trở lên.
:::

Đây là ví dụ về cách bạn có thể cung cấp custom assets thông qua một dictionary đơn giản:

```javascript
const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createPaywallView(paywall, { customAssets })

```

:::note
Nếu không tìm thấy asset, paywall sẽ quay lại giao diện mặc định của nó.
:::

---


# File: react-native-present-paywalls
---

---
title: "React Native - Hiển thị paywall mới bằng Paywall Builder"
description: "Hiển thị paywall trong ứng dụng React Native bằng Adapty."
---

Nếu bạn đã tùy chỉnh paywall bằng Paywall Builder, bạn không cần lo lắng về việc render nó trong mã ứng dụng di động để hiển thị cho người dùng. Một paywall như vậy chứa cả nội dung cần hiển thị lẫn cách thức hiển thị.

Trước khi bắt đầu, hãy đảm bảo rằng:

1. Bạn đã [tạo một paywall](create-paywall).
2. Bạn đã thêm paywall vào một [placement](placements).
3. Bạn đã [tải paywall và chuẩn bị view](react-native-get-pb-paywalls).

:::warning

Hướng dẫn này chỉ dành cho **paywall mới của Paywall Builder**, yêu cầu SDK v3.0 trở lên. Quy trình hiển thị paywall khác nhau tùy theo phiên bản Paywall Builder và paywall dùng Remote Config.

- Để hiển thị **paywall dùng Remote Config**, xem [Render paywall được thiết kế bằng Remote Config](present-remote-config-paywalls).

:::

Adapty React Native SDK cung cấp hai cách để hiển thị paywall:

- **React component**: Component được nhúng cho phép bạn tích hợp vào kiến trúc và hệ thống điều hướng của ứng dụng.

- **Hiển thị dạng modal**

## React component \{#react-component\}

:::note
Cách dùng **React component** yêu cầu SDK 3.14.0 trở lên.
:::

Để nhúng paywall vào cây component hiện có của bạn, hãy dùng component `AdaptyPaywallView` trực tiếp trong hệ thống phân cấp component React Native. Component được nhúng cho phép bạn tích hợp vào kiến trúc và hệ thống điều hướng của ứng dụng.

:::note
Trên Android, nếu paywall không kéo dài ra sau thanh trạng thái, một lớp phủ trực quan có thể xuất hiện ở phía trên cùng. Chúng tôi khuyên bạn nên tắt tính năng này cho các paywall của mình. Xem [Lớp phủ trực quan ở đầu paywall (Android)](#visual-overlay-at-the-top-of-the-paywall-android).
:::

```typescript showLineNumbers title="React Native (TSX)"

function MyPaywall({ paywall }) {
  const paywallParams = useMemo(() => ({
    loadTimeoutMs: 3000,
  }), []);

  const onCloseButtonPress = useCallback<EventHandlers['onCloseButtonPress']>(() => {}, []);
  const onProductSelected = useCallback<EventHandlers['onProductSelected']>((productId) => {}, []);
  const onPurchaseStarted = useCallback<EventHandlers['onPurchaseStarted']>((product) => {}, []);
  const onPurchaseCompleted = useCallback<EventHandlers['onPurchaseCompleted']>((purchaseResult, product) => {}, []);
  const onPurchaseFailed = useCallback<EventHandlers['onPurchaseFailed']>((error, product) => {}, []);
  const onRestoreStarted = useCallback<EventHandlers['onRestoreStarted']>(() => {}, []);
  const onRestoreCompleted = useCallback<EventHandlers['onRestoreCompleted']>((profile) => {}, []);
  const onRestoreFailed = useCallback<EventHandlers['onRestoreFailed']>((error) => {}, []);
  const onPaywallShown = useCallback<EventHandlers['onPaywallShown']>(() => {}, []);
  const onRenderingFailed = useCallback<EventHandlers['onRenderingFailed']>((error) => {}, []);
  const onLoadingProductsFailed = useCallback<EventHandlers['onLoadingProductsFailed']>((error) => {}, []);
  const onUrlPress = useCallback<EventHandlers['onUrlPress']>((url) => {}, []);
  const onCustomAction = useCallback<EventHandlers['onCustomAction']>((actionId) => {}, []);
  const onWebPaymentNavigationFinished = useCallback<EventHandlers['onWebPaymentNavigationFinished']>(() => {}, []);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      params={paywallParams}
      style={styles.paywall}
      onCloseButtonPress={onCloseButtonPress}
      onProductSelected={onProductSelected}
      onPurchaseStarted={onPurchaseStarted}
      onPurchaseCompleted={onPurchaseCompleted}
      onPurchaseFailed={onPurchaseFailed}
      onRestoreStarted={onRestoreStarted}
      onRestoreCompleted={onRestoreCompleted}
      onRestoreFailed={onRestoreFailed}
      onPaywallShown={onPaywallShown}
      onRenderingFailed={onRenderingFailed}
      onLoadingProductsFailed={onLoadingProductsFailed}
      onCustomAction={onCustomAction}
      onUrlPress={onUrlPress}
      onWebPaymentNavigationFinished={onWebPaymentNavigationFinished}
    />
  );
}
```

## Hiển thị dạng modal \{#modal-presentation\}

Để hiển thị paywall dưới dạng màn hình độc lập, hãy dùng phương thức `view.present()` trên `view` được tạo bởi phương thức [`createPaywallView`](react-native-get-pb-paywalls#fetch-the-view-configuration-of-paywall-designed-using-paywall-builder). Mỗi `view` chỉ có thể dùng một lần. Nếu bạn cần hiển thị paywall lại, hãy gọi `createPaywallView` thêm một lần nữa để tạo instance `view` mới.

:::warning
Việc tái sử dụng cùng một `view` mà không tạo lại là không được phép. Điều này sẽ dẫn đến lỗi `AdaptyUIError.viewAlreadyPresented`.
:::

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>
```typescript showLineNumbers title="React Native (TSX)"

const view = await createPaywallView(paywall);

// Optional: handle paywall events (close, purchase, restore, etc)
// view.setEventHandlers({ ... });

try {
  await view.present();
} catch (error) {
  // handle the error
}
```

:::important
Gọi `setEventHandlers` nhiều lần sẽ ghi đè các handler bạn đã cung cấp, thay thế cả handler mặc định lẫn handler đã đặt trước đó cho những sự kiện cụ thể đó.
:::

</TabItem>

<TabItem value="old" label="SDK version < 3.14" default>
```typescript showLineNumbers title="React Native (TSX)"

const view = await createPaywallView(paywall);

view.registerEventHandlers(); // handle close press, etc

try {
  await view.present();
} catch (error) {
  // handle the error
}
```

</TabItem>
</Tabs>

### Cấu hình kiểu trình bày trên iOS \{#configure-ios-presentation-style\}

Cấu hình cách paywall được hiển thị trên iOS bằng cách truyền tham số `iosPresentationStyle` vào phương thức `present()`. Tham số này chấp nhận giá trị `'full_screen'` (mặc định) hoặc `'page_sheet'`.

```typescript showLineNumbers
try {
  await view.present(iosPresentationStyle: 'page_sheet');
} catch (error) {
  // handle the error
}
```

## Dùng bộ đếm thời gian do nhà phát triển định nghĩa \{#use-developer-defined-timer\}

Để sử dụng bộ đếm thời gian do nhà phát triển định nghĩa trong ứng dụng di động, hãy dùng `timerId`, trong ví dụ này là `CUSTOM_TIMER_NY` — **Timer ID** của bộ đếm thời gian do nhà phát triển định nghĩa mà bạn đã đặt trong Adapty dashboard. Điều này đảm bảo ứng dụng của bạn cập nhật động bộ đếm thời gian với giá trị chính xác — như `13d 09h 03m 34s` (được tính bằng thời gian kết thúc của bộ đếm, chẳng hạn Ngày đầu năm mới, trừ đi thời gian hiện tại).

<Tabs>
<TabItem value="component" label="React component">
```typescript showLineNumbers title="React Native (TSX)"
const paywallParams = {
  customTimers: { 'CUSTOM_TIMER_NY': new Date(2025, 0, 1) }
};

<AdaptyPaywallView
  paywall={paywall}
  params={paywallParams}
  // ... your event handlers
/>
```
</TabItem>
<TabItem value="modal" label="Modal presentation">
```typescript showLineNumbers title="React Native (TSX)"
const customTimers = { 'CUSTOM_TIMER_NY': new Date(2025, 0, 1) };

const view = await createPaywallView(paywall, { customTimers });
```
</TabItem>
</Tabs>
Trong ví dụ này, `CUSTOM_TIMER_NY` là **Timer ID** của bộ đếm thời gian do nhà phát triển định nghĩa mà bạn đã đặt trong Adapty dashboard. `timerResolver` đảm bảo ứng dụng của bạn cập nhật động bộ đếm thời gian với giá trị chính xác — như `13d 09h 03m 34s` (được tính bằng thời gian kết thúc của bộ đếm, chẳng hạn Ngày đầu năm mới, trừ đi thời gian hiện tại).

## Hiển thị hộp thoại \{#show-dialog\}

Sử dụng phương thức này thay vì hộp thoại cảnh báo gốc khi một paywall view đang được hiển thị trên Android. Trên Android, các alert thông thường của RN xuất hiện phía sau paywall view, khiến người dùng không thể nhìn thấy chúng. Phương thức này đảm bảo hộp thoại được hiển thị đúng cách phía trên paywall trên tất cả các nền tảng.

```typescript showLineNumbers title="React Native (TSX)"
try {
  const action = await view.showDialog({
    title: 'Close paywall?',
    content: 'You will lose access to exclusive offers.',
    primaryActionTitle: 'Stay',
    secondaryActionTitle: 'Close',
  });
  
  if (action === 'secondary') {
    // User confirmed - close the paywall
    await view.dismiss();
  }
  // If primary - do nothing, user stays
} catch (error) {
  // handle error
}
```

## Thay thế một gói đăng ký bằng gói khác \{#replace-one-subscription-with-another\}

Khi người dùng cố gắng mua một gói đăng ký mới trong khi đang có gói đăng ký khác hoạt động trên Android, bạn có thể kiểm soát cách xử lý giao dịch mới bằng cách truyền tham số cập nhật gói đăng ký khi tạo paywall view. Để thay thế gói đăng ký hiện tại bằng gói mới, hãy dùng `productPurchaseParams` trong `createPaywallView` với các tham số `oldSubVendorProductId` và `prorationMode`.

```typescript showLineNumbers title="React Native (TSX)"

const productPurchaseParams = paywall.productIdentifiers.map((productId) => {
  let params = {};
  if (Platform.OS === 'android') {
    params.android = {
      subscriptionUpdateParams: {
        oldSubVendorProductId: 'PRODUCT_ID_OF_THE_CURRENT_ACTIVE_SUBSCRIPTION',
        prorationMode: 'with_time_proration',
      },
    };
  }
  return { productId, params };
});

const view = await createPaywallView(paywall, { productPurchaseParams });
```

## Khắc phục sự cố \{#troubleshooting\}

### Lớp phủ trực quan ở đầu paywall (Android) \{#visual-overlay-at-the-top-of-the-paywall-android\}

:::note
Cài đặt này được hỗ trợ từ React Native SDK 3.15.5 trở lên và chỉ khả dụng trong các dự án React Native thuần túy.

Nếu bạn đang dùng Expo managed workflow, bạn không thể thêm tài nguyên Android này trực tiếp. Để áp dụng cài đặt này, bạn phải tạo một Expo config plugin tùy chỉnh để thêm tài nguyên Android tương ứng và đăng ký nó trong app.config.js. Điều này là bắt buộc vì Expo quản lý dự án Android gốc cho bạn.
:::

Nếu `AdaptyPaywallView` không kéo dài ra sau thanh trạng thái, một lớp phủ trực quan vẫn có thể xuất hiện ở phía trên cùng. Để xóa nó, hãy thêm tài nguyên boolean sau vào ứng dụng của bạn:

1. Đi đến `android/app/src/main/res/values`. Nếu không có file `bools.xml`, hãy tạo file đó.

2. Thêm tài nguyên sau:

```xml
<resources>
    <bool name="adapty_paywall_enable_safe_area_paddings">false</bool>
</resources>
```

Lưu ý rằng các thay đổi này áp dụng cho tất cả paywall trong ứng dụng của bạn.

---


# File: react-native-handle-paywall-actions
---

---
title: "Xử lý hành động nút trong React Native SDK"
description: "Xử lý các hành động nút trên paywall trong React Native bằng Adapty để tối ưu hóa doanh thu ứng dụng."
---

Nếu bạn đang xây dựng paywall bằng Adapty paywall builder, việc thiết lập các nút đúng cách là rất quan trọng:

1. Thêm [nút trong paywall builder](paywall-buttons) và gán cho nó một hành động có sẵn hoặc tạo một ID hành động tùy chỉnh.
2. Viết code trong ứng dụng để xử lý từng hành động bạn đã gán.

Hướng dẫn này hướng dẫn cách xử lý các hành động tùy chỉnh và các hành động có sẵn trong code của bạn.

:::warning
**Chỉ các hành động mua hàng, khôi phục, đóng paywall và mở URL được xử lý tự động.** Tất cả các hành động nút khác đều cần được triển khai xử lý trong code ứng dụng.
:::

## Đóng paywall \{#close-paywalls\}

Để thêm nút đóng paywall:

1. Trong paywall builder, thêm một nút và gán cho nó hành động **Close**.
2. Trong code ứng dụng, triển khai handler cho hành động `close` để đóng paywall.

:::info
Trong React Native SDK, hành động `close` mặc định sẽ kích hoạt việc đóng paywall. Tuy nhiên, bạn có thể ghi đè hành vi này trong code nếu cần. Ví dụ: đóng một paywall có thể kích hoạt mở một paywall khác.
:::

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

Với React component, xử lý hành động đóng thông qua các prop handler sự kiện riêng lẻ:

```javascript

function MyPaywall({ paywall }) {
  const onCloseButtonPress = useCallback<EventHandlers['onCloseButtonPress']>(() => {
    // Handle close button press - navigate away or hide component
    navigation.goBack();
  }, [navigation]);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      style={styles.container}
      onCloseButtonPress={onCloseButtonPress}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Với modal presentation, triển khai handler đóng:

```javascript

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
    onCloseButtonPress() {
        return true; // allow paywall closing
    }
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14" default>

Với SDK version < 3.14, chỉ hỗ trợ modal presentation:

```javascript

const view = await createPaywallView(paywall);

const unsubscribe = view.registerEventHandlers({
    onCloseButtonPress() {
        return true; // allow paywall closing
    }
});
```

</TabItem>
</Tabs>

## Mở URL từ paywall \{#open-urls-from-paywalls\}

:::tip
Nếu bạn muốn thêm một nhóm liên kết (ví dụ: điều khoản sử dụng và khôi phục mua hàng), hãy thêm một phần tử **Link** trong paywall builder và xử lý nó giống như các nút có hành động **Open URL**.
:::

Để thêm nút mở liên kết từ paywall (ví dụ: **Terms of use** hoặc **Privacy policy**):

1. Trong paywall builder, thêm một nút, gán cho nó hành động **Open URL** và nhập URL bạn muốn mở.
2. Trong code ứng dụng, triển khai handler cho hành động `openUrl` để mở URL nhận được trong trình duyệt.

:::info
Trong React Native SDK, hành động `openUrl` mặc định sẽ kích hoạt việc mở URL. Tuy nhiên, bạn có thể ghi đè hành vi này trong code nếu cần.
:::

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

Với React component, xử lý việc mở URL thông qua prop handler sự kiện:

```javascript

function MyPaywall({ paywall }) {
  const onUrlPress = useCallback<EventHandlers['onUrlPress']>((url) => {
    Linking.openURL(url);
  }, []);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      style={styles.container}
      onUrlPress={onUrlPress}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Với modal presentation, triển khai handler URL:

```javascript

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
    onUrlPress(url) {
        Linking.openURL(url);
        return false; // Keep paywall open
    },
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14" default>

Với SDK version < 3.14, chỉ hỗ trợ modal presentation:

```javascript

const view = await createPaywallView(paywall);

const unsubscribe = view.registerEventHandlers({
    onUrlPress(url) {
        Linking.openURL(url);
        return false; // Keep paywall open
    },
});
```

</TabItem>
</Tabs>

## Đăng nhập vào ứng dụng \{#log-into-the-app\}

Để thêm nút cho phép người dùng đăng nhập vào ứng dụng:

1. Trong paywall builder, thêm một nút và gán cho nó hành động **Login**.
2. Trong code ứng dụng, triển khai handler cho hành động `login` để xác định người dùng.

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

Với React component, xử lý đăng nhập thông qua prop handler sự kiện:

```javascript

function MyPaywall({ paywall }) {
  const onCustomAction = useCallback<EventHandlers['onCustomAction']>((actionId) => {
    if (actionId === 'login') {
      navigation.navigate('Login');
    }
  }, [navigation]);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      style={styles.container}
      onCustomAction={onCustomAction}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Với modal presentation, triển khai handler đăng nhập:

```javascript

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
    onCustomAction(actionId) {
        if (actionId === 'login') {
            navigation.navigate('Login');
        }
    }
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14" default>

Với SDK version < 3.14, chỉ hỗ trợ modal presentation:

```javascript

const view = await createPaywallView(paywall);

const unsubscribe = view.registerEventHandlers({
    onCustomAction(actionId) {
        if (actionId === 'login') {
            navigation.navigate('Login');
        }
    }
});
```

</TabItem>
</Tabs>

## Xử lý hành động tùy chỉnh \{#handle-custom-actions\}

Để thêm nút xử lý các hành động khác:

1. Trong paywall builder, thêm một nút, gán cho nó hành động **Custom** và đặt một ID cho nó.
2. Trong code ứng dụng, triển khai handler cho ID hành động bạn đã tạo.

Ví dụ: nếu bạn có thêm một bộ ưu đãi gói đăng ký hoặc sản phẩm mua một lần, bạn có thể thêm nút để hiển thị một paywall khác:

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

Với React component, xử lý các hành động tùy chỉnh thông qua prop handler sự kiện:

```javascript

function MyPaywall({ paywall }) {
  const onCustomAction = useCallback<EventHandlers['onCustomAction']>((actionId) => {
    if (actionId === 'openNewPaywall') {
      // Display another paywall
    }
  }, []);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      style={styles.container}
      onCustomAction={onCustomAction}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Với modal presentation, triển khai các handler hành động tùy chỉnh:

```javascript
const unsubscribe = view.setEventHandlers({
    onCustomAction(actionId) {
        if (actionId === 'openNewPaywall') {
            // Display another paywall
        }
    },
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14" default>

Với SDK version < 3.14, chỉ hỗ trợ modal presentation:

```javascript
const unsubscribe = view.registerEventHandlers({
    onCustomAction(actionId) {
        if (actionId === 'openNewPaywall') {
            // Display another paywall
        }
    },
});
```

</TabItem>
</Tabs>

---


# File: react-native-handling-events-1
---

---
title: "React Native - Xử lý sự kiện paywall"
description: "Xử lý các sự kiện gói đăng ký trong React Native với Adapty SDK."
---

:::important
Hướng dẫn này đề cập đến việc xử lý sự kiện cho các giao dịch mua, khôi phục, chọn sản phẩm và hiển thị paywall. Bạn cũng cần triển khai xử lý các nút bấm (đóng paywall, mở liên kết, v.v.). Xem [hướng dẫn xử lý hành động nút bấm](react-native-handle-paywall-actions) để biết thêm chi tiết.
:::

Các paywall được cấu hình bằng [Paywall Builder](adapty-paywall-builder) không cần thêm code để thực hiện và khôi phục giao dịch mua. Tuy nhiên, chúng tạo ra một số sự kiện mà ứng dụng của bạn có thể phản hồi. Những sự kiện đó bao gồm các lần nhấn nút (nút đóng, URL, chọn sản phẩm, v.v.) cũng như thông báo về các hành động liên quan đến giao dịch mua trên paywall. Tìm hiểu cách phản hồi các sự kiện này bên dưới.

:::warning
Hướng dẫn này chỉ dành cho **paywall Paywall Builder mới** yêu cầu Adapty SDK v3.0 trở lên.
:::

Để kiểm soát hoặc theo dõi các quy trình diễn ra trên màn hình paywall trong ứng dụng di động của bạn, hãy triển khai các event handler:

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

Với React component, bạn xử lý các sự kiện thông qua các prop event handler riêng lẻ trong component `AdaptyPaywallView`:

```typescript showLineNumbers title="React Native (TSX)"

function MyPaywall({ paywall }) {
  const onCloseButtonPress = useCallback<EventHandlers['onCloseButtonPress']>(() => {}, []);
  const onProductSelected = useCallback<EventHandlers['onProductSelected']>((productId) => {}, []);
  const onPurchaseStarted = useCallback<EventHandlers['onPurchaseStarted']>((product) => {}, []);
  const onPurchaseCompleted = useCallback<EventHandlers['onPurchaseCompleted']>((purchaseResult, product) => {}, []);
  const onPurchaseFailed = useCallback<EventHandlers['onPurchaseFailed']>((error, product) => {}, []);
  const onRestoreStarted = useCallback<EventHandlers['onRestoreStarted']>(() => {}, []);
  const onRestoreCompleted = useCallback<EventHandlers['onRestoreCompleted']>((profile) => {}, []);
  const onRestoreFailed = useCallback<EventHandlers['onRestoreFailed']>((error) => {}, []);
  const onPaywallShown = useCallback<EventHandlers['onPaywallShown']>(() => {}, []);
  const onRenderingFailed = useCallback<EventHandlers['onRenderingFailed']>((error) => {}, []);
  const onLoadingProductsFailed = useCallback<EventHandlers['onLoadingProductsFailed']>((error) => {}, []);
  const onUrlPress = useCallback<EventHandlers['onUrlPress']>((url) => {
    Linking.openURL(url);
  }, []);
  const onCustomAction = useCallback<EventHandlers['onCustomAction']>((actionId) => {}, []);
  const onWebPaymentNavigationFinished = useCallback<EventHandlers['onWebPaymentNavigationFinished']>(() => {}, []);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      style={styles.container}
      onCloseButtonPress={onCloseButtonPress}
      onProductSelected={onProductSelected}
      onPurchaseStarted={onPurchaseStarted}
      onPurchaseCompleted={onPurchaseCompleted}
      onPurchaseFailed={onPurchaseFailed}
      onRestoreStarted={onRestoreStarted}
      onRestoreCompleted={onRestoreCompleted}
      onRestoreFailed={onRestoreFailed}
      onPaywallShown={onPaywallShown}
      onRenderingFailed={onRenderingFailed}
      onLoadingProductsFailed={onLoadingProductsFailed}
      onUrlPress={onUrlPress}
      onCustomAction={onCustomAction}
      onWebPaymentNavigationFinished={onWebPaymentNavigationFinished}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Với modal presentation, hãy triển khai phương thức event handler.

:::important
Gọi `setEventHandlers` nhiều lần sẽ ghi đè các handler bạn đã cung cấp, thay thế cả handler mặc định lẫn các handler đã thiết lập trước đó cho những sự kiện cụ thể đó.
:::

```javascript showLineNumbers title="React Native (TSX)"

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
  onCloseButtonPress() {
    return true;
  },
  onAndroidSystemBack() {
    return true;
  },
  onPurchaseCompleted(purchaseResult, product) {
    return purchaseResult.type !== 'user_cancelled';
  },
  onPurchaseStarted(product) { /***/},
  onPurchaseFailed(error) { /***/ },
  onRestoreCompleted(profile) { /***/ },
  onRestoreFailed(error, product) { /***/ },
  onProductSelected(productId) { /***/},
  onRenderingFailed(error) { /***/ },
  onLoadingProductsFailed(error) { /***/ },
  onUrlPress(url) {
      Linking.openURL(url);
      return false; // Keep paywall open
  },
  onPaywallShown() { /***/ },
  onPaywallClosed() { /***/ },
  onWebPaymentNavigationFinished() { /***/ },  
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14" default>

Với SDK version < 3.14, chỉ hỗ trợ modal presentation:

```javascript showLineNumbers title="React Native (TSX)"

const view = await createPaywallView(paywall);

const unsubscribe = view.registerEventHandlers({
  onCloseButtonPress() {
    return true;
  },
  onAndroidSystemBack() {
    return true;
  },
  onPurchaseCompleted(purchaseResult, product) {
    return purchaseResult.type !== 'user_cancelled';
  },
  onPurchaseStarted(product) { /***/},
  onPurchaseFailed(error, product) { /***/ },
  onRestoreCompleted(profile) { /***/ },
  onRestoreFailed(error) { /***/ },
  onProductSelected(productId) { /***/},
  onRenderingFailed(error) { /***/ },
  onLoadingProductsFailed(error) { /***/ },
  onUrlPress(url) {
      Linking.openURL(url);
      return false; // Keep paywall open
  },
  onPaywallShown() { /***/ },
  onPaywallClosed() { /***/ },
  onWebPaymentNavigationFinished() { /***/ },
});
```

</TabItem>
</Tabs>

<Details>
<summary>Ví dụ về sự kiện (Nhấn để mở rộng)</summary>

```javascript
// onCloseButtonPress
{
  "event": "close_button_press"
}

// onAndroidSystemBack
{
  "event": "android_system_back"
}

// onUrlPress
{
  "event": "url_press",
  "url": "https://example.com/terms"
}

// onCustomAction
{
  "event": "custom_action",
  "actionId": "login"
}

// onProductSelected
{
  "event": "product_selected",
  "productId": "premium_monthly"
}

// onPurchaseStarted
{
  "event": "purchase_started",
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseCompleted - Success
{
  "event": "purchase_completed",
  "purchaseResult": {
    "type": "success",
    "profile": {
      "accessLevels": {
        "premium": {
          "id": "premium",
          "isActive": true,
          "expiresAt": "2024-02-15T10:30:00Z"
        }
      }
    }
  },
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseCompleted - Cancelled
{
  "event": "purchase_completed",
  "purchaseResult": {
    "type": "user_cancelled"
  },
  "product": {
    "vendorProductId": "premium_monthly",
    "localizedTitle": "Premium Monthly",
    "localizedDescription": "Premium subscription for 1 month",
    "localizedPrice": "$9.99",
    "price": 9.99,
    "currencyCode": "USD"
  }
}

// onPurchaseFailed
{
  "event": "purchase_failed",
  "error": {
    "code": "purchase_failed",
    "message": "Purchase failed due to insufficient funds",
    "details": {
      "underlyingError": "Insufficient funds in account"
    },
    "product": {
        "vendorProductId": "premium_monthly",
            "localizedTitle": "Premium Monthly",
            "localizedDescription": "Premium subscription for 1 month",
            "localizedPrice": "$9.99",
            "price": 9.99,
            "currencyCode": "USD"
    }
  }
}

// onRestoreCompleted
{
  "event": "restore_completed",
  "profile": {
    "accessLevels": {
      "premium": {
        "id": "premium",
        "isActive": true,
        "expiresAt": "2024-02-15T10:30:00Z"
      }
    },
    "subscriptions": [
      {
        "vendorProductId": "premium_monthly",
        "isActive": true,
        "expiresAt": "2024-02-15T10:30:00Z"
      }
    ]
  }
}

// onRestoreFailed
{
  "event": "restore_failed",
  "error": {
    "code": "restore_failed",
    "message": "Purchase restoration failed",
    "details": {
      "underlyingError": "No previous purchases found"
    }
  }
}

// onRenderingFailed
{
  "event": "rendering_failed",
  "error": {
    "code": "rendering_failed",
    "message": "Failed to render paywall interface",
    "details": {
      "underlyingError": "Invalid paywall configuration"
    }
  }
}

// onLoadingProductsFailed
{
  "event": "loading_products_failed",
  "error": {
    "code": "products_loading_failed",
    "message": "Failed to load products from the server",
    "details": {
      "underlyingError": "Network timeout"
    }
  }
}

// onPaywallShown
{
  "event": "paywall_shown"
}

// onPaywallClosed
{
  "event": "paywall_closed"
}

// onWebPaymentNavigationFinished
{
  "event": "web_payment_navigation_finished"
}
```
</Details>

Bạn có thể đăng ký những event handler mà bạn cần và bỏ qua những cái không cần. Trong trường hợp đó, các event listener không dùng đến sẽ không được tạo. Không có event handler nào là bắt buộc.

Các event handler trả về một giá trị boolean. Nếu trả về `true`, quá trình hiển thị được coi là hoàn tất, do đó màn hình paywall sẽ đóng lại và các event listener cho view này sẽ bị xóa.

Một số event handler có hành vi mặc định mà bạn có thể ghi đè nếu cần:
- `onCloseButtonPress`: đóng paywall khi nhấn nút đóng.
- `onUrlPress`: mở URL được nhấn và giữ paywall mở.
- `onAndroidSystemBack` (chỉ dành cho modal presentation): đóng paywall khi nhấn nút **Back**.
- `onRestoreCompleted`: đóng paywall sau khi khôi phục thành công.
- `onPurchaseCompleted`: đóng paywall trừ khi người dùng hủy.
- `onRenderingFailed`: đóng paywall nếu quá trình hiển thị của nó thất bại.

### Các event handler \{#event-handlers\}

| Event handler                      | Mô tả                                                                                                                                                                                                                                                                                                      |
|:-----------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **onCustomAction**                 | Được gọi khi người dùng thực hiện một hành động tùy chỉnh, ví dụ: nhấn vào [nút tùy chỉnh](paywall-buttons).                                                                                                                                                                                              |
| **onUrlPress**                     | Được gọi khi người dùng nhấn vào một URL trong paywall của bạn.                                                                                                                                                                                                                                            |
| **onAndroidSystemBack**            | Chỉ dành cho modal presentation: Được gọi khi người dùng nhấn nút **Back** hệ thống của Android.                                                                                                                                                                                                          |
| **onCloseButtonPress**             | Được gọi khi nút đóng hiển thị và người dùng nhấn vào nó. Nên đóng màn hình paywall trong handler này.                                                                                                                                                                                                    |
| **onPurchaseCompleted**            | Được gọi khi giao dịch mua hoàn thành, dù thành công, bị người dùng hủy, hay đang chờ phê duyệt. Trong trường hợp mua thành công, nó cung cấp `AdaptyProfile` đã được cập nhật. Việc người dùng hủy và thanh toán đang chờ xử lý (ví dụ: cần phê duyệt của phụ huynh) sẽ kích hoạt sự kiện này, không phải `onPurchaseFailed`. |
| **onPurchaseStarted**              | Được gọi khi người dùng nhấn nút hành động "Purchase" để bắt đầu quá trình mua.                                                                                                                                                                                                                           |
| **onPurchaseFailed**               | Được gọi khi giao dịch mua thất bại do lỗi (ví dụ: hạn chế thanh toán, sản phẩm không hợp lệ, lỗi mạng, lỗi xác minh giao dịch). Không được gọi khi người dùng hủy hoặc thanh toán đang chờ xử lý, những trường hợp này sẽ kích hoạt `onPurchaseCompleted`.                                             |
| **onRestoreStarted**               | Được gọi khi người dùng bắt đầu quá trình khôi phục giao dịch mua.                                                                                                                                                                                                                                        |
| **onRestoreCompleted**             | Được gọi khi khôi phục giao dịch mua thành công và cung cấp `AdaptyProfile` đã được cập nhật. Nên đóng màn hình nếu người dùng có `accessLevel` yêu cầu. Tham khảo chủ đề [Trạng thái gói đăng ký](react-native-listen-subscription-changes) để biết cách kiểm tra.                                       |
| **onRestoreFailed**                | Được gọi khi quá trình khôi phục thất bại và cung cấp `AdaptyError`.                                                                                                                                                                                                                                      |
| **onProductSelected**              | Được gọi khi bất kỳ sản phẩm nào trong paywall view được chọn, cho phép bạn theo dõi những gì người dùng chọn trước khi mua.                                                                                                                                                                              |
| **onRenderingFailed**              | Được gọi khi xảy ra lỗi trong quá trình hiển thị view và cung cấp `AdaptyError`. Những lỗi như vậy không nên xảy ra, vì vậy nếu bạn gặp phải, vui lòng thông báo cho chúng tôi.                                                                                                                          |
| **onLoadingProductsFailed**        | Được gọi khi tải sản phẩm thất bại và cung cấp `AdaptyError`. Nếu bạn chưa đặt `prefetchProducts: true` khi tạo view, AdaptyUI sẽ tự động lấy các đối tượng cần thiết từ server.                                                                                                                          |
| **onPaywallShown**                 | Được gọi khi paywall hiển thị cho người dùng. Trên iOS, cũng được gọi khi người dùng nhấn vào [nút web paywall](web-paywall#step-2a-add-a-web-purchase-button) bên trong paywall và web paywall mở trong trình duyệt trong ứng dụng.                                                                       |
| **onPaywallClosed**                | Chỉ dành cho modal presentation: Được gọi khi người dùng đóng paywall. Trên iOS, cũng được gọi khi một [web paywall](web-paywall#step-2a-add-a-web-purchase-button) được mở từ paywall trong trình duyệt trong ứng dụng biến mất khỏi màn hình.                                                            |
| **onWebPaymentNavigationFinished** | Được gọi sau khi cố gắng mở [web paywall](web-paywall) để mua, dù thành công hay thất bại.                                                                                                                                                                                                                |

---


# File: react-native-use-fallback-paywalls-expo
---

---
title: "Sử dụng fallback paywall trong dự án Expo"
description: "Cấu hình fallback paywall trong dự án Expo React Native thông qua config plugin react-native-adapty."
---

:::important
Hướng dẫn này áp dụng cho **dự án Expo**.
Nếu bạn đang dùng **React Native thuần (không dùng Expo)**, hãy xem [hướng dẫn fallback cho React Native thuần](react-native-use-fallback-paywalls-pure).
:::

Để duy trì trải nghiệm người dùng mượt mà, điều quan trọng là phải thiết lập [paywall dự phòng](/fallback-paywalls) cho các flow, [paywall](paywalls) và [onboarding](onboardings) của bạn. Biện pháp phòng ngừa này giúp mở rộng khả năng của ứng dụng trong trường hợp mất kết nối internet một phần hoặc hoàn toàn.

* **Nếu ứng dụng không thể kết nối đến máy chủ Adapty:**

    Ứng dụng vẫn có thể hiển thị flow hoặc paywall dự phòng, và truy cập cấu hình onboarding đã lưu cục bộ.

* **Nếu ứng dụng không thể kết nối internet:**

    Ứng dụng vẫn có thể hiển thị flow hoặc paywall dự phòng. Onboarding chứa nội dung từ xa và cần có kết nối internet để hoạt động.

:::important
Trước khi thực hiện các bước trong hướng dẫn này, hãy [tải xuống](/local-fallback-paywalls) các file cấu hình dự phòng từ Adapty.
:::

SDK Adapty đọc file fallback từ bundle **native** — một resource iOS bên trong package `.app`, hoặc một entry trong `android/app/src/main/assets/`. Trong dự án Expo, lệnh `npx expo prebuild --clean` sẽ tái tạo lại các thư mục đó sau mỗi lần chạy, nên bạn không thể đặt file vào thủ công. Config plugin `react-native-adapty` sẽ tự động tích hợp file vào bundle native cho bạn.

:::tip
Một ví dụ hoàn chỉnh đã được cung cấp trong [ứng dụng mẫu `FocusJournalExpo`](https://github.com/adaptyteam/AdaptySDK-React-Native/tree/master/examples/FocusJournalExpo).
:::

## Cấu hình \{#configuration\}

1. Đặt các file JSON fallback ở bất kỳ đâu trong dự án — thường là cạnh các asset khác:

   ```
   <your-project>/
   └── assets/
       ├── ios_fallback.json
       └── android_fallback.json
   ```

2. Thêm tùy chọn `fallbackFile` vào mục `react-native-adapty` trong `app.json` (hoặc `app.config.js`). Mỗi key của platform là tùy chọn — chỉ cần cấu hình những platform bạn cần:

   ```json title="app.json"
   {
     "expo": {
       "plugins": [
         [
           "react-native-adapty",
           {
             "fallbackFile": {
               "ios": "./assets/ios_fallback.json",
               "android": "./assets/android_fallback.json"
             }
           }
         ]
       ]
     }
   }
   ```

   :::note
   Adapty xuất file JSON fallback khác nhau cho từng platform — ID sản phẩm của Apple trên iOS, ID sản phẩm Google Play trên Android. Hãy trỏ từng platform đến file của riêng nó.
   :::

3. Tái tạo lại các dự án native:

   ```sh title="Shell"
   npx expo prebuild
   ```

   Plugin sẽ thêm file iOS vào bundle resources của dự án Xcode và sao chép file Android vào `android/app/src/main/assets/`. Output của prebuild sẽ có các dòng như sau:

   ```
   [react-native-adapty] Registered ios_fallback.json as iOS bundle resource
   [react-native-adapty] Copied android_fallback.json to android assets/
   ```

4. Đăng ký file với SDK lúc runtime:

   ```typescript showLineNumbers title="App.tsx"
   import { adapty } from 'react-native-adapty';

   await adapty.activate('PUBLIC_SDK_KEY');

   await adapty.setFallback({
     ios: { fileName: 'ios_fallback.json' },
     android: { relativeAssetPath: 'android_fallback.json' },
   });
   ```

   Tên file truyền vào `setFallback` phải khớp với tên cơ sở (basename) của các file đã cấu hình trong `fallbackFile`.

:::important
`setFallback` phải chạy trước khi SDK fetch bất kỳ paywall hoặc onboarding nào.
:::

## Kiểm tra \{#verification\}

Sau khi chạy `npx expo prebuild`, hãy kiểm tra cả hai platform:

- **Android**: Liệt kê nội dung của `android/app/src/main/assets/`. File đã cấu hình trong `fallbackFile.android` phải có mặt ở đây, và tên file chỉ dành cho iOS không được xuất hiện ở đây.
- **iOS**: Tìm kiếm tên file iOS trong `ios/<ProjectName>.xcodeproj/project.pbxproj`. Nó phải xuất hiện trong `PBXFileReference`, nhóm `Resources`, và `PBXResourcesBuildPhase`. Tên file chỉ dành cho Android không được xuất hiện trong `project.pbxproj`.

---


# File: react-native-use-fallback-paywalls-pure
---

---
title: "Sử dụng paywall dự phòng trong dự án React Native thuần"
description: "Cấu hình paywall dự phòng trong dự án React Native thuần (không dùng Expo)."
---

:::important
Hướng dẫn này á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 xem [hướng dẫn fallback cho Expo](react-native-use-fallback-paywalls-expo).
:::

Để duy trì trải nghiệm người dùng mượt mà, điều quan trọng là phải thiết lập [paywall dự phòng](/fallback-paywalls) cho các flow, [paywall](paywalls) và [onboarding](onboardings) của bạn. Biện pháp phòng ngừa này giúp mở rộng khả năng của ứng dụng trong trường hợp mất kết nối internet một phần hoặc hoàn toàn.

* **Nếu ứng dụng không thể kết nối đến máy chủ Adapty:**

    Ứng dụng vẫn có thể hiển thị flow hoặc paywall dự phòng, và truy cập cấu hình onboarding đã lưu cục bộ.

* **Nếu ứng dụng không thể kết nối internet:**

    Ứng dụng vẫn có thể hiển thị flow hoặc paywall dự phòng. Onboarding chứa nội dung từ xa và cần có kết nối internet để hoạt động.

:::important
Trước khi thực hiện các bước trong hướng dẫn này, hãy [tải xuống](/local-fallback-paywalls) các file cấu hình dự phòng từ Adapty.
:::

## Cấu hình \{#configuration\}

### Android \{#android\}

1. Thêm file cấu hình dự phòng vào ứng dụng của bạn. Chọn một trong các thư mục sau:
   * **android/app/src/main/assets/**
   * **android/app/src/main/res/raw/**

      Lưu ý: Thư mục `res/raw` có quy tắc đặt tên file đặc biệt (bắt đầu bằng chữ cái, không dùng chữ hoa, không dùng ký tự đặc biệt ngoại trừ dấu gạch dưới, và không có dấu cách trong tên file).

2. Cập nhật thuộc tính `android` của hằng số `FileLocation`:
   * Nếu file nằm trong thư mục `assets`, truyền đường dẫn file tương đối so với thư mục đó.
   * Nếu file nằm trong thư mục `res/raw`, truyền tên file không kèm phần mở rộng.

### iOS \{#ios\}

1. Thêm file JSON dự phòng vào bundle dự án: mở menu **File** trong XCode và chọn tùy chọn **Add Files to "YourProjectName"**.
2. Truyền tên file cấu hình vào thuộc tính `ios` của hằng số `FileLocation`.

## Ví dụ \{#example\}

<Tabs groupId="current-os" queryString> <TabItem value="current" label="Hiện tại (v3.8+)" default>
```typescript showLineNumbers
//after v3.8
const fileLocation = {
  ios: {
    fileName: 'ios_fallback.json'
  },
  android: {
    //if the file is located in 'android/app/src/main/assets/'
    relativeAssetPath: 'android_fallback.json'
  }
}
await adapty.setFallback(fileLocation);
```
</TabItem>
<TabItem value="old" label="Cũ (trước v3.8)" default>
```typescript showLineNumbers
//Legacy (before v3.8)
const paywallsLocation = {
  ios: {
    fileName: 'ios_fallback.json'
  },
  android: {
    //if the file is located in 'android/app/src/main/assets/'
    relativeAssetPath: 'android_fallback.json'
  }
}
await adapty.setFallbackPaywalls(paywallsLocation);
```
</TabItem>
</Tabs>

Các tham số:

| Tham số            | Mô tả                                              |
| :------------------- | :------------------------------------------------------- |
| **fileLocation** | Đối tượng đại diện cho vị trí của file cấu hình dự phòng. |

---


# File: react-native-localizations-and-locale-codes
---

---
title: "Sử dụng bản địa hóa và mã ngôn ngữ trong React Native SDK"
description: "Tìm hiểu cách bản địa hóa paywall trong ứng dụng React Native của bạn với Adapty SDK."
---

## Tại sao điều này quan trọng \{#why-this-is-important\}

Có một vài trường hợp mà mã ngôn ngữ (locale code) trở nên cần thiết — ví dụ, khi bạn muốn lấy đúng paywall phù hợp với bản địa hóa hiện tại của ứng dụng.

Vì mã ngôn ngữ khá phức tạp và có thể khác nhau tùy nền tảng, chúng tôi sử dụng một chuẩn nội bộ thống nhất cho tất cả các nền tảng được hỗ trợ. Tuy nhiên, chính vì sự phức tạp đó, bạn cần hiểu rõ mình đang gửi gì lên server để nhận đúng bản địa hóa, và điều gì xảy ra tiếp theo — để đảm bảo bạn luôn nhận được kết quả như mong đợi.

## Chuẩn mã ngôn ngữ tại Adapty \{#locale-code-standard-at-adapty\}

Adapty sử dụng chuẩn [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) với một số điều chỉnh nhỏ: mỗi mã gồm các subtag viết thường, phân cách bằng dấu gạch ngang. Ví dụ: `en` (tiếng Anh), `pt-br` (tiếng Bồ Đào Nha (Brazil)), `zh` (tiếng Trung giản thể), `zh-hant` (tiếng Trung phồn thể).

## Khớp mã ngôn ngữ \{#locale-code-matching\}

Khi Adapty nhận được yêu cầu từ SDK phía client kèm theo mã ngôn ngữ và bắt đầu tìm kiếm bản địa hóa tương ứng của paywall, quá trình diễn ra như sau:

1. Chuỗi locale đầu vào được chuyển thành chữ thường và tất cả dấu gạch dưới (`_`) được thay bằng dấu gạch ngang (`-`)
2. Hệ thống tìm kiếm bản địa hóa có mã ngôn ngữ khớp hoàn toàn
3. Nếu không tìm thấy, hệ thống lấy phần chuỗi trước dấu gạch ngang đầu tiên (`pt` từ `pt-br`) và tìm kiếm bản địa hóa khớp
4. Nếu vẫn không tìm thấy, hệ thống trả về bản địa hóa mặc định `en`

Nhờ vậy, một thiết bị iOS gửi `'pt_BR'`, một thiết bị Android gửi `pt-BR`, và một thiết bị khác gửi `pt-br` đều nhận được cùng kết quả.

## Cách triển khai bản địa hóa được khuyến nghị \{#implementing-localizations-recommended-way\}

Nếu bạn đang tìm hiểu về bản địa hóa, khả năng cao bạn đã làm việc với các file chuỗi đã được bản địa hóa trong dự án của mình. Trong trường hợp đó, chúng tôi khuyến nghị bạn đặt một cặp key-value chứa mã ngôn ngữ Adapty mong muốn vào từng file tương ứng. Sau đó trích xuất giá trị của key đó khi gọi SDK, như sau:

```javascript showLineNumbers
// 1. Modify your localization files (e.g., using react-i18next)

/*
en.json
*/
{
  "adapty_paywalls_locale": "en"
}

/*
es.json
*/
{
  "adapty_paywalls_locale": "es"
}

/*
pt-BR.json
*/
{
  "adapty_paywalls_locale": "pt-br"
}

// 2. Extract and use the locale code

const MyComponent = () => {
  const { t } = useTranslation();
  
  const fetchPaywall = async () => {
    const locale = t('adapty_paywalls_locale');
    // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
    const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
  };
};
```

Cách này giúp bạn kiểm soát hoàn toàn bản địa hóa nào sẽ được lấy về cho từng người dùng của ứng dụng.

## Cách triển khai bản địa hóa thay thế \{#implementing-localizations-the-other-way\}

Bạn cũng có thể đạt được kết quả tương tự (nhưng không hoàn toàn giống) mà không cần định nghĩa rõ ràng mã ngôn ngữ cho từng bản địa hóa. Cách này đồng nghĩa với việc trích xuất mã ngôn ngữ từ thiết bị, chẳng hạn thông qua [`react-native-localize`](https://github.com/zoontek/react-native-localize):

```javascript showLineNumbers

const fetchPaywall = async () => {
  // getLocales() returns the user's preferred locales in BCP-47 format (e.g., 'en-US', 'pt-BR')
  const locale = RNLocalize.getLocales()[0].languageTag;
  // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
  const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
};
```

Lưu ý rằng chúng tôi không khuyến nghị cách tiếp cận này vì một số lý do:

1. Trên iOS, ngôn ngữ ưu tiên và locale khu vực hiện tại là hai thứ khác nhau. Nếu bạn muốn bản địa hóa được chọn đúng, bạn phải dựa vào logic xử lý của Apple — vốn hoạt động tự động khi bạn dùng cách khuyến nghị với file chuỗi đã bản địa hóa — hoặc tự tái tạo lại logic đó.
2. Locale của thiết bị có thể không khớp với bất kỳ bản địa hóa nào bạn đã cấu hình trong Adapty. Trong trường hợp đó, SDK sẽ fallback về kết quả khớp theo subtag đầu tiên hoặc cuối cùng là `en` — điều này có thể không phải ngôn ngữ mà bạn muốn mặc định cho người dùng đó.

Nếu bạn vẫn quyết định dùng cách này — hãy đảm bảo bạn đã xử lý tất cả các trường hợp liên quan.

---


# File: react-native-web-paywall
---

---
title: "Triển khai web paywall"
description: "Tìm hiểu cách triển khai web paywall trong ứng dụng React Native với Adapty SDK."
---

:::important
Trước khi bắt đầu, hãy đảm bảo bạn đã [cấu hình web paywall trong dashboard](web-paywall) và cài đặt Adapty SDK phiên bản 3.6.1 trở lên.
:::

## Mở web paywall \{#open-web-paywalls\}

Nếu bạn đang làm việc với paywall tự phát triển, bạn cần xử lý web paywall bằng phương thức SDK. Phương thức `.openWebPaywall`:
1. Tạo URL duy nhất giúp Adapty liên kết paywall cụ thể đang hiển thị cho một người dùng cụ thể với trang web họ được chuyển hướng đến.
2. Theo dõi khi người dùng quay lại ứng dụng rồi gọi `.getProfile` theo chu kỳ ngắn để xác định xem quyền truy cập của hồ sơ người dùng có được cập nhật hay không.

Như vậy, nếu thanh toán thành công và quyền truy cập được cập nhật, gói đăng ký sẽ kích hoạt trong ứng dụng gần như ngay lập tức.

```typescript showLineNumbers title="React Native (TSX)"

try {
    await adapty.openWebPaywall(product);
} catch (error) {
    console.warn('Failed to open web paywall:', error);
}
```

:::note
Có hai phiên bản của phương thức `openWebPaywall`:
1. `openWebPaywall(product)` tạo URL theo paywall và đồng thời thêm dữ liệu sản phẩm vào URL.
2. `openWebPaywall(paywall)` tạo URL theo paywall mà không thêm dữ liệu sản phẩm vào URL. Dùng phiên bản này khi các sản phẩm trong Adapty paywall khác với các sản phẩm trong web paywall.
:::

#### Xử lý lỗi \{#handle-errors\}

| Lỗi                                     | Mô tả                                                           | Hành động khuyến nghị                                                              |
|-----------------------------------------|-----------------------------------------------------------------|------------------------------------------------------------------------------------|
| AdaptyError.paywallWithoutPurchaseUrl   | Paywall chưa được cấu hình URL mua hàng web                     | Kiểm tra xem paywall đã được cấu hình đúng trong Adapty Dashboard chưa             |
| AdaptyError.productWithoutPurchaseUrl   | Sản phẩm chưa có URL mua hàng web                               | Xác minh cấu hình sản phẩm trong Adapty Dashboard                                  |
| AdaptyError.failedOpeningWebPaywallUrl  | Không mở được URL trong trình duyệt                             | Kiểm tra cài đặt thiết bị hoặc cung cấp phương thức mua hàng thay thế              |
| AdaptyError.failedDecodingWebPaywallUrl | Không mã hóa đúng các tham số trong URL                        | Xác minh các tham số URL hợp lệ và được định dạng đúng                             |

## Mở web paywall trong trình duyệt trong ứng dụng \{#open-web-paywalls-in-an-in-app-browser\}

:::important
Mở web paywall trong trình duyệt trong ứng dụng được hỗ trợ từ Adapty SDK v3.15 trở lên.
:::

Theo mặc định, web paywall mở trong trình duyệt bên ngoài.

Để mang lại trải nghiệm người dùng liền mạch, bạn có thể mở web paywall trong trình duyệt trong ứng dụng. Tính năng này hiển thị trang mua hàng web ngay bên trong ứng dụng của bạn, cho phép người dùng hoàn tất giao dịch mà không cần chuyển ứng dụng.

Để bật tính năng này, truyền `WebPresentation.BrowserInApp` làm đối số thứ hai cho `openWebPaywall`:

```typescript showLineNumbers title="React Native (TSX)"

try {
    await adapty.openWebPaywall(
        product,
        WebPresentation.BrowserInApp, // default – WebPresentation.BrowserOutApp
    );
} catch (error) {
    console.warn('Failed to open web paywall:', error);
}

```

---


# File: react-native-troubleshoot-paywall-builder
---

---
title: "Khắc phục sự cố Paywall Builder trong React Native SDK"
description: "Khắc phục sự cố Paywall Builder trong React Native SDK"
---

Hướng dẫn này giúp bạn giải quyết các sự cố thường gặp khi sử dụng paywall được thiết kế trong Adapty Paywall Builder với React Native SDK.

## Lấy cấu hình paywall thất bại \{#getting-a-paywall-configuration-fails\}

**Sự cố**: Phương thức `getPaywallConfiguration` không lấy được cấu hình paywall.

**Nguyên nhân**: Paywall chưa được bật để hiển thị trên thiết bị trong Paywall Builder.

**Giải pháp**: Bật toggle **Show on device** trong Paywall Builder.

  <img src="/assets/shared/img/show-on-device.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

## Số lượt xem paywall bị nhân đôi \{#the-paywall-view-number-is-too-big\}

**Sự cố**: Số lượt xem paywall hiển thị gấp đôi so với dự kiến.

**Nguyên nhân**: Có thể bạn đang gọi `logShowPaywall` trong code, khiến số lượt xem bị tính hai lần nếu bạn đang dùng Paywall Builder. Với các paywall được thiết kế bằng Paywall Builder, analytics được theo dõi tự động nên bạn không cần dùng phương thức này.

**Giải pháp**: Đảm bảo bạn không gọi `logShowPaywall` trong code nếu đang sử dụng Paywall Builder.

## Các sự cố khác \{#other-issues\}

**Sự cố**: Bạn gặp phải các vấn đề liên quan đến Paywall Builder chưa được đề cập ở trên.

**Giải pháp**: Migrate SDK lên phiên bản mới nhất bằng cách sử dụng [hướng dẫn migration](react-native-sdk-migration-guides) nếu cần. Nhiều sự cố đã được khắc phục trong các phiên bản SDK mới hơn.

---


# File: react-native-quickstart-manual
---

---
title: "Bật tính năng mua hàng trong paywall tùy chỉnh với React Native SDK"
description: "Tích hợp Adapty SDK vào các paywall React Native tùy chỉnh để bật in-app purchase."
---

Hướng dẫn này mô tả cách tích hợp Adapty vào các paywall tùy chỉnh của bạn. Bạn giữ toàn quyền kiểm soát việc triển khai paywall, trong khi Adapty SDK lo việc lấy sản phẩm, xử lý giao dịch mua mới và khôi phục các giao dịch trước đó.

:::important
**Hướng dẫn này dành cho các nhà phát triển đang triển khai paywall tùy chỉnh.** Nếu bạn muốn cách đơn giản nhất để bật tính năng mua hàng, hãy sử dụng [Adapty Paywall Builder](react-native-quickstart-paywalls). Với Paywall Builder, bạn tạo paywall trong trình chỉnh sửa trực quan không cần code, Adapty tự động xử lý toàn bộ logic mua hàng, và bạn có thể thử nghiệm các thiết kế khác nhau mà không cần phát hành lại ứng dụng.
:::

## Trước khi bắt đầu \{#before-you-start\}

### Thiết lập sản phẩm \{#set-up-products\}

Để bật in-app purchase, bạn cần hiểu ba khái niệm chính:

- [**Sản phẩm**](product) – bất cứ thứ gì người dùng có thể mua (gói đăng ký, consumable, quyền truy cập trọn đời)
- [**Paywalls**](paywalls) – các cấu hình xác định sản phẩm nào sẽ được cung cấp. Trong Adapty, paywall là cách duy nhất để lấy sản phẩm, nhưng thiết kế này cho phép bạn chỉnh sửa sản phẩm, giá cả và ưu đãi mà không cần thay đổi code ứng dụng.
- [**Placements**](placements) – nơi và thời điểm bạn hiển thị paywall trong ứng dụng (ví dụ: `main`, `onboarding`, `settings`). Bạn thiết lập paywall cho các placement trên dashboard, rồi truy xuất chúng theo placement ID trong code. Điều này giúp bạn dễ dàng chạy A/B test và hiển thị các paywall khác nhau cho từng nhóm người dùng.

Hãy đảm bảo bạn hiểu các khái niệm này ngay cả khi làm việc với paywall tùy chỉnh. Về cơ bản, đây chỉ là cách bạn quản lý các sản phẩm bán trong ứng dụng.

Để triển khai paywall tùy chỉnh, bạn cần tạo một **paywall** và thêm vào một **placement**. Thiết lập này cho phép bạn lấy sản phẩm của mình. Để hiểu những gì cần làm trên dashboard, hãy làm theo hướng dẫn bắt đầu nhanh [tại đây](quickstart).

### Quản lý người dùng \{#manage-users\}

Bạn có thể làm việc có hoặc không cần xác thực backend ở phía mình.

Tuy nhiên, Adapty SDK xử lý người dùng ẩn danh và người dùng đã xác định theo cách khác nhau. Đọc [hướng dẫn bắt đầu nhanh về xác định người dùng](react-native-quickstart-identify) để hiểu các điểm đặc thù và đảm bảo bạn đang làm việc với người dùng đúng cách.

## Bước 1. Lấy sản phẩm \{#step-1-get-products\}

Để lấy sản phẩm cho paywall tùy chỉnh, bạn cần:

1. Lấy đối tượng `paywall` bằng cách truyền ID [placement](placements) vào phương thức `getPaywall`.
2. Lấy mảng sản phẩm cho paywall này bằng phương thức `getPaywallProducts`.

```typescript showLineNumbers

async function loadPaywall() {
  try {
    const paywall: AdaptyPaywall = await adapty.getPaywall('YOUR_PLACEMENT_ID');
    const products: AdaptyPaywallProduct[] = await adapty.getPaywallProducts(paywall);
    
    // Use products to build your custom paywall UI
  } catch (error) {
    // Handle the error
  }
}
```

## Bước 2. Chấp nhận giao dịch mua \{#step-2-accept-purchases\}

Khi người dùng nhấn vào một sản phẩm trong paywall tùy chỉnh, hãy gọi phương thức `makePurchase` với sản phẩm đã chọn. Phương thức này sẽ xử lý luồng mua hàng và trả về hồ sơ người dùng đã được cập nhật.

```typescript showLineNumbers

async function purchaseProduct(product: AdaptyPaywallProduct) {
  try {
    const purchaseResult: AdaptyPurchaseResult = await adapty.makePurchase(product);
    
    switch (purchaseResult.type) {
      case 'success':
        // Purchase successful, profile updated
        break;
      case 'user_cancelled':
        // User canceled the purchase
        break;
      case 'pending':
        // Purchase is pending (e.g., user will pay offline with cash)
        break;
    }
  } catch (error) {
    // Handle the error
  }
}
```

## Bước 3. Khôi phục giao dịch mua \{#step-3-restore-purchases\}

Các cửa hàng ứng dụng yêu cầu tất cả ứng dụng có gói đăng ký phải cung cấp cách để người dùng có thể khôi phục giao dịch mua của họ.

Gọi phương thức `restorePurchases` khi người dùng nhấn nút khôi phục. Phương thức này sẽ đồng bộ lịch sử mua hàng của họ với Adapty và trả về hồ sơ người dùng đã được cập nhật.

```typescript showLineNumbers

async function restorePurchases() {
  try {
    const profile: AdaptyProfile = await adapty.restorePurchases();
    // Restore successful, profile updated
  } catch (error) {
    // Handle the error
  }
}
```

## Các bước tiếp theo \{#next-steps\}

---
no_index: true
---
import Callout from '../../../components/Callout.astro';

<Callout type="tip">
Bạn có câu hỏi hoặc gặp sự cố? Hãy xem [diễn đàn hỗ trợ](https://adapty.featurebase.app/) của chúng tôi — nơi bạn có thể tìm câu trả lời cho các câu hỏi thường gặp hoặc đặt câu hỏi của riêng mình. Đội ngũ và cộng đồng của chúng tôi luôn sẵn sàng giúp đỡ!
</Callout>

Paywall của bạn đã sẵn sàng để hiển thị trong ứng dụng. Hãy kiểm tra giao dịch mua trong [sandbox App Store](test-purchases-in-sandbox) hoặc trên [Google Play Store](testing-on-android) để đảm bảo bạn có thể hoàn thành một giao dịch mua thử nghiệm từ paywall. Để xem cách hoạt động trong một triển khai sẵn sàng cho môi trường production, hãy xem [CustomPurchaseScreen.tsx](https://github.com/adaptyteam/AdaptySDK-React-Native/blob/master/examples/ExpoGoWebMock/src/CustomPurchaseScreen.tsx) trong ứng dụng ví dụ của chúng tôi, minh họa cách xử lý giao dịch mua với xử lý lỗi đúng cách, trạng thái loading và quản lý trạng thái giao diện.

Tiếp theo, [kiểm tra xem người dùng đã hoàn thành giao dịch mua chưa](react-native-check-subscription-status) để xác định có nên hiển thị paywall hay cấp quyền truy cập vào các tính năng trả phí.

---


# File: fetch-paywalls-and-products-react-native
---

---
title: "Lấy thông tin paywalls và sản phẩm cho remote config paywalls trong React Native SDK"
description: "Lấy thông tin paywalls và sản phẩm trong Adapty React Native SDK để tăng cường khả năng kiếm tiền từ người dùng."
---

Trước khi hiển thị remote config và custom paywalls, bạn cần lấy thông tin về chúng. Lưu ý rằng chủ đề này liên quan đến remote config và custom paywalls. Để biết cách lấy paywalls cho các paywall được tùy chỉnh bằng Paywall Builder, hãy xem [Lấy paywalls Paywall Builder và cấu hình của chúng](react-native-get-pb-paywalls).

:::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](sample-apps) của chúng tôi, nơi minh họa toàn bộ quá 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.

:::

<details>
   <summary>Trước khi bắt đầu lấy paywalls và sản phẩm trong ứng dụng di động của bạn (nhấn để mở rộng)</summary>

   1. [Tạo sản phẩm](create-product) trong Adapty Dashboard.

2. [Tạo paywall và thêm sản phẩm vào paywall](create-paywall) trong Adapty Dashboard.

3. [Tạo placement và thêm paywall vào placement](create-placement) trong Adapty Dashboard.

4. [Cài đặt Adapty SDK](sdk-installation-reactnative) trong ứng dụng di động của bạn.
</details>

## Lấy thông tin paywall \{#fetch-paywall-information\}

Trong Adapty, một [sản phẩm](product) là sự kết hợp của các sản phẩm từ cả App Store lẫn Google Play. Các sản phẩm đa nền tảng này được tích hợp vào paywalls, cho phép bạn hiển thị chúng trong các placement cụ thể của ứng dụng di động.

Để hiển thị sản phẩm, bạn cần lấy một [Paywall](paywalls) từ một trong các [placement](placements) của mình bằng phương thức `getPaywall`.

:::important
**Đừng hardcode product ID.** ID duy nhất bạn nên hardcode là placement ID. Paywalls được cấu hình từ xa, nên số lượng sản phẩm và ưu đãi có thể thay đổi bất cứ lúc nào. Ứng dụng của bạn phải xử lý những thay đổi này một cách linh hoạt — nếu hôm nay paywall trả về hai sản phẩm và ngày mai trả về ba, hãy hiển thị tất cả mà không cần thay đổi code.
:::

```typescript showLineNumbers
try {
    const id = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywall(id, locale);
    // the requested paywall
} catch (error) {
    // handle the error
}
```

| Tham số           | Bắt buộc | Mô tả |
|-------------------|--------|-----------|
| **placementId**   | bắt buộc | Định danh của [Placement](placements). Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard. |
| **locale**        | <p>tùy chọn</p><p>mặc định: `en`</p> | <p>Định danh của [bản địa hóa paywall](add-remote-config-locale). Tham số này là một mã ngôn ngữ gồm một hoặc nhiều thẻ phụ được phân tách bằng dấu trừ (**-**). Thẻ đầu tiên là ngôn ngữ, thẻ thứ hai là vùng.</p><p></p><p>Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha của Brazil.</p><p></p><p>Xem [Localizations and locale codes](react-native-localizations-and-locale-codes) để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng chúng.</p> |
| **fetchPolicy**   | mặc định: `.reloadRevalidatingCacheData` | <p>Theo mặc định, SDK sẽ cố tải dữ liệu từ máy chủ và trả về dữ liệu đã lưu trong cache nếu thất bại. Chúng tôi khuyến nghị tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.</p><p></p><p>Tuy nhiên, nếu bạn cho rằng người dùng của mình thường xuyên gặp kết nối internet không ổn định, hãy cân nhắc sử dụng `.returnCacheDataElseLoad` để trả về dữ liệu cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng thời gian tải sẽ nhanh hơn dù kết nối internet không tốt. Cache được cập nhật thường xuyên nên hoàn toàn an toàn khi sử dụng trong phiên làm việc để tránh các yêu cầu mạng.</p><p></p><p>Lưu ý rằng cache vẫn còn nguyên sau khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt ứng dụng hoặc xóa thủ công.</p><p></p><p>Adapty SDK lưu trữ paywalls theo hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và [paywall dự phòng](react-native-use-fallback-paywalls). Chúng tôi cũng sử dụng CDN để lấy paywalls nhanh hơn và một máy chủ dự phòng độc lập trong trường hợp CDN không thể truy cập. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản paywall mới nhất trong khi vẫn đảm bảo độ tin cậy ngay cả khi kết nối internet yếu.</p> |
| **loadTimeoutMs** | mặc định: 5 giây | <p>Giá trị này giới hạn thời gian chờ cho phương thức này. Nếu hết thời gian chờ, dữ liệu cache hoặc fallback cục bộ sẽ được trả về.</p><p></p><p>Lưu ý rằng trong một số trường hợp hiếm gặp, phương thức này có thể hết thời gian chờ muộn hơn một chút so với `loadTimeout` đã chỉ định, vì thao tác có thể bao gồm nhiều yêu cầu khác nhau bên dưới.</p> |

Đừng hardcode product ID! Vì paywalls được cấu hình từ xa, các sản phẩm có sẵn, số lượng sản phẩm và ưu đãi đặc biệt (như dùng thử miễn phí) có thể thay đổi theo thời gian. Hãy đảm bảo code của bạn xử lý được các tình huống này.  
Ví dụ: nếu ban đầu bạn nhận được 2 sản phẩm, ứng dụng của bạn nên hiển thị 2 sản phẩm đó. Nhưng nếu sau này bạn nhận được 3 sản phẩm, ứng dụng của bạn nên hiển thị cả 3 mà không cần thay đổi code. Điều duy nhất bạn phải hardcode là placement ID.

Tham số trả về:

| Tham số | Mô tả                                                                                                                                                  |
| :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Paywall   | Một đối tượng [`AdaptyPaywall`](https://react-native.adapty.io/interfaces/adaptypaywall) với: danh sách product ID, định danh paywall, Remote Config và một số thuộc tính khác. |

## Lấy sản phẩm \{#fetch-products\}

Sau khi có paywall, bạn có thể truy vấn mảng sản phẩm tương ứng với nó:

```typescript showLineNumbers
try {
    // ...paywall
    const products = await adapty.getPaywallProducts(paywall);
  // the requested products list
} catch (error) {
    // handle the error
}
```

Tham số trả về:

| Tham số | Mô tả                                                                                                                                                                                |
| :-------- |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Products  | Danh sách các đối tượng [`AdaptyPaywallProduct`](https://react-native.adapty.io/interfaces/adaptypaywallproduct) với: định danh sản phẩm, tên sản phẩm, giá, đơn vị tiền tệ, thời hạn gói đăng ký và một số thuộc tính khác.                                   |

Khi tự thiết kế paywall, bạn sẽ cần truy cập các thuộc tính này từ đối tượng [`AdaptyPaywallProduct`](https://react-native.adapty.io/interfaces/adaptypaywallproduct). Dưới đây là các thuộc tính được sử dụng phổ biến nhất, nhưng hãy tham khảo tài liệu được liên kết để xem đầy đủ tất cả các thuộc tính có sẵn.

| Thuộc tính              | Mô tả                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Title**               | Để hiển thị tiêu đề sản phẩm, sử dụng `product.localizedTitle`. Lưu ý rằng việc bản địa hóa dựa trên quốc gia cửa hàng mà người dùng đã chọn, không phải ngôn ngữ của thiết bị.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Price**               | Để hiển thị giá đã được bản địa hóa, sử dụng `product.price?.localizedString`. Việc bản địa hóa này dựa trên thông tin locale của thiết bị. Bạn cũng có thể truy cập giá dưới dạng số bằng `product.price?.amount`. Giá trị sẽ được cung cấp theo đơn vị tiền tệ địa phương. Để lấy ký hiệu tiền tệ liên quan, sử dụng `product.price?.currencySymbol`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Subscription Period** | Để hiển thị chu kỳ (ví dụ: tuần, tháng, năm, v.v.), sử dụng `product.subscription?.localizedSubscriptionPeriod`. Việc bản địa hóa này dựa trên locale của thiết bị. Để lấy chu kỳ gói đăng ký theo cách lập trình, sử dụng `product.subscription?.subscriptionPeriod`. Từ đó bạn có thể truy cập thuộc tính `unit` để lấy độ dài (tức là 'day', 'week', 'month', 'year', hoặc 'unknown'). Giá trị `numberOfUnits` sẽ cho bạn biết số đơn vị chu kỳ. Ví dụ: với gói đăng ký theo quý, bạn sẽ thấy `'month'` trong thuộc tính unit và `3` trong thuộc tính numberOfUnits.                                                                                                                                                                                                                                                                                                       |
| **Introductory Offer**  | Để hiển thị huy hiệu hoặc chỉ báo khác cho biết gói đăng ký có ưu đãi giới thiệu, hãy kiểm tra thuộc tính `product.subscription?.offer?.phases`. Đây là danh sách có thể chứa tối đa hai giai đoạn giảm giá: giai đoạn dùng thử miễn phí và giai đoạn giá ưu đãi giới thiệu. Trong mỗi đối tượng giai đoạn có các thuộc tính hữu ích sau:<br/>• `paymentMode`: một chuỗi với các giá trị `'free_trial'`, `'pay_as_you_go'`, `'pay_up_front'` và `'unknown'`. Dùng thử miễn phí sẽ có loại `'free_trial'`.<br/>• `price`: Giá giảm dưới dạng số. Với dùng thử miễn phí, tìm giá trị `0` ở đây.<br/>• `localizedNumberOfPeriods`: một chuỗi được bản địa hóa theo locale của thiết bị mô tả độ dài của ưu đãi. Ví dụ: ưu đãi dùng thử ba ngày hiển thị `'3 days'` trong trường này.<br/>• `subscriptionPeriod`: Ngoài ra, bạn có thể lấy thông tin chi tiết của chu kỳ ưu đãi bằng thuộc tính này. Nó hoạt động tương tự như mô tả trong phần trước dành cho ưu đãi.<br/>• `localizedSubscriptionPeriod`: Chu kỳ gói đăng ký đã được định dạng theo locale của người dùng cho phần giảm giá. |

## Tăng tốc độ lấy paywall với paywall đối tượng mặc định \{#speed-up-paywall-fetching-with-default-audience-paywall\}

Thông thường, paywalls được lấy gần như ngay lập tức, vì vậy bạn không cần lo lắng về việc tăng tốc quá trình này. Tuy nhiên, trong trường hợp bạn có nhiều đối tượng và paywalls, và người dùng của bạn có kết nối internet yếu, việc lấy paywall có thể mất nhiều thời gian hơn mong muốn. Trong những tình huống như vậy, bạn có thể muốn hiển thị paywall mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị paywall nào cả.

Để giải quyết điều này, bạn có thể sử dụng phương thức `getPaywallForDefaultAudience`, phương thức này lấy paywall của placement được chỉ định cho đối tượng **All Users**. Tuy nhiên, điều quan trọng cần hiểu là cách tiếp cận được khuyến nghị là lấy paywall bằng phương thức `getPaywall`, như được mô tả chi tiết trong phần [Lấy thông tin paywall](fetch-paywalls-and-products-react-native#fetch-paywall-information) ở trên.

:::warning
Lý do chúng tôi khuyến nghị sử dụng `getPaywall`

Phương thức `getPaywallForDefaultAudience` có một số hạn chế đáng kể:

- **Vấn đề tương thích ngược tiềm ẩn**: Nếu bạn cần hiển thị các paywall khác nhau cho các phiên bản ứng dụng khác nhau (hiện tại và tương lai), bạn có thể gặp khó khăn. Bạn sẽ phải thiết kế paywalls hỗ trợ phiên bản hiện tại (cũ) hoặc chấp nhận rằng người dùng có phiên bản hiện tại (cũ) có thể gặp sự cố với các paywalls không hiển thị được.
- **Mất khả năng nhắm mục tiêu**: Tất cả người dùng sẽ thấy cùng một paywall được thiết kế cho đối tượng **All Users**, nghĩa là bạn mất khả năng nhắm mục tiêu cá nhân hóa (bao gồm theo quốc gia, attribution marketing hoặc các thuộc tính tùy chỉnh của bạn).

Nếu bạn sẵn sàng chấp nhận những hạn chế này để được hưởng lợi từ tốc độ lấy paywall nhanh hơn, hãy sử dụng phương thức `getPaywallForDefaultAudience` như sau. Nếu không, hãy tiếp tục sử dụng `getPaywall` được mô tả [ở trên](fetch-paywalls-and-products-react-native#fetch-paywall-information).
:::

```typescript showLineNumbers
try {
    const id = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const paywall = await adapty.getPaywallForDefaultAudience(id, locale);
  // the requested paywall
} catch (error) {
    // handle the error
}
```

:::note
Phương thức `getPaywallForDefaultAudience` có sẵn từ React Native SDK phiên bản 2.11.2 trở lên.
:::

| Tham số | Bắt buộc | Mô tả |
|---------|--------|-----------|
| **placementId** | bắt buộc | Định danh của [Placement](placements). Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard. |
| **locale** | <p>tùy chọn</p><p>mặc định: `en`</p> | <p>Định danh của [bản địa hóa paywall](add-remote-config-locale). Tham số này là một mã ngôn ngữ gồm một hoặc nhiều thẻ phụ được phân tách bằng dấu trừ (**-**). Thẻ đầu tiên là ngôn ngữ, thẻ thứ hai là vùng.</p><p></p><p>Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha của Brazil.</p><p></p><p>Xem [Localizations and locale codes](react-native-localizations-and-locale-codes) để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng chúng.</p> |
| **fetchPolicy** | mặc định: `.reloadRevalidatingCacheData` | <p>Theo mặc định, SDK sẽ cố tải dữ liệu từ máy chủ và trả về dữ liệu đã lưu trong cache nếu thất bại. Chúng tôi khuyến nghị tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.</p><p></p><p>Tuy nhiên, nếu bạn cho rằng người dùng của mình thường xuyên gặp kết nối internet không ổn định, hãy cân nhắc sử dụng `.returnCacheDataElseLoad` để trả về dữ liệu cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng thời gian tải sẽ nhanh hơn dù kết nối internet không tốt. Cache được cập nhật thường xuyên nên hoàn toàn an toàn khi sử dụng trong phiên làm việc để tránh các yêu cầu mạng.</p><p></p><p>Lưu ý rằng cache vẫn còn nguyên sau khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt ứng dụng hoặc xóa thủ công.</p> |

---


# File: present-remote-config-paywalls-react-native
---

---
title: "Render paywall designed by remote config in React Native SDK"
description: "Khám phá cách hiển thị paywall Remote Config trong Adapty React Native SDK để cá nhân hóa trải nghiệm người dùng."
---

Nếu bạn đã tùy chỉnh paywall bằng Remote Config, bạn cần tự triển khai phần render trong code của ứng dụng để hiển thị nó cho người dùng. Vì Remote Config mang lại sự linh hoạt theo nhu cầu của bạn, bạn hoàn toàn quyết định những gì được đưa vào và giao diện paywall trông như thế nào. Chúng tôi cung cấp một phương thức để lấy cấu hình remote, giúp bạn tự do hiển thị paywall tùy chỉnh đã được thiết lập qua Remote Config.

## Lấy Remote Config của paywall và hiển thị nó \{#get-paywall-remote-config-and-present-it\}

Để lấy Remote Config của một paywall, hãy truy cập thuộc tính `remoteConfig` và trích xuất các giá trị cần thiết.

```typescript showLineNumbers
try {
  const paywall = await adapty.getPaywall({ placementId: "YOUR_PLACEMENT_ID" });
  const headerText = paywall.remoteConfig?.data?.["header_text"];
} catch (error) {
  // handle the error
}
```

Sau khi nhận được tất cả các giá trị cần thiết, đã đến lúc render và ghép chúng thành một trang đẹp mắt. Hãy đảm bảo thiết kế phù hợp với nhiều kích thước màn hình và hướng xoay khác nhau, mang lại trải nghiệm mượt mà và thân thiện trên mọi thiết bị.

:::warning
Hãy đảm bảo [ghi lại sự kiện xem paywall](present-remote-config-paywalls-react-native#track-paywall-view-events) như mô tả bên dưới, để Adapty analytics có thể thu thập dữ liệu cho các funnel và A/B test.
:::

Sau khi hoàn tất việc hiển thị paywall, hãy tiếp tục thiết lập luồng mua hàng. Khi người dùng thực hiện mua hàng, chỉ cần gọi `.makePurchase()` với sản phẩm từ paywall của bạn. Để biết thêm chi tiết về phương thức `.makePurchase()`, hãy đọc [Thực hiện mua hàng](react-native-making-purchases).

Chúng tôi khuyến nghị [tạo một paywall dự phòng](react-native-use-fallback-paywalls). Paywall dự phòng này sẽ được hiển thị cho người dùng khi không có kết nối internet hoặc cache, đảm bảo trải nghiệm mượt mà ngay cả trong những tình huống đó.

## Theo dõi sự kiện xem paywall \{#track-paywall-view-events\}

Adapty hỗ trợ bạn đo lường hiệu quả của các paywall. Trong khi dữ liệu mua hàng được thu thập tự động, việc ghi lại lượt xem paywall cần có sự tham gia của bạn vì chỉ bạn mới biết khi nào người dùng thực sự thấy paywall.

Để ghi lại sự kiện xem paywall, chỉ cần gọi `.logShowPaywall(paywall)`, và sự kiện này sẽ được phản ánh trong các chỉ số paywall của bạn trong funnel và A/B test.

:::important
Không cần gọi `.logShowPaywall(paywall)` nếu bạn đang hiển thị paywall được tạo trong [Paywall Builder](adapty-paywall-builder).
:::

```typescript showLineNumbers
await adapty.logShowPaywall(paywall);
```

Tham số yêu cầu:

| Tham số     | Bắt buộc | Mô tả                                                                                       |
| :---------- | :------- |:--------------------------------------------------------------------------------------------|
| **paywall** | bắt buộc | Một đối tượng [`AdaptyPaywall`](https://react-native.adapty.io/interfaces/adaptypaywall).   |

---


# File: react-native-making-purchases
---

---
title: "Thực hiện mua hàng trong ứng dụng với React Native SDK"
description: "Hướng dẫn xử lý in-app purchase và gói đăng ký bằng Adapty."
---

Hiển thị paywall trong ứng dụng là bước quan trọng để cung cấp cho người dùng quyền truy cập vào nội dung hoặc dịch vụ cao cấp. Tuy nhiên, chỉ cần hiển thị paywall là đủ để hỗ trợ mua hàng nếu bạn dùng [Paywall Builder](adapty-paywall-builder) để tùy chỉnh paywall của mình.

Nếu không dùng Paywall Builder, bạn phải sử dụng một phương thức riêng là `.makePurchase()` để hoàn tất giao dịch và mở khóa nội dung. Phương thức này là cổng để người dùng tương tác với paywall và tiến hành giao dịch.

Nếu paywall của bạn có ưu đãi đang hoạt động cho sản phẩm mà người dùng muốn mua, Adapty sẽ tự động áp dụng ưu đãi đó tại thời điểm mua hàng.

:::warning
Lưu ý rằng ưu đãi giới thiệu chỉ được áp dụng tự động nếu bạn sử dụng paywall được thiết lập bằng Paywall Builder.

Trong các trường hợp khác, bạn cần [xác minh tính đủ điều kiện của người dùng để nhận ưu đãi giới thiệu trên iOS](fetch-paywalls-and-products#check-intro-offer-eligibility-on-ios). Bỏ qua bước này có thể dẫn đến ứng dụng bị từ chối khi phát hành. Ngoài ra, điều này có thể khiến người dùng đủ điều kiện nhận ưu đãi giới thiệu bị tính giá đầy đủ.
:::

Hãy đảm bảo bạn đã [hoàn thành cấu hình ban đầu](quickstart) mà không bỏ qua bất kỳ bước nào. Nếu không, chúng tôi không thể xác thực giao dịch mua hàng.

## Thực hiện mua hàng \{#make-purchase\}

:::note
**Đang dùng [Paywall Builder](adapty-paywall-builder)?** Các giao dịch mua được xử lý tự động — bạn có thể bỏ qua bước này.

**Muốn có hướng dẫn từng bước?** Xem [hướng dẫn quickstart](react-native-implement-paywalls-manually) để có hướng dẫn triển khai đầy đủ từ đầu đến cuối.
:::

```typescript showLineNumbers
try {
    const purchaseResult = await adapty.makePurchase(product);
    switch (purchaseResult.type) {
      case 'success':
        const isSubscribed = purchaseResult.profile?.accessLevels['YOUR_ACCESS_LEVEL']?.isActive;

        if (isSubscribed) {
          // Grant access to the paid features
        }
        break;
      case 'user_cancelled':
        // Handle the case where the user canceled the purchase
        break;
      case 'pending':
        // Handle deferred purchases (e.g., the user will pay offline with cash)
        break;
    }
} catch (error) {
    // Handle the error
}
```

Tham số yêu cầu:

| Tham số     | Bắt buộc | Mô tả                                                                                                                          |
| :---------- | :------- |:-------------------------------------------------------------------------------------------------------------------------------|
| **Product** | bắt buộc | Đối tượng [`AdaptyPaywallProduct`](https://react-native.adapty.io/interfaces/adaptypaywallproduct) lấy từ paywall. |

Tham số phản hồi:

| Tham số | Mô tả                                                                                                                                                                                                                                                                                                                                                                            |
|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Profile** | <p>Nếu yêu cầu thành công, phản hồi chứa đối tượng này. Đối tượng [AdaptyProfile](https://react-native.adapty.io/interfaces/adaptyprofile) cung cấp thông tin toàn diện về mức độ truy cập, gói đăng ký và sản phẩm mua một lần của người dùng trong ứng dụng.</p><p>Kiểm tra trạng thái mức độ truy cập để xác định xem người dùng có quyền truy cập cần thiết vào ứng dụng hay không.</p> |

:::warning
**Lưu ý:** Nếu bạn vẫn đang dùng StoreKit của Apple phiên bản thấp hơn 2.0 và Adapty SDK phiên bản thấp hơn 2.9.0, bạn cần cung cấp [Apple App Store shared secret](app-store-connection-configuration#step-5-enter-app-store-shared-secret) thay thế. Phương thức này hiện đã bị Apple ngừng hỗ trợ.
:::

## Thay đổi gói đăng ký khi mua hàng \{#change-subscription-when-making-a-purchase\}

Khi người dùng chọn một gói đăng ký mới thay vì gia hạn gói hiện tại, cách xử lý phụ thuộc vào cửa hàng:

- Với App Store, gói đăng ký sẽ tự động được cập nhật trong cùng nhóm gói đăng ký. Nếu người dùng mua một gói từ nhóm này trong khi đã có gói từ nhóm khác, cả hai gói đều sẽ hoạt động đồng thời.
- Với Google Play, gói đăng ký không tự động được cập nhật. Bạn cần xử lý việc chuyển đổi trong code ứng dụng như mô tả bên dưới.

Để thay thế gói đăng ký bằng gói khác trên Android, gọi phương thức `.makePurchase()` với tham số bổ sung:

```typescript showLineNumbers
try {
    const purchaseResult = await adapty.makePurchase(product, params);
    switch (purchaseResult.type) {
      case 'success':
        const isSubscribed = purchaseResult.profile?.accessLevels['YOUR_ACCESS_LEVEL']?.isActive;

        if (isSubscribed) {
          // Grant access to the paid features
        }
        break;
      case 'user_cancelled':
        // Handle the case where the user canceled the purchase
        break;
      case 'pending':
        // Handle deferred purchases (e.g., the user will pay offline with cash)
        break;
    }
} catch (error) {
    // Handle the error
}
```
Tham số yêu cầu bổ sung:

| Tham số    | Bắt buộc | Mô tả                                                  |
| :--------- | :------- | :----------------------------------------------------------- |
| **params** | bắt buộc | Đối tượng thuộc kiểu [`MakePurchaseParamsInput`](https://react-native.adapty.io/types/makepurchaseparamsinput). |

:::info
**Phiên bản 3.8.2+**: Cấu trúc `MakePurchaseParamsInput` đã được cập nhật. `oldSubVendorProductId` và `prorationMode` giờ nằm trong `subscriptionUpdateParams`, và `isOfferPersonalized` được chuyển lên cấp trên.

Ví dụ:
```javascript
makePurchase(product, {
    android: {
        subscriptionUpdateParams: {
            oldSubVendorProductId: 'old_product_id',
            prorationMode: 'charge_prorated_price'
        },
        isOfferPersonalized: true
    }
});
```
:::

Bạn có thể đọc thêm về gói đăng ký và các chế độ thay thế trong tài liệu Google Developer:

- [Về các chế độ thay thế](https://developer.android.com/google/play/billing/subscriptions#replacement-modes)
- [Khuyến nghị của Google về chế độ thay thế](https://developer.android.com/google/play/billing/subscriptions#replacement-recommendations)
- Chế độ thay thế [`CHARGE_PRORATED_PRICE`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.ReplacementMode#CHARGE_PRORATED_PRICE()). Lưu ý: phương thức này chỉ áp dụng cho việc nâng cấp gói đăng ký. Hạ cấp không được hỗ trợ.
- Chế độ thay thế [`DEFERRED`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.ReplacementMode#DEFERRED()). Lưu ý: Việc thay đổi gói đăng ký thực sự chỉ xảy ra khi chu kỳ thanh toán hiện tại kết thúc.

## Đổi mã ưu đãi trên iOS \{#redeem-offer-codes-in-ios\}

---
no_index: true
---
import Callout from '../../../components/Callout.astro';

<Details>
<summary>Về offer code</summary>

Offer code cho phép bạn tặng ưu đãi hoặc dùng thử miễn phí cho những người dùng cụ thể. Không giống như các ưu đãi thông thường được áp dụng tự động, offer code được phân phối bên ngoài ứng dụng — qua email marketing, mạng xã hội, hoặc tài liệu in ấn. Người dùng đổi code bằng cách nhập vào App Store, truy cập URL đổi thưởng, hoặc qua hộp thoại trong ứng dụng.

Để thiết lập offer code, mở một gói đăng ký trong App Store Connect và vào mục **Offer Codes**. Bạn có thể tạo [ba loại](https://developer.apple.com/help/app-store-connect/manage-subscriptions/set-up-subscription-offer-codes) offer code:

- **Free** — gói đăng ký miễn phí trong một khoảng thời gian nhất định, sau đó gia hạn với giá đầy đủ.
- **Pay as you go** — người dùng trả giá ưu đãi theo từng chu kỳ thanh toán trong một khoảng thời gian, sau đó gói đăng ký gia hạn với giá đầy đủ.
- **Pay up front** — người dùng trả một lần với giá ưu đãi cho toàn bộ thời gian ưu đãi, sau đó gói đăng ký gia hạn với giá đầy đủ.

Bạn không cần thêm offer code vào Adapty. Apple gắn tag mọi giao dịch trong thời gian ưu đãi với danh mục offer code. Điều này bao gồm lần đổi code đầu tiên và tất cả các lần gia hạn ưu đãi tiếp theo. Adapty phát hiện tag đó và ghi lại từng giao dịch với danh mục ưu đãi `offer_code`. Khi thời gian ưu đãi kết thúc và gói đăng ký gia hạn với giá đầy đủ, tag đó sẽ không còn nữa. Bạn có thể lọc analytics theo loại ưu đãi **Offer Code** trên [Adapty Dashboard](controls-filters-grouping-compare-proceeds).

#### Xử lý sự chênh lệch doanh thu \{#revenue-discrepancy-troubleshooting\}

Nếu bạn nhận thấy một giao dịch offer code xuất hiện trong Adapty với giá đầy đủ thay vì giá ưu đãi, hãy kiểm tra lại những điểm sau trong App Store Connect:

- Offer code đã được cấu hình đúng giá cho tất cả các khu vực mà người dùng có thể đổi code.
- Giá ưu đãi đã được thiết lập cho quốc gia hoặc khu vực cụ thể của người dùng. Apple gửi giá theo khu vực trong giao dịch. Nếu không có giá khu vực nào được cấu hình cho ưu đãi, Apple có thể gửi giá đầy đủ của sản phẩm.

Bạn có thể lọc và kiểm tra các giao dịch offer code trên [Adapty Dashboard](controls-filters-grouping-compare-proceeds) theo loại ưu đãi **Offer Code** và bộ lọc **Offer Discount Type**.

#### Promo code cũ (đã ngừng hỗ trợ) \{#legacy-promo-codes-deprecated\}

<Callout type="warning">
Apple đã ngừng hỗ trợ promo code cho in-app purchase vào tháng 3 năm 2026. Offer code thay thế chúng với nhiều tính năng hơn: điều kiện tham gia có thể cấu hình, ngày hết hạn, và lên đến 1 triệu code mỗi quý. Nếu trước đây bạn sử dụng promo code cho in-app purchase, hãy chuyển sang offer code trong App Store Connect.
</Callout>

Promo code cũ (giới hạn 100 code mỗi ứng dụng mỗi phiên bản) cấp quyền truy cập miễn phí vào một gói đăng ký. Không giống như offer code, Apple không đưa thông tin giảm giá vào giao dịch promo code — Apple gửi giá đầy đủ của sản phẩm trong biên lai. Kết quả là Adapty ghi lại các giao dịch này theo giá đầy đủ, gây ra sự chênh lệch doanh thu giữa Adapty analytics và App Store Connect.

Nếu bạn thấy các giao dịch lịch sử với giá đầy đủ trong khi đáng lẽ phải miễn phí, nhiều khả năng đó là từ promo code cũ. Vì các code này đã bị ngừng hỗ trợ, hãy chuyển sang offer code để theo dõi doanh thu chính xác.

</Details>

Để hiển thị sheet đổi mã trong ứng dụng:

```typescript showLineNumbers
adapty.presentCodeRedemptionSheet();
```

:::danger
Qua quan sát của chúng tôi, sheet Offer Code Redemption trong một số ứng dụng có thể hoạt động không ổn định. Chúng tôi khuyến nghị chuyển hướng người dùng trực tiếp đến App Store.

Để thực hiện điều này, bạn cần mở URL theo định dạng sau:
`https://apps.apple.com/redeem?ctx=offercodes&id={apple_app_id}&code={code}`
:::

## Quản lý gói trả trước (Android) \{#manage-prepaid-plans-android\}

Nếu người dùng ứng dụng của bạn có thể mua [gói trả trước](https://developer.android.com/google/play/billing/subscriptions#prepaid-plans) (ví dụ: mua gói đăng ký không tự gia hạn cho vài tháng), bạn có thể bật [giao dịch đang chờ xử lý](https://developer.android.com/google/play/billing/subscriptions#pending) cho các gói trả trước.

```typescript showLineNumbers
adapty.activate("PUBLIC_SDK_KEY", {
    android: { pendingPrepaidPlansEnabled: true }
});
```

---


# File: react-native-restore-purchase
---

---
title: "Khôi phục giao dịch mua trong ứng dụng với React Native SDK"
description: "Tìm hiểu cách khôi phục giao dịch mua trong Adapty để đảm bảo trải nghiệm người dùng liền mạch."
---

Khôi phục giao dịch mua trên cả iOS và Android là tính năng cho phép người dùng lấy lại quyền truy cập vào nội dung đã mua trước đó — chẳng hạn như gói đăng ký hoặc in-app purchase — mà không bị tính phí thêm. Tính năng này đặc biệt hữu ích cho những người dùng đã gỡ cài đặt và cài lại ứng dụng, hoặc chuyển sang thiết bị mới và muốn truy cập nội dung đã mua trước đó mà không cần thanh toán lại.

:::note
Trong các paywall được xây dựng bằng [Paywall Builder](adapty-paywall-builder), giao dịch mua được khôi phục tự động mà không cần thêm code từ phía bạn. Nếu đó là trường hợp của bạn — bạn có thể bỏ qua bước này.
:::

Để khôi phục giao dịch mua khi bạn không dùng [Paywall Builder](adapty-paywall-builder) để tùy chỉnh paywall, hãy gọi phương thức `.restorePurchases()`:

```typescript showLineNumbers
try {
    const profile = await adapty.restorePurchases();
    const isSubscribed = profile.accessLevels['YOUR_ACCESS_LEVEL']?.isActive;
  
    if (isSubscribed) {
        // restore access
    }
} catch (error) {
    // handle the error
}
```

Tham số phản hồi:

| Tham số | Mô tả |
|---------|-----------|
| **Profile** | <p>Đối tượng [`AdaptyProfile`](https://react-native.adapty.io/interfaces/adaptyprofile). Model này chứa thông tin về mức độ truy cập, gói đăng ký và các sản phẩm mua một lần.</p><p>Kiểm tra **trạng thái mức độ truy cập** để xác định xem người dùng có quyền truy cập vào ứng dụng hay không.</p> |

:::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](sample-apps) của chúng tôi, nơi minh họa toàn bộ quá 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.

:::

---


# File: implement-observer-mode-react-native
---

---
title: "Triển khai Observer mode trong React Native SDK"
description: "Triển khai observer mode trong Adapty để theo dõi các sự kiện gói đăng ký của người dùng trong React Native SDK."
---

Nếu bạn đã có hệ thống mua hàng riêng và chưa sẵn sàng chuyển hoàn toàn sang Adapty, bạn có thể tìm hiểu về [Observer mode](observer-vs-full-mode). Ở dạng cơ bản, Observer Mode cung cấp analytics nâng cao và tích hợp liền mạch với các hệ thống attribution và analytics.

Nếu điều này phù hợp với nhu cầu của bạn, bạn chỉ cần:
1. Bật nó khi cấu hình Adapty SDK bằng cách đặt tham số `observerMode` thành `true`. Làm theo hướng dẫn thiết lập cho [React Native](sdk-installation-reactnative).
2. [Báo cáo các giao dịch](report-transactions-observer-mode-react-native) từ hệ thống mua hàng hiện có của bạn tới Adapty.

### Thiết lập Observer mode \{#observer-mode-setup\}

Bật Observer mode nếu bạn tự xử lý việc mua hàng và trạng thái gói đăng ký, và chỉ dùng Adapty để gửi sự kiện gói đăng ký và analytics.

:::important
Khi chạy ở Observer mode, Adapty SDK sẽ không đóng bất kỳ giao dịch nào, vì vậy hãy đảm bảo bạn tự xử lý điều đó.
:::

```typescript showLineNumbers title="App.tsx"

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  observerMode: true, // Enable observer mode
});
```

Các tham số:

| Tham số                     | Mô tả                                                        |
| --------------------------- | ------------------------------------------------------------ |
| observerMode                | Giá trị boolean điều khiển [Observer mode](observer-vs-full-mode). Giá trị mặc định là `false`. |

## Sử dụng paywall của Adapty trong Observer Mode \{#using-adapty-paywalls-in-observer-mode\}

Nếu bạn cũng muốn sử dụng các tính năng paywall và A/B test của Adapty, bạn hoàn toàn có thể — nhưng cần thêm một số thiết lập trong Observer mode. Đây là những gì bạn cần thực hiện ngoài các bước trên:

1. Hiển thị paywall như bình thường cho [remote config paywalls](present-remote-config-paywalls-react-native).
3. [Liên kết paywall](report-transactions-observer-mode-react-native) với các giao dịch mua hàng.

---


# File: report-transactions-observer-mode-react-native
---

---
title: "Báo cáo giao dịch trong Observer Mode trên React Native SDK"
description: "Báo cáo giao dịch mua hàng trong Adapty Observer Mode để theo dõi thông tin người dùng và doanh thu trên React Native SDK."
---

<Tabs groupId="sdk-version" queryString> 

<TabItem value="current" label="Adapty SDK v3.4+ (current)" default> 
Trong Observer mode, Adapty SDK không thể tự động theo dõi các giao dịch mua hàng thực hiện qua hệ thống thanh toán hiện có của bạn. Bạn cần báo cáo các giao dịch từ cửa hàng ứng dụng của mình. Điều quan trọng là phải thiết lập điều này **trước** khi phát hành ứng dụng để tránh sai sót trong phân tích.

Sử dụng `reportTransaction` để báo cáo từng giao dịch cho Adapty nhận biết.

:::warning

**Đừng bỏ qua việc báo cáo giao dịch!**
Nếu bạn không gọi `reportTransaction`, Adapty sẽ không nhận ra giao dịch, giao dịch đó sẽ không xuất hiện trong phân tích và sẽ không được gửi đến các tích hợp.

:::

Nếu bạn sử dụng paywall của Adapty, hãy đưa `variationId` vào khi báo cáo giao dịch. Điều này liên kết giao dịch mua hàng với paywall đã kích hoạt nó, đảm bảo phân tích paywall chính xác.

```typescript showLineNumbers
const variationId = paywall.variationId;

try {
    await adapty.reportTransaction(transactionId, variationId);
} catch (error) {
    // handle the `AdaptyError`
}
```

Tham số:

| Tham số       | Bắt buộc | Mô tả                                                        |
| ------------- | -------- | ------------------------------------------------------------ |
| transactionId | bắt buộc | <ul><li> Với iOS: Định danh của giao dịch.</li><li> Với Android: Định danh chuỗi (`purchase.getOrderId`) của giao dịch mua hàng, trong đó purchase là một instance của lớp [Purchase](https://developer.android.com/reference/com/android/billingclient/api/Purchase) trong thư viện billing.</li></ul> |
| variationId   | tùy chọn | Định danh chuỗi của biến thể. Bạn có thể lấy giá trị này qua thuộc tính `variationId` của đối tượng [AdaptyPaywall](https://react-native.adapty.io/interfaces/adaptypaywall). |

</TabItem>
<TabItem value="old" label="Adapty SDK 3.3.x (legacy)" default> 

Trong Observer mode, Adapty SDK không thể tự động theo dõi các giao dịch mua hàng thực hiện qua hệ thống thanh toán hiện có của bạn. Bạn cần báo cáo các giao dịch từ cửa hàng ứng dụng hoặc khôi phục chúng. Điều quan trọng là phải thiết lập điều này **trước** khi phát hành ứng dụng để tránh sai sót trong phân tích.

Sử dụng `reportTransaction` trên cả hai nền tảng để báo cáo từng giao dịch, và sử dụng `restorePurchases` trên Android như một bước bổ sung để đảm bảo Adapty nhận biết giao dịch.

:::warning

**Đừng bỏ qua việc báo cáo giao dịch!**
Nếu bạn không gọi các phương thức này, Adapty sẽ không nhận ra giao dịch, giao dịch đó sẽ không xuất hiện trong phân tích và sẽ không được gửi đến các tích hợp.

:::

Nếu bạn sử dụng paywall của Adapty, hãy đưa `variationId` vào khi báo cáo giao dịch. Điều này liên kết giao dịch mua hàng với paywall đã kích hoạt nó, đảm bảo phân tích paywall chính xác.

```typescript showLineNumbers
if (Platform.OS === 'android') {
    try {
        await adapty.restorePurchases();
    } catch (error) {
        // handle the error
    }
}

...

const variationId = paywall.variationId;

try {
    await adapty.reportTransaction(transactionId, variationId);
} catch (error) {
    // handle the `AdaptyError`
}
```

Tham số:

| Tham số       | Bắt buộc | Mô tả                                                        |
| ------------- | -------- | ------------------------------------------------------------ |
| transactionId | bắt buộc | <ul><li> Với iOS, StoreKit 1: đối tượng [SKPaymentTransaction](https://developer.apple.com/documentation/storekit/skpaymenttransaction).</li><li> Với iOS, StoreKit 2: đối tượng [Transaction](https://developer.apple.com/documentation/storekit/transaction).</li><li> Với Android: Định danh chuỗi (`purchase.getOrderId`) của giao dịch mua hàng, trong đó purchase là một instance của lớp [Purchase](https://developer.android.com/reference/com/android/billingclient/api/Purchase) trong thư viện billing.</li></ul> |
| variationId   | tùy chọn | Định danh chuỗi của biến thể. Bạn có thể lấy giá trị này qua thuộc tính `variationId` của đối tượng [AdaptyPaywall](https://react-native.adapty.io/interfaces/adaptypaywall). |

</TabItem>
<TabItem value="old2" label="Adapty SDK up to 3.2.x (legacy)" default> 

<Tabs groupId="current-os" queryString> 
<TabItem value="swift" label="iOS" default> 

**Báo cáo giao dịch**

- Các phiên bản đến 3.1.x tự động lắng nghe các giao dịch trên App Store, vì vậy không cần báo cáo thủ công.
- Phiên bản 3.2 không hỗ trợ Observer Mode.

</TabItem> 
<TabItem value="kotlin" label="Android and Android-based cross-platforms" default> 

**Báo cáo giao dịch**

Sử dụng `restorePurchases` để báo cáo giao dịch cho Adapty trong Observer Mode, như được giải thích trên trang [Restore Purchases in Mobile Code](react-native-restore-purchase).

:::warning
**Đừng bỏ qua việc báo cáo giao dịch!**
Nếu bạn không gọi `restorePurchases`, Adapty sẽ không nhận ra giao dịch, giao dịch đó sẽ không xuất hiện trong phân tích và sẽ không được gửi đến các tích hợp.
::: 

</TabItem>
</Tabs>

**Liên kết paywall với giao dịch**

Adapty SDK không thể xác định nguồn gốc của các giao dịch mua hàng vì bạn là người xử lý chúng. Do đó, nếu bạn dự định sử dụng paywall và/hoặc A/B test trong Observer mode, bạn cần liên kết giao dịch đến từ cửa hàng ứng dụng với paywall tương ứng trong code ứng dụng di động của mình. Điều này rất quan trọng cần thực hiện đúng trước khi phát hành ứng dụng, nếu không sẽ dẫn đến sai sót trong phân tích.

```typescript 
const variationId = paywall.variationId;

try {
    await adapty.setVariationId('transactionId', variationId);
} catch (error) {
    // handle the `AdaptyError`
}
```

Tham số yêu cầu:

| Tham số       | Bắt buộc | Mô tả                                                        |
| ------------- | -------- | ------------------------------------------------------------ |
| transactionId | bắt buộc | <p>Với iOS, StoreKit 1: đối tượng [SKPaymentTransaction](https://developer.apple.com/documentation/storekit/skpaymenttransaction).</p><p>Với iOS, StoreKit 2: đối tượng [Transaction](https://developer.apple.com/documentation/storekit/transaction).</p><p>Với Android: Định danh chuỗi (purchase.getOrderId của giao dịch mua hàng, trong đó purchase là một instance của lớp [Purchase](https://developer.android.com/reference/com/android/billingclient/api/Purchase) trong thư viện billing.</p> |
| variationId   | bắt buộc | Định danh chuỗi của biến thể. Bạn có thể lấy giá trị này qua thuộc tính `variationId` của đối tượng [AdaptyPaywall](https://react-native.adapty.io/interfaces/adaptypaywall). |

</TabItem> 
</Tabs>

---


# File: react-native-troubleshoot-purchases
---

---
title: "Xử lý sự cố mua hàng trong React Native SDK"
description: "Xử lý sự cố mua hàng trong React Native SDK"
---

Hướng dẫn này giúp bạn giải quyết các vấn đề thường gặp khi triển khai mua hàng thủ công trong React Native SDK.

## makePurchase được gọi thành công nhưng hồ sơ người dùng không được cập nhật \{#makepurchase-is-called-successfully-but-the-profile-is-not-being-updated\}

**Vấn đề**: Phương thức `makePurchase` hoàn tất thành công, nhưng hồ sơ người dùng và trạng thái gói đăng ký không được cập nhật trong Adapty.

**Nguyên nhân**: Điều này thường cho thấy thiết lập Google Play Store chưa hoàn chỉnh hoặc có vấn đề cấu hình.

**Giải pháp**: Đảm bảo bạn đã hoàn thành tất cả [các bước thiết lập Google Play](initial-android).

## makePurchase bị gọi hai lần \{#makepurchase-is-invoked-twice\}

**Vấn đề**: Phương thức `makePurchase` đang được gọi nhiều lần cho cùng một giao dịch mua.

**Nguyên nhân**: Điều này thường xảy ra khi flow mua hàng được kích hoạt nhiều lần do vấn đề quản lý trạng thái giao diện hoặc người dùng thao tác quá nhanh.

**Giải pháp**: Đảm bảo bạn đã hoàn thành tất cả [các bước thiết lập Google Play](initial-android).

## AdaptyError.cantMakePayments trong observer mode \{#adaptyer-ror-cantmakepayments-in-observer-mode\}

**Vấn đề**: Bạn nhận được lỗi `AdaptyError.cantMakePayments` khi dùng `makePurchase` ở observer mode.

**Nguyên nhân**: Trong observer mode, bạn cần tự xử lý việc mua hàng ở phía mình, không dùng phương thức `makePurchase` của Adapty.

**Giải pháp**: Nếu bạn dùng `makePurchase` để xử lý mua hàng, hãy tắt observer mode. Bạn chỉ được chọn một trong hai: dùng `makePurchase` hoặc tự xử lý mua hàng trong observer mode. Xem [Triển khai Observer mode](implement-observer-mode-react-native) để biết thêm chi tiết.

## Lỗi Adapty: (code: 103, message: Play Market request failed on purchases updated: responseCode=3, debugMessage=Billing Unavailable, detail: null) \{#adapty-error-code-103-message-play-market-request-failed-on-purchases-updated-responsecode3-debugmessagebilling-unavailable-detail-null\}

**Vấn đề**: Bạn nhận được lỗi billing không khả dụng từ Google Play Store.

**Nguyên nhân**: Lỗi này không liên quan đến Adapty. Đây là lỗi từ Google Play Billing Library cho biết billing không khả dụng trên thiết bị.

**Giải pháp**: Lỗi này không liên quan đến Adapty. Bạn có thể xem thêm thông tin trong tài liệu Play Store: [Handle BillingResult response codes](https://developer.android.com/google/play/billing/errors#billing_unavailable_error_code_3) | Play Billing | Android Developers.

## Không tìm thấy makePurchasesCompletionHandlers \{#not-found-makepurchasescompletionhandlers\}

**Vấn đề**: Bạn gặp sự cố với `makePurchasesCompletionHandlers` không được tìm thấy.

**Nguyên nhân**: Điều này thường liên quan đến vấn đề kiểm thử trong sandbox.

**Giải pháp**: Tạo một người dùng sandbox mới và thử lại. Cách này thường giải quyết được các vấn đề liên quan đến purchase completion handler trong sandbox.

## Các vấn đề khác \{#other-issues\}

**Vấn đề**: Bạn đang gặp các sự cố liên quan đến mua hàng khác chưa được đề cập ở trên.

**Giải pháp**: Nếu cần, hãy migrate SDK lên phiên bản mới nhất theo [hướng dẫn migration](react-native-sdk-migration-guides). Nhiều vấn đề đã được khắc phục trong các phiên bản SDK mới hơn.

---


# File: react-native-identifying-users
---

---
title: "Xác định người dùng trong React Native SDK"
description: "Tìm hiểu cách xác định người dùng trong ứng dụng React Native với Adapty SDK."
---

Adapty tạo một internal profile ID cho mỗi người dùng. Tuy nhiên, nếu bạn có hệ thống xác thực riêng, bạn nên đặt Customer User ID của mình. Bạn có thể tìm người dùng theo Customer User ID trong mục [Profiles](profiles-crm) và sử dụng nó trong [server-side API](getting-started-with-server-side-api), vốn sẽ được gửi đến tất cả các tích hợp.

### Đặt customer user ID khi cấu hình \{#setting-customer-user-id-on-configuration\}

Nếu bạn đã có user ID trong quá trình cấu hình, chỉ cần truyền nó làm tham số `customerUserId` vào phương thức `.activate()`:

```typescript showLineNumbers
adapty.activate("PUBLIC_SDK_KEY", {
    customerUserId: "YOUR_USER_ID"
});
```

:::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](sample-apps) của chúng tôi, nơi minh họa toàn bộ quá 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.

:::

### Đặt customer user ID sau khi cấu hình \{#setting-customer-user-id-after-configuration\}

Nếu bạn chưa có user ID trong cấu hình SDK, bạn có thể đặt nó sau bất kỳ lúc nào bằng phương thức `.identify()`. Các trường hợp phổ biến nhất khi dùng phương thức này là sau khi đăng ký hoặc đăng nhập, khi người dùng chuyển từ trạng thái ẩn danh sang người dùng đã xác thực.

```typescript showLineNumbers
try {
    await adapty.identify("YOUR_USER_ID");
    // successfully identified
} catch (error) {
    // handle the error
}
```

Tham số yêu cầu:

- **Customer User ID** (bắt buộc): chuỗi định danh người dùng.

:::warning
Gửi lại dữ liệu người dùng quan trọng

Trong một số trường hợp, chẳng hạn khi người dùng đăng nhập lại vào tài khoản, máy chủ Adapty đã có thông tin về người dùng đó. Trong các tình huống này, Adapty SDK sẽ tự động chuyển sang làm việc với người dùng mới. Nếu bạn đã truyền dữ liệu cho người dùng ẩn danh, chẳng hạn như thuộc tính tùy chỉnh hoặc attribution từ các mạng bên thứ ba, bạn cần gửi lại dữ liệu đó cho người dùng đã được xác định.

Ngoài ra, bạn cũng cần gọi lại tất cả paywall và sản phẩm sau khi xác định người dùng, vì dữ liệu của người dùng mới có thể khác.
:::

### Đăng xuất và đăng nhập \{#logging-out-and-logging-in\}

Bạn có thể đăng xuất người dùng bất cứ lúc nào bằng cách gọi phương thức `.logout()`:

```typescript showLineNumbers
try {
    await adapty.logout();
    // successful logout
} catch (error) {
    // handle the error
}
```

Sau đó bạn có thể đăng nhập người dùng bằng phương thức `.identify()`.

## Gán `appAccountToken` (iOS) \{#assign-appaccounttoken-ios\}

[`appAccountToken`](https://developer.apple.com/documentation/storekit/product/purchaseoption/appaccounttoken(_:)) là một **UUID** cho phép bạn liên kết các giao dịch App Store với danh tính người dùng nội bộ của mình.  
StoreKit gắn token này vào mỗi giao dịch, giúp backend của bạn có thể khớp dữ liệu App Store với người dùng.

Hãy sử dụng một UUID ổn định được tạo cho mỗi người dùng và tái sử dụng nó cho cùng một tài khoản trên nhiều thiết bị.
Điều này đảm bảo rằng các lần mua và thông báo App Store luôn được liên kết chính xác.

Bạn có thể đặt token theo hai cách – trong quá trình kích hoạt SDK hoặc khi xác định người dùng.

:::important
Bạn phải luôn truyền `appAccountToken` cùng với `customerUserId`.
Nếu chỉ truyền token mà không có `customerUserId`, nó sẽ không được đưa vào giao dịch.
:::

```typescript showLineNumbers
// During configuration:
adapty.activate("PUBLIC_SDK_KEY", {
    customerUserId: "YOUR_USER_ID",
    ios: { appAccountToken: "YOUR_APP_ACCOUNT_TOKEN" },
});

// Or when identifying users
try {
    await adapty.identify("YOUR_USER_ID", {
        ios: {appAccountToken: 'YOUR_APP_ACCOUNT_TOKEN'}
    });
    // successfully identified
} catch (error) {
    // handle the error
}
```

### Đặt obfuscated account ID (Android) \{#set-obfuscated-account-ids-android\}

Google Play yêu cầu obfuscated account ID cho một số trường hợp sử dụng nhất định nhằm tăng cường quyền riêng tư và bảo mật cho người dùng. Các ID này giúp Google Play xác định giao dịch mua trong khi vẫn giữ thông tin người dùng ẩn danh, điều này đặc biệt quan trọng để ngăn chặn gian lận và phân tích.

Bạn có thể cần đặt các ID này nếu ứng dụng của bạn xử lý dữ liệu người dùng nhạy cảm hoặc nếu bạn phải tuân thủ các quy định về quyền riêng tư cụ thể. Các obfuscated ID cho phép Google Play theo dõi giao dịch mua mà không làm lộ định danh người dùng thực.

```typescript showLineNumbers
// During configuration:
adapty.activate("PUBLIC_SDK_KEY", {
    customerUserId: "YOUR_USER_ID",
    android: { obfuscatedAccountId: 'YOUR_OBFUSCATED_ACCOUNT_ID' }
});

// Or when identifying users
try {
    await adapty.identify("YOUR_USER_ID", {
        android: { obfuscatedAccountId: 'YOUR_OBFUSCATED_ACCOUNT_ID' }
    });
    // successfully identified
} catch (error) {
    // handle the error
}
```

## Phát hiện người dùng trên nhiều thiết bị \{#detect-users-across-devices\}

---
no_index: true
---

Khi SDK được kích hoạt, nó tự động đọc các quyền hiện có của người dùng từ StoreKit (iOS) hoặc Google Play Billing (Android) và đồng bộ chúng với backend của Adapty. Một gói đăng ký đang hoạt động sẽ xuất hiện trên hồ sơ người dùng Adapty mà không cần ứng dụng gọi `restorePurchases`.

Điều **không** xảy ra tự động là nhận diện rằng một hồ sơ người dùng trên thiết bị mới thuộc về cùng một người dùng như hồ sơ trên thiết bị ban đầu. Adapty khớp các hồ sơ người dùng theo Customer User ID, vì vậy tính liên tục danh tính phụ thuộc vào những gì bạn sử dụng làm CUID.

**Những gì Adapty có thể phát hiện trên nhiều thiết bị**

| Cài đặt của bạn | Adapty phát hiện được gì | Bạn phải làm gì |
| --- | --- | --- |
| Customer User ID = `device_id` (không đăng nhập ứng dụng) | Thiết bị mới nhận được CUID khác và do đó có hồ sơ người dùng khác. Gói đăng ký đồng bộ với hồ sơ người dùng mới thông qua sự kiện **Access level updated**, nhưng `subscription_started` không kích hoạt — hồ sơ người dùng mới được coi là người kế thừa của giao dịch mua ban đầu. Các phân tích dựa trên `subscription_started` sẽ đếm thiếu những người dùng quay lại. | Sử dụng ID tài khoản ổn định làm Customer User ID để người dùng quay lại khớp với hồ sơ người dùng hiện có trên các thiết bị. |
| Customer User ID = ID tài khoản ổn định (đăng nhập trên mọi thiết bị) | SDK tự động đồng bộ gói đăng ký khi `activate()`, và `identify()` khớp hồ sơ người dùng hiện có theo CUID. | Không cần cài đặt thêm — cả danh tính lẫn gói đăng ký đều được xử lý tự động. |
| Người kế thừa Apple Family Sharing | Thành viên gia đình nhận gói đăng ký thông qua sự kiện **Access level updated** — `subscription_started` không kích hoạt. | Lắng nghe sự kiện **Access level updated**. Xem [Apple Family Sharing](apple-family-sharing) để biết ma trận sự kiện đầy đủ. |
| Cùng tài khoản Apple/Google, người dùng khác nhau trong ứng dụng | Hồ sơ người dùng đầu tiên ghi lại giao dịch mua trở thành hồ sơ cha. Các hồ sơ người dùng tiếp theo thấy gói đăng ký thông qua chuỗi kế thừa, với một sự kiện **Access level updated**. | Yêu cầu đăng nhập, sau đó chọn [chế độ chia sẻ](sharing-paid-access-between-user-accounts) phù hợp với mô hình của bạn. |

**Khôi phục giao dịch mua trên thiết bị mới**

Hiển thị nút "Khôi phục giao dịch mua" do người dùng khởi tạo trên paywall của bạn. Apple App Review (hướng dẫn 3.1.1) yêu cầu có nút này, và nó đóng vai trò dự phòng khi quá trình đồng bộ tự động bỏ sót một trường hợp đặc biệt. Nút này nên gọi `restorePurchases` trên SDK của bạn.

Không cần gọi `restorePurchases` theo chương trình khi khởi chạy lần đầu trong điều kiện sử dụng bình thường — SDK đã thực hiện tương đương khi `activate()`. Chỉ dùng các lệnh gọi theo chương trình để buộc kiểm tra biên lai mới, ví dụ khi debug trường hợp mất quyền truy cập sau khi `activate()` đã hoàn thành.

---


# File: react-native-setting-user-attributes
---

---
title: "Thiết lập thuộc tính người dùng trong React Native SDK"
description: "Tìm hiểu cách cập nhật thuộc tính người dùng và dữ liệu hồ sơ trong ứng dụng React Native của bạn với Adapty SDK."
---

Bạn có thể thiết lập các thuộc tính tùy chọn như email, số điện thoại, v.v. cho người dùng ứng dụng của mình. Sau đó, bạn có thể dùng các thuộc tính này để tạo [phân khúc](segments) người dùng hoặc đơn giản là xem chúng trong CRM.

### Thiết lập thuộc tính người dùng \{#setting-user-attributes\}

Để thiết lập thuộc tính người dùng, gọi phương thức `.updateProfile()`:

```typescript showLineNumbers
// Only for TypeScript validation

const params: AdaptyProfileParameters = {
    email: 'email@email.com',
    phoneNumber: '+18888888888',
    firstName: 'John',
    lastName: 'Appleseed',
    gender: 'other',
    birthday: new Date().toISOString(),
};

try {
    await adapty.updateProfile(params);
} catch (error) {
    // handle `AdaptyError`
}
```

Lưu ý rằng các thuộc tính bạn đã thiết lập trước đó bằng phương thức `updateProfile` sẽ không bị xóa.

:::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](sample-apps) của chúng tôi, nơi minh họa toàn bộ quá 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.

:::

### Danh sách các key được phép \{#the-allowed-keys-list\}

Các key `<Key>` được phép của `AdaptyProfileParameters.Builder` và các giá trị `<Value>` tương ứng được liệt kê bên dưới:

| Key | Value |
|---|-----|
| <p>email</p><p>phoneNumber</p><p>firstName</p><p>lastName</p> | String |
| gender | Enum, các giá trị cho phép là: `female`, `male`, `other` |
| birthday | Date |

### Thuộc tính tùy chỉnh của người dùng \{#custom-user-attributes\}

Bạn có thể thiết lập các thuộc tính tùy chỉnh của riêng mình. Những thuộc tính này thường liên quan đến cách sử dụng ứng dụng. Ví dụ, với ứng dụng thể dục, chúng có thể là số buổi tập mỗi tuần; với ứng dụng học ngôn ngữ, chúng có thể là trình độ kiến thức của người dùng, v.v. Bạn có thể dùng chúng trong các phân khúc để tạo paywall và ưu đãi có mục tiêu, đồng thời dùng trong analytics để tìm ra chỉ số sản phẩm nào ảnh hưởng nhiều nhất đến doanh thu.

```typescript showLineNumbers
try {
  await adapty.updateProfile({
    codableCustomAttributes: {
      key_1: 'value_1',
      key_2: 2,
    },
  });
} catch (error) {
    // handle `AdaptyError`
}
```

Để xóa một key hiện có, sử dụng phương thức `.withRemoved(customAttributeForKey:)`:

```typescript showLineNumbers
try {
  // to remove a key, pass null as its value
  await adapty.updateProfile({
    codableCustomAttributes: {
      key_1: null,
      key_2: null,
    },
  });
} catch (error) {
    // handle `AdaptyError`
}
```

Đôi khi bạn cần biết những thuộc tính tùy chỉnh nào đã được thiết lập trước đó. Để làm điều này, hãy sử dụng trường `customAttributes` của đối tượng `AdaptyProfile`.

:::warning
Lưu ý rằng giá trị của `customAttributes` có thể không phải là mới nhất, vì thuộc tính người dùng có thể được gửi từ nhiều thiết bị khác nhau vào bất kỳ lúc nào, nên các thuộc tính trên server có thể đã thay đổi sau lần đồng bộ cuối cùng.
:::

### Giới hạn \{#limits\}

- Tối đa 30 thuộc tính tùy chỉnh mỗi người dùng
- Tên key dài tối đa 30 ký tự. Tên key có thể bao gồm các ký tự chữ và số cùng với bất kỳ ký tự nào sau đây: `_`  `-` `.`
- Giá trị có thể là chuỗi hoặc số thực (float) với tối đa 50 ký tự.

---


# File: react-native-listen-subscription-changes
---

---
title: "Kiểm tra trạng thái gói đăng ký trong React Native SDK"
description: "Theo dõi và quản lý trạng thái gói đăng ký người dùng trong Adapty để cải thiện khả năng giữ chân khách hàng trong ứng dụng React Native của bạn."
---

Với Adapty, việc theo dõi trạng thái gói đăng ký trở nên rất đơn giản. Bạn không cần phải chèn thủ công các ID sản phẩm vào code. Thay vào đó, bạn có thể dễ dàng xác nhận trạng thái gói đăng ký của người dùng bằng cách kiểm tra [mức độ truy cập](access-level) đang hoạt động.

<details>
   <summary>Trước khi bắt đầu kiểm tra trạng thái gói đăng ký (Nhấn để mở rộng)</summary>

- Đối với iOS, hãy thiết lập [App Store Server Notifications](enable-app-store-server-notifications)
- Đối với Android, hãy thiết lập [Real-time Developer Notifications (RTDN)](enable-real-time-developer-notifications-rtdn)
</details>

## Mức độ truy cập và đối tượng AdaptyProfile \{#access-level-and-the-adaptyprofile-object\}

Mức độ truy cập là các thuộc tính của đối tượng [AdaptyProfile](https://react-native.adapty.io/interfaces/adaptyprofile). Chúng tôi khuyến nghị lấy hồ sơ người dùng khi ứng dụng khởi động, chẳng hạn như khi bạn [xác định người dùng](react-native-identifying-users#setting-customer-user-id-on-configuration), rồi cập nhật lại mỗi khi có thay đổi. Bằng cách này, bạn có thể sử dụng đối tượng hồ sơ mà không cần liên tục gửi yêu cầu lấy dữ liệu.

Để nhận thông báo khi hồ sơ người dùng được cập nhật, hãy lắng nghe các thay đổi như mô tả trong phần [Lắng nghe cập nhật hồ sơ, bao gồm mức độ truy cập](react-native-listen-subscription-changes) bên dưới.

:::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](sample-apps) của chúng tôi, nơi minh họa toàn bộ quá 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.

:::

## Lấy mức độ truy cập từ máy chủ \{#retrieving-the-access-level-from-the-server\}

Để lấy mức độ truy cập từ máy chủ, sử dụng phương thức `.getProfile()`:

```typescript showLineNumbers
try {
    const profile = await adapty.getProfile();
} catch (error) {
  // handle the error
}
```

Các tham số phản hồi:

| Tham số | Mô tả                                                  |
| --------- | ------------------------------------------------------------ |
| Profile   | <p>Một đối tượng [AdaptyProfile](https://react-native.adapty.io/interfaces/adaptyprofile). Thông thường, bạn chỉ cần kiểm tra trạng thái mức độ truy cập của hồ sơ để xác định xem người dùng có quyền truy cập premium vào ứng dụng hay không.</p><p></p><p>Phương thức `.getProfile` cung cấp kết quả mới nhất vì nó luôn cố gắng truy vấn API. Nếu vì lý do nào đó (ví dụ: không có kết nối internet), Adapty SDK không thể lấy thông tin từ máy chủ, dữ liệu từ bộ nhớ cache sẽ được trả về. Cần lưu ý rằng Adapty SDK cập nhật cache của `AdaptyProfile` thường xuyên để giữ thông tin này luôn cập nhật nhất có thể.</p> |

Phương thức `.getProfile()` cung cấp hồ sơ người dùng, từ đó bạn có thể lấy trạng thái mức độ truy cập. Bạn có thể có nhiều mức độ truy cập trong một ứng dụng. Ví dụ: nếu bạn có ứng dụng báo và bán gói đăng ký cho các chủ đề khác nhau một cách độc lập, bạn có thể tạo các mức độ truy cập "sports" và "science". Nhưng hầu hết thời gian, bạn chỉ cần một mức độ truy cập — trong trường hợp đó, bạn có thể dùng mức độ truy cập mặc định "premium".

Dưới đây là ví dụ kiểm tra mức độ truy cập "premium" mặc định:

```typescript showLineNumbers
try {
    const profile = await adapty.getProfile();
    
  const isActive = profile.accessLevels?.["premium"]?.isActive;
    if (isActive) {
        // grant access to premium features
    }
} catch (error) {
    // handle the error
}
```

### Lắng nghe cập nhật trạng thái gói đăng ký \{#listening-for-subscription-status-updates\}

Mỗi khi gói đăng ký của người dùng thay đổi, Adapty sẽ kích hoạt một sự kiện.

Để nhận tin nhắn từ Adapty, bạn cần thực hiện một số cấu hình bổ sung:

```typescript showLineNumbers
// Create an "onLatestProfileLoad" event listener
adapty.addEventListener('onLatestProfileLoad', profile => {
    // handle any changes to subscription state
});
```

Adapty cũng kích hoạt một sự kiện khi ứng dụng khởi động. Trong trường hợp này, trạng thái gói đăng ký được lưu trong cache sẽ được truyền vào.

### Cache trạng thái gói đăng ký \{#subscription-status-cache\}

Cache được tích hợp trong Adapty SDK lưu trữ trạng thái gói đăng ký của hồ sơ người dùng. Điều này có nghĩa là ngay cả khi máy chủ không khả dụng, dữ liệu được lưu trong cache vẫn có thể được truy cập để cung cấp thông tin về trạng thái gói đăng ký của hồ sơ.

Tuy nhiên, cần lưu ý rằng không thể yêu cầu dữ liệu trực tiếp từ cache. SDK định kỳ truy vấn máy chủ mỗi phút để kiểm tra các cập nhật hoặc thay đổi liên quan đến hồ sơ. Nếu có bất kỳ thay đổi nào, chẳng hạn như giao dịch mới hoặc các cập nhật khác, chúng sẽ được đồng bộ vào dữ liệu cache để giữ cho nó luôn nhất quán với máy chủ.

---


# File: react-native-deal-with-att
---

---
title: "Xử lý ATT trong React Native SDK"
description: "Bắt đầu với Adapty trên React Native để đơn giản hóa việc thiết lập và quản lý gói đăng ký."
---

Nếu ứng dụng của bạn sử dụng framework AppTrackingTransparency và hiển thị yêu cầu ủy quyền theo dõi ứng dụng cho người dùng, bạn cần gửi [trạng thái ủy quyền](https://developer.apple.com/documentation/apptrackingtransparency/attrackingmanager/authorizationstatus/) đến Adapty.

```typescript showLineNumbers

try {
  await adapty.updateProfile({
    // you can also pass a string value (validated via tsc) if you prefer
    appTrackingTransparencyStatus: AppTrackingTransparencyStatus.Authorized,
  });
} catch (error) {
  // handle `AdaptyError`
}
```

:::warning
Chúng tôi khuyến nghị bạn gửi giá trị này càng sớm càng tốt khi nó thay đổi — chỉ như vậy dữ liệu mới được chuyển đến các tích hợp bạn đã cấu hình một cách kịp thời.
:::

---


# File: kids-mode-react-native
---

---
title: "Chế Độ Trẻ Em trong React Native SDK"
description: "Dễ dàng bật Chế Độ Trẻ Em để tuân thủ chính sách của Apple và Google. Không thu thập IDFA, GAID hay dữ liệu quảng cáo trong React Native SDK."
---

Nếu ứng dụng React Native của bạn dành cho trẻ em, bạn phải tuân theo chính sách của [Apple](https://developer.apple.com/kids/) và [Google](https://support.google.com/googleplay/android-developer/answer/9893335). Nếu bạn đang dùng Adapty SDK, một vài bước đơn giản sẽ giúp bạn cấu hình SDK để đáp ứng các chính sách này và vượt qua quá trình xét duyệt của cửa hàng.

## Cần làm gì? \{#whats-required\}

Bạn cần cấu hình Adapty SDK để tắt việc thu thập:

- [IDFA (Identifier for Advertisers)](https://en.wikipedia.org/wiki/Identifier_for_Advertisers) (iOS)
- [Android Advertising ID (AAID/GAID)](https://support.google.com/googleplay/android-developer/answer/6048248) (Android)
- [Địa chỉ IP](https://www.ftc.gov/system/files/ftc_gov/pdf/p235402_coppa_application.pdf)

Ngoài ra, chúng tôi khuyến nghị sử dụng customer user ID một cách thận trọng. ID người dùng có định dạng `<FirstName.LastName>` chắc chắn sẽ bị coi là thu thập dữ liệu cá nhân, tương tự như việc dùng email. Đối với Chế Độ Trẻ Em, phương pháp tốt nhất là sử dụng các định danh được tạo ngẫu nhiên hoặc ẩn danh (ví dụ: hashed ID hoặc UUID do thiết bị tạo ra) để đảm bảo tuân thủ.

## Bật Chế Độ Trẻ Em \{#enabling-kids-mode\}

### Cập nhật trong Adapty Dashboard \{#updates-in-the-adapty-dashboard\}

Trong Adapty Dashboard, bạn cần tắt việc thu thập địa chỉ IP. Để làm điều này, vào [App settings](https://app.adapty.io/settings/general) và nhấn **Disable IP address collection** trong mục **Collect users' IP address**.

### Cập nhật trong code ứng dụng di động \{#updates-in-your-mobile-app-code\}

Để tuân thủ các chính sách, hãy tắt việc thu thập IDFA (iOS), GAID/AAID (Android) và địa chỉ IP của người dùng khi bạn kích hoạt Adapty SDK:

```typescript showLineNumbers title="App.tsx"

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  // Disable IP address collection
  ipAddressCollectionDisabled: true,

  // Disable IDFA collection on iOS
  ios: {
    idfaCollectionDisabled: true,
  },

  // Disable Google Advertising ID collection on Android
  android: {
    adIdCollectionDisabled: true,
  },
});
```

### Cập nhật trong Android manifest \{#updates-in-your-android-manifest\}

:::note
Nếu ứng dụng của bạn chỉ dành cho trẻ em **và** biên dịch với Android 13 (API 33) trở lên, Google Play yêu cầu bạn không được yêu cầu quyền `AD_ID`. Một SDK khác trong ứng dụng của bạn (analytics, attribution, hoặc quảng cáo) có thể thêm quyền này thông qua quá trình manifest merging. Việc đặt `adIdCollectionDisabled` chỉ ngăn Adapty thu thập ID, nhưng không xóa quyền mà một SDK khác đã khai báo.
:::

Để xóa quyền đó, hãy thêm đoạn sau vào bên trong phần tử `<manifest>` của `android/app/src/main/AndroidManifest.xml`. Phần tử `<manifest>` phải khai báo `xmlns:tools="http://schemas.android.com/tools"`.

```xml showLineNumbers title="AndroidManifest.xml"
<uses-permission
    android:name="com.google.android.gms.permission.AD_ID"
    tools:node="remove" />
```

---


# File: react-native-get-onboardings
---

---
title: "Lấy onboarding trong React Native SDK"
description: "Tìm hiểu cách lấy onboarding trong Adapty cho React Native."
---

Sau khi [bạn thiết kế phần giao diện cho onboarding](design-onboarding) bằng builder trong Adapty Dashboard, bạn có thể hiển thị nó trong ứng dụng React Native của mình. Bước đầu tiên trong quá trình này là lấy onboarding gắn với placement và cấu hình view của nó như mô tả bên dưới.

Trước khi bắt đầu, hãy đảm bảo rằng:

1. Bạn đã cài đặt [Adapty React Native SDK](sdk-installation-reactnative) phiên bản 3.8.0 trở lên.
2. Bạn đã [tạo một onboarding](create-onboarding).
3. Bạn đã thêm onboarding vào một [placement](placements).

## Lấy onboarding \{#fetch-onboarding\}

Khi bạn tạo một [onboarding](onboardings) bằng builder không cần code của chúng tôi, nó được lưu trữ dưới dạng một container chứa cấu hình mà ứng dụng của bạn cần lấy và hiển thị. Container này quản lý toàn bộ trải nghiệm — nội dung nào xuất hiện, cách trình bày, và cách xử lý các tương tác của người dùng (như câu trả lời quiz hay dữ liệu nhập vào form). Container cũng tự động theo dõi các sự kiện analytics, nên bạn không cần tự triển khai tính năng theo dõi view riêng.

Để có hiệu suất tốt nhất, hãy lấy cấu hình onboarding sớm để hình ảnh có đủ thời gian tải xuống trước khi hiển thị cho người dùng.

Để lấy một onboarding, sử dụng phương thức `getOnboarding`:

```typescript showLineNumbers
try {
    const placementId = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const onboarding = await adapty.getOnboarding(placementId, locale);
    // the requested onboarding
} catch (error) {
    // handle the error
}
```

Sau đó, gọi phương thức `createOnboardingView` để tạo một instance view.

:::warning
Kết quả của phương thức `createOnboardingView` chỉ có thể được sử dụng một lần. Nếu bạn cần sử dụng lại, hãy gọi lại phương thức `createOnboardingView`. Gọi nó hai lần mà không tạo lại có thể dẫn đến lỗi `AdaptyUIError.viewAlreadyPresented`.
:::

```typescript showLineNumbers
// for the Adapty SDK < 3.14 – import {createOnboardingView} from 'react-native-adapty/dist/ui';

if (onboarding.hasViewConfiguration) {
    try {
        const view = await createOnboardingView(onboarding);
    } catch (error) {
        // handle the error
    }
} else {
    //use your custom logic
}
```

Các tham số:

| Tham số           | Bắt buộc | Mô tả                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **placementId**   | bắt buộc | Định danh của [Placement](placements) mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **locale**        | <p>tùy chọn</p><p>mặc định: `en`</p> | <p>Định danh của bản dịch onboarding. Tham số này phải là mã ngôn ngữ gồm một hoặc hai subtag phân cách bằng dấu trừ (**-**). Subtag đầu tiên là ngôn ngữ, subtag thứ hai là vùng.</p><p></p><p>Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha (Brazil).</p><p>Xem [Localizations and locale codes](localizations-and-locale-codes) để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **fetchPolicy**   | mặc định: `.reloadRevalidatingCacheData` | <p>Theo mặc định, SDK sẽ cố tải dữ liệu từ server và trả về dữ liệu được cache trong trường hợp thất bại. Chúng tôi khuyến nghị tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.</p><p></p><p>Tuy nhiên, nếu bạn cho rằng người dùng của mình có kết nối internet không ổn định, hãy cân nhắc dùng `.returnCacheDataElseLoad` để trả về dữ liệu cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng họ sẽ có thời gian tải nhanh hơn dù kết nối mạng không ổn định. Cache được cập nhật thường xuyên, vì vậy có thể dùng nó trong phiên để tránh các request mạng.</p><p></p><p>Lưu ý rằng cache vẫn tồn tại khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt ứng dụng hoặc thông qua việc dọn dẹp thủ công.</p><p></p><p>Adapty SDK lưu trữ onboarding cục bộ trong hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và onboarding dự phòng. Chúng tôi cũng sử dụng CDN để tải onboarding nhanh hơn và một server dự phòng độc lập trong trường hợp CDN không truy cập được. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản onboarding mới nhất trong khi vẫn đảm bảo độ tin cậy ngay cả khi kết nối internet hạn chế.</p> |
| **loadTimeoutMs** | mặc định: 5 giây | <p>Giá trị này giới hạn thời gian chờ cho phương thức này. Nếu hết thời gian chờ, dữ liệu cache hoặc fallback cục bộ sẽ được trả về.</p><p>Lưu ý rằng trong một số trường hợp hiếm gặp, phương thức này có thể hết thời gian chờ muộn hơn một chút so với giá trị được chỉ định trong `loadTimeout`, do thao tác có thể bao gồm nhiều request khác nhau bên dưới.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

Các tham số trả về:

| Tham số | Mô tả                                                                                                                                                |
|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Onboarding      | Một đối tượng [`AdaptyOnboarding`](https://react-native.adapty.io/interfaces/adaptyonboarding) gồm: định danh và cấu hình onboarding, Remote Config, và một số thuộc tính khác. |

## Tăng tốc lấy onboarding với onboarding đối tượng mặc định \{#speed-up-onboarding-fetching-with-default-audience-onboarding\}

Thông thường, onboarding được lấy gần như ngay lập tức, vì vậy bạn không cần lo lắng về việc tăng tốc quá trình này. Tuy nhiên, trong những trường hợp bạn có nhiều đối tượng và onboarding, và người dùng có kết nối internet yếu, việc lấy onboarding có thể mất nhiều thời gian hơn bạn muốn. Trong những tình huống đó, bạn có thể muốn hiển thị một onboarding mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị onboarding nào.

Để giải quyết vấn đề này, bạn có thể sử dụng phương thức `getOnboardingForDefaultAudience`, phương thức này lấy onboarding của placement đã chỉ định cho đối tượng **All Users**. Tuy nhiên, điều quan trọng cần hiểu là cách tiếp cận được khuyến nghị là lấy onboarding bằng phương thức `getOnboarding`, như đã mô tả trong phần [Lấy onboarding](#fetch-onboarding) ở trên.

:::warning
Hãy cân nhắc dùng `getOnboarding` thay vì `getOnboardingForDefaultAudience`, vì phương thức sau có những hạn chế quan trọng:

- **Vấn đề tương thích**: Có thể gây ra sự cố khi hỗ trợ nhiều phiên bản ứng dụng, đòi hỏi thiết kế tương thích ngược hoặc chấp nhận rằng các phiên bản cũ hơn có thể hiển thị không chính xác.
- **Không cá nhân hóa**: Chỉ hiển thị nội dung cho đối tượng "All Users", bỏ qua việc nhắm mục tiêu dựa trên quốc gia, attribution, hoặc thuộc tính tùy chỉnh.

Nếu tốc độ lấy nhanh hơn vượt trội hơn những hạn chế này cho trường hợp sử dụng của bạn, hãy dùng `getOnboardingForDefaultAudience` như bên dưới. Nếu không, hãy dùng `getOnboarding` như đã mô tả [ở trên](#fetch-onboarding).
:::

```typescript showLineNumbers
try {
    const placementId = 'YOUR_PLACEMENT_ID';
    const locale = 'en';

    const onboarding = await adapty.getOnboardingForDefaultAudience(placementId, locale);
    // the requested onboarding
} catch (error) {
    // handle the error
}
```

Các tham số:

| Tham số | Bắt buộc | Mô tả                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **placementId** | bắt buộc | Định danh của [Placement](placements) mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **locale** | <p>tùy chọn</p><p>mặc định: `en`</p> | <p>Định danh của bản dịch onboarding. Tham số này phải là mã ngôn ngữ gồm một hoặc hai subtag phân cách bằng dấu trừ (**-**). Subtag đầu tiên là ngôn ngữ, subtag thứ hai là vùng.</p><p></p><p>Ví dụ: `en` là tiếng Anh, `pt-br` là tiếng Bồ Đào Nha (Brazil).</p><p>Xem [Localizations and locale codes](localizations-and-locale-codes) để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **fetchPolicy** | mặc định: `.reloadRevalidatingCacheData` | <p>Theo mặc định, SDK sẽ cố tải dữ liệu từ server và trả về dữ liệu được cache trong trường hợp thất bại. Chúng tôi khuyến nghị tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.</p><p></p><p>Tuy nhiên, nếu bạn cho rằng người dùng của mình có kết nối internet không ổn định, hãy cân nhắc dùng `.returnCacheDataElseLoad` để trả về dữ liệu cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng họ sẽ có thời gian tải nhanh hơn dù kết nối mạng không ổn định. Cache được cập nhật thường xuyên, vì vậy có thể dùng nó trong phiên để tránh các request mạng.</p><p></p><p>Lưu ý rằng cache vẫn tồn tại khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt ứng dụng hoặc thông qua việc dọn dẹp thủ công.</p><p></p><p>Adapty SDK lưu trữ onboarding cục bộ trong hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và onboarding dự phòng. Chúng tôi cũng sử dụng CDN để tải onboarding nhanh hơn và một server dự phòng độc lập trong trường hợp CDN không truy cập được. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản onboarding mới nhất trong khi vẫn đảm bảo độ tin cậy ngay cả khi kết nối internet hạn chế.</p> |

---


# File: react-native-present-onboardings
---

---
title: "Hiển thị onboarding trong React Native SDK"
description: "Khám phá cách hiển thị onboarding trên React Native để tăng tỷ lệ chuyển đổi và doanh thu."
---

Nếu bạn đã tùy chỉnh onboarding bằng builder, bạn không cần lo lắng về việc render nó trong code ứng dụng di động để hiển thị cho người dùng. Onboarding đó chứa cả nội dung cần hiển thị lẫn cách hiển thị.

Trước khi bắt đầu, hãy đảm bảo rằng:

1. Bạn đã cài đặt [Adapty React Native SDK](sdk-installation-reactnative) phiên bản 3.8.0 trở lên.
2. Bạn đã [tạo một onboarding](create-onboarding).
3. Bạn đã thêm onboarding vào một [placement](placements).

Adapty React Native SDK cung cấp hai cách để hiển thị onboarding:
- **React component**: Embedded component cho phép bạn tích hợp vào kiến trúc và hệ thống điều hướng của ứng dụng.

- **Modal presentation**
## React component \{#react-component\}

Để nhúng một onboarding vào cây component hiện có của bạn, hãy sử dụng component `AdaptyOnboardingView` trực tiếp trong cấu trúc phân cấp component React Native. Component nhúng này cho phép bạn tích hợp nó vào kiến trúc và hệ thống điều hướng của ứng dụng.

:::note
Trên Android, chúng tôi khuyến nghị cấu hình bổ sung cho `AdaptyOnboardingView` để tránh hiện tượng lỗi hiển thị trực quan. Xem [Giao diện hệ thống chồng lên nội dung onboarding trên Android](#system-ui-overlaps-onboarding-content-on-android).
:::
<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK phiên bản 3.14 trở lên" default>
```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
  const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
  const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
  const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
  const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
  const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onAnalytics={onAnalytics}
      onClose={onClose}
      onCustom={onCustom}
      onPaywall={onPaywall}
      onStateUpdated={onStateUpdated}
      onFinishedLoading={onFinishedLoading}
      onError={onError}
    />
  );
}
```
</TabItem>
<TabItem value="old" label="Phiên bản SDK < 3.14" default>
```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={{ flex: 1 }}
      eventHandlers={{
        onAnalytics(event, meta) { 
          // Handle analytics events
        },
        onClose(actionId, meta) { 
          // Handle close actions
        },
        onCustom(actionId, meta) { 
          // Handle custom actions
        },
        onPaywall(actionId, meta) { 
          // Handle paywall actions
        },
        onStateUpdated(action, meta) { 
          // Handle state updates
        },
        onFinishedLoading(meta) { 
          // Handle when onboarding finishes loading
        },
        onError(error) { 
          // Handle errors
        },
      }}
    />
  );
}
```
</TabItem>
</Tabs>
## Hiển thị dạng modal \{#modal-presentation\}

Để hiển thị onboarding dưới dạng màn hình độc lập mà người dùng có thể đóng lại, sử dụng phương thức `view.present()` trên `view` được tạo bởi phương thức `createOnboardingView`. Mỗi `view` chỉ có thể được sử dụng một lần. Nếu bạn cần hiển thị lại onboarding, hãy gọi `createOnboardingView` thêm một lần nữa để tạo một `view` mới.

:::warning
Không được tái sử dụng cùng một `view` mà không tạo lại. Việc này sẽ dẫn đến lỗi `AdaptyUIError.viewAlreadyPresented`.
:::
<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>
```typescript showLineNumbers title="React Native (TSX)"

const view = await createOnboardingView(onboarding);

// Optional: handle onboarding events (close, custom actions, etc)
// view.setEventHandlers({ ... });

try {
    await view.present();
} catch (error) {
    // handle the error
}
```
</TabItem>
<TabItem value="old" label="SDK version < 3.14" default>
```typescript showLineNumbers title="React Native (TSX)"

const view = await createOnboardingView(onboarding);

view.registerEventHandlers(); // handle close press, etc

try {
    await view.present();
} catch (error) {
    // handle the error
}
```
</TabItem>
</Tabs>
### Cấu hình kiểu hiển thị trên iOS \{#configure-ios-presentation-style\}

Cấu hình cách paywall được hiển thị trên iOS bằng cách truyền tham số `iosPresentationStyle` vào phương thức `present()`. Tham số này chấp nhận các giá trị `'full_screen'` (mặc định) hoặc `'page_sheet'`.

```typescript showLineNumbers
try {
  await view.present({ iosPresentationStyle: 'page_sheet' });
} catch (error) {
  // handle the error
}
```

## Loader trong quá trình hiển thị onboarding \{#loader-during-onboarding\}

Khi hiển thị onboarding trong React Native, bạn có thể thấy một màn hình trắng hoặc màn hình loading ngắn xuất hiện trước khi onboarding hiện ra. Điều này xảy ra trong khi native view bên dưới đang được khởi tạo. Bạn có thể xử lý vấn đề này theo nhiều cách khác nhau tùy thuộc vào nhu cầu và quy trình làm việc của bạn.

#### Kiểm soát splash screen bằng onFinishedLoading \{#control-splash-screen-using-onfinishedloading\}

:::note
Cách này chỉ khả dụng khi sử dụng React component. Không áp dụng được cho modal presentation.
:::
Cách được khuyến nghị cho React Native là giữ màn hình chờ (splash screen) hoặc lớp phủ tùy chỉnh hiển thị cho đến khi onboarding tải xong hoàn toàn, sau đó ẩn nó đi theo cách thủ công.

Khi sử dụng React component (`AdaptyOnboardingView`), hãy chờ sự kiện `onFinishedLoading` trước khi ẩn splash screen hoặc lớp phủ:

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK phiên bản 3.14 trở lên" default>
```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const [isLoading, setIsLoading] = useState(true);

  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {
    // Hide your splash screen or custom overlay here
    setIsLoading(false);
  }, []);

  return (
    <>
      <AdaptyOnboardingView
        onboarding={onboarding}
        onFinishedLoading={onFinishedLoading}
        // ... other callbacks
      />
      {isLoading && <YourCustomLoadingOverlay />}
    </>
  );
}
```

</TabItem>

<TabItem value="old" label="Phiên bản SDK < 3.14">
```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <>
      <AdaptyOnboardingView
        onboarding={onboarding}
        eventHandlers={{
          onFinishedLoading(meta) {
            // Hide your splash screen or custom overlay here
            setIsLoading(false);
          },
          // ... other handlers
        }}
      />
      {isLoading && <YourCustomLoadingOverlay />}
    </>
  );
}
```

</TabItem>
</Tabs>

#### Tùy chỉnh native loader \{#customize-native-loader\}

:::important
Expo-managed workflow không hỗ trợ việc đặt các layout native tùy chỉnh (ví dụ: `res/layout` trên Android). Đối với ứng dụng Expo, cách duy nhất khả thi là kiểm soát splash screen hoặc sử dụng React Native overlay.
:::

Bạn có thể thay thế native loader bằng các layout theo từng nền tảng trên Android và iOS. Nếu bạn đang sử dụng modal presentation, đây là lựa chọn duy nhất của bạn.

Tuy nhiên, cách tiếp cận này thường kém tiện lợi hơn đối với ứng dụng React Native:

- Yêu cầu triển khai riêng biệt cho Android và iOS
- Không tương thích với Expo-managed workflow
Xác định placeholder cho từng nền tảng:

- **iOS**: Thêm `AdaptyOnboardingPlaceholderView.xib` vào dự án Xcode của bạn. [Tìm hiểu thêm](ios-present-onboardings#add-smooth-transitions-between-the-splash-screen-and-onboarding).
- **Android**: Tạo `adapty_onboarding_placeholder_view.xml` trong `res/layout` và định nghĩa placeholder tại đó. [Tìm hiểu thêm](android-present-onboardings#add-smooth-transitions-between-the-splash-screen-and-onboarding).
## Tùy chỉnh cách mở liên kết trong onboardings \{#customize-how-links-open-in-onboardings\}

:::important
Tính năng tùy chỉnh cách mở liên kết trong onboardings được hỗ trợ từ Adapty SDK v3.15.1 trở lên.
:::

Theo mặc định, các liên kết trong onboardings sẽ mở trong trình duyệt nội bộ của ứng dụng. Điều này mang lại trải nghiệm liền mạch cho người dùng bằng cách hiển thị các trang web ngay trong ứng dụng, giúp họ xem nội dung mà không cần rời khỏi app.

Nếu bạn muốn mở liên kết bằng trình duyệt bên ngoài, bạn có thể tùy chỉnh hành vi này bằng cách đặt tham số `externalUrlsPresentation` thành `WebPresentation.BrowserOutApp`:
<Tabs groupId="rn-onboarding-views" queryString>
<TabItem value="component" label="React component" default>
```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
  const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
  const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
  const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
  const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
  const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      externalUrlsPresentation={WebPresentation.BrowserOutApp} // default – BrowserInApp
      onAnalytics={onAnalytics}
      onClose={onClose}
      onCustom={onCustom}
      onPaywall={onPaywall}
      onStateUpdated={onStateUpdated}
      onFinishedLoading={onFinishedLoading}
      onError={onError}
    />
  );
}
```
</TabItem>
<TabItem value="modal" label="Modal presentation">

```typescript showLineNumbers title="React Native (TSX)"

const view = await createOnboardingView(
  onboarding, 
  { externalUrlsPresentation: WebPresentation.BrowserOutApp } // default – BrowserInApp
);

try {
    await view.present();
} catch (error) {
    // handle the error
}
```
</TabItem>
</Tabs>
## Xử lý sự cố \{#troubleshooting\}

### Giao diện hệ thống che khuất nội dung onboarding trên Android \{#system-ui-overlaps-onboarding-content-on-android\}

:::note
Cài đặt này chỉ được hỗ trợ trong các dự án React Native thuần (bare).

Nếu bạn đang dùng Expo managed workflow, bạn không thể thêm Android resource này trực tiếp. Để áp dụng cài đặt này, bạn cần tạo một custom Expo config plugin để thêm Android resource tương ứng và đăng ký nó trong `app.config.js`. Điều này là bắt buộc vì Expo quản lý native Android project cho bạn.
:::
Khi sử dụng `AdaptyOnboardingView` trên Android, các thành phần giao diện hệ thống như thanh trạng thái và thanh điều hướng có thể hiển thị đè lên nội dung paywall. Để tránh điều này, hãy thêm tài nguyên boolean sau vào ứng dụng của bạn:

1. Truy cập `android/app/src/main/res/values`. Nếu chưa có file `bools.xml`, hãy tạo mới.

2. Thêm tài nguyên sau:

```xml
<resources>
    <bool name="adapty_onboarding_enable_safe_area_paddings">false</bool>
</resources>
```

Lưu ý rằng thay đổi này áp dụng toàn cục cho tất cả các onboarding trong ứng dụng của bạn.
## Các bước tiếp theo \{#next-steps\}

Sau khi hiển thị onboarding, bạn sẽ muốn [xử lý các tương tác và sự kiện của người dùng](react-native-handling-onboarding-events). Tìm hiểu cách xử lý các sự kiện onboarding để phản hồi hành động của người dùng và theo dõi analytics.

---


# File: react-native-handling-onboarding-events
---

---
title: "Xử lý sự kiện onboarding trong React Native SDK"
description: "Xử lý các sự kiện liên quan đến onboarding trong React Native bằng Adapty."
---

Các onboarding được cấu hình bằng builder sẽ tạo ra các sự kiện mà ứng dụng của bạn có thể xử lý. Cách xử lý những sự kiện này phụ thuộc vào phương thức hiển thị bạn đang dùng:

- **Modal presentation**: Yêu cầu thiết lập các event handler để xử lý sự kiện cho tất cả onboarding view
- **React component**: Xử lý sự kiện thông qua các tham số callback trực tiếp trong widget

Trước khi bắt đầu, hãy đảm bảo rằng:

1. Bạn đã cài đặt [Adapty React Native SDK](sdk-installation-reactnative) phiên bản 3.8.0 trở lên.
2. Bạn đã [tạo một onboarding](create-onboarding).
3. Bạn đã thêm onboarding vào một [placement](placements).

Để kiểm soát hoặc theo dõi các tiến trình xảy ra trên màn hình onboarding trong ứng dụng di động của bạn, hãy triển khai các event handler:

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

Với React component, bạn xử lý sự kiện thông qua các prop event handler riêng lẻ trong component `AdaptyOnboardingView`:

```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
  const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
  const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
  const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
  const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
  const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onAnalytics={onAnalytics}
      onClose={onClose}
      onCustom={onCustom}
      onPaywall={onPaywall}
      onStateUpdated={onStateUpdated}
      onFinishedLoading={onFinishedLoading}
      onError={onError}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Với modal presentation, hãy triển khai phương thức event handler.

:::important
Gọi `setEventHandlers` nhiều lần sẽ ghi đè các handler bạn cung cấp, thay thế cả handler mặc định lẫn handler đã được thiết lập trước đó cho những sự kiện cụ thể đó.
:::

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.setEventHandlers({
  onAnalytics(event, meta) {
    // Track analytics events
  },
  onClose(actionId, meta) {
    // Handle close action
    view.dismiss();
    return true;
  },
  onCustom(actionId, meta) {
    // Handle custom actions
  },
  onPaywall(actionId, meta) {
    // Handle paywall actions
  },
  onStateUpdated(action, meta) {
    // Handle user input updates
  },
  onFinishedLoading(meta) {
    // Onboarding finished loading
  },
  onError(error) {
    // Handle loading errors
  },
});

try {
  await view.present();
} catch (error) {
  // handle the error
}
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14">

Với SDK phiên bản < 3.14, chỉ hỗ trợ modal presentation:

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.registerEventHandlers({
  onAnalytics(event, meta) {
    // Track analytics events
  },
  onClose(actionId, meta) {
    // Handle close action
    view.dismiss();
    return true;
  },
  onCustom(actionId, meta) {
    // Handle custom actions
  },
  onPaywall(actionId, meta) {
    // Handle paywall actions
  },
  onStateUpdated(action, meta) {
    // Handle user input updates
  },
  onFinishedLoading(meta) {
    // Onboarding finished loading
  },
  onError(error) {
    // Handle loading errors
  },
});

try {
  await view.present();
} catch (error) {
  // handle the error
}
```

</TabItem>
</Tabs>

## Các loại sự kiện \{#event-types\}

Các phần dưới đây mô tả các loại sự kiện khác nhau mà bạn có thể xử lý, bất kể phương thức hiển thị bạn đang dùng là gì.

### Xử lý hành động tùy chỉnh \{#handle-custom-actions\}

Trong builder, bạn có thể thêm hành động **custom** vào một nút và gán cho nó một ID.

  <img src="/assets/shared/img/ios-events-1.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

Sau đó, bạn có thể dùng ID này trong code và xử lý nó như một hành động tùy chỉnh. Ví dụ: nếu người dùng nhấn vào một nút tùy chỉnh như **Login** hay **Allow notifications**, event handler sẽ được kích hoạt với tham số `actionId` khớp với **Action ID** từ builder. Bạn có thể tạo ID riêng của mình, chẳng hạn như "allowNotifications".

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {
    switch (actionId) {
      case 'login':
        login();
        break;
      case 'allow_notifications':
        allowNotifications();
        break;
    }
  }, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onCustom={onCustom}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.setEventHandlers({
  onCustom(actionId, meta) {
    switch (actionId) {
      case 'login':
        login();
        break;
      case 'allow_notifications':
        allowNotifications();
        break;
    }
  },
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14">

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.registerEventHandlers({
  onCustom(actionId, meta) {
    switch (actionId) {
      case 'login':
        login();
        break;
      case 'allow_notifications':
        allowNotifications();
        break;
    }
  },
});
```

</TabItem>
</Tabs>

<Details>
<summary>Ví dụ sự kiện (Nhấp để mở rộng)</summary>

```json
{
  "actionId": "allow_notifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}
```
</Details>

### Hoàn tất tải onboarding \{#finishing-loading-onboarding\}

Khi onboarding hoàn tất việc tải, sự kiện này sẽ được kích hoạt:

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {
    console.log('Onboarding loaded:', meta.onboardingId);
  }, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onFinishedLoading={onFinishedLoading}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.setEventHandlers({
  onFinishedLoading(meta) {
    console.log('Onboarding loaded:', meta.onboardingId);
  },
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14">

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.registerEventHandlers({
  onFinishedLoading(meta) {
    console.log('Onboarding loaded:', meta.onboardingId);
  },
});
```

</TabItem>
</Tabs>

<Details>
<summary>Ví dụ sự kiện (Nhấp để mở rộng)</summary>

```json
{
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "welcome_screen",
        "screen_index": 0,
        "total_screens": 4
    }
}
```
</Details>

### Đóng onboarding \{#closing-onboarding\}

Onboarding được coi là đã đóng khi người dùng nhấn vào một nút có gán hành động **Close**.

  <img src="/assets/shared/img/ios-events-2.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

:::important
Lưu ý rằng bạn cần tự quản lý những gì xảy ra khi người dùng đóng onboarding. Ví dụ: bạn cần dừng hiển thị chính onboarding đó.
:::

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding, navigation }) {
  const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {
    navigation.goBack();  
  }, [navigation]);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onClose={onClose}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.setEventHandlers({
  onClose(actionId, meta) {
    await view.dismiss();
    return true;
  },
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14">

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.registerEventHandlers({
  onClose(actionId, meta) {
    await view.dismiss();
    return true;
  },
});
```

</TabItem>
</Tabs>

<Details>
<summary>Ví dụ sự kiện (Nhấp để mở rộng)</summary>

```json
{
  "action_id": "close_button",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
  }
}
```
</Details>

### Mở paywall \{#opening-a-paywall\}

:::tip
Xử lý sự kiện này để mở paywall nếu bạn muốn mở nó ngay bên trong onboarding. Nếu bạn muốn mở paywall sau khi onboarding đóng lại, có một cách đơn giản hơn – xử lý hành động đóng và mở paywall mà không cần dựa vào dữ liệu sự kiện.
:::

Cách làm liền mạch nhất khi làm việc với paywall trong onboarding là đặt action ID bằng với placement ID của paywall.

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {
    openPaywall(actionId);
  }, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onPaywall={onPaywall}
    />
  );
}

const openPaywall = async (placementId) => {
  // Implement your paywall opening logic here
};
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

Lưu ý rằng trên iOS, chỉ có thể hiển thị một view (paywall hoặc onboarding) trên màn hình tại một thời điểm. Nếu bạn hiển thị paywall chồng lên onboarding, bạn không thể điều khiển onboarding ở nền bằng code. Cố gắng dismiss onboarding sẽ đóng paywall thay vào đó, khiến onboarding vẫn hiển thị. Để tránh điều này, hãy luôn dismiss onboarding view trước khi hiển thị paywall.

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.setEventHandlers({
  onPaywall(actionId, meta) {
    view.dismiss().then(() => {
      openPaywall(actionId);
    });
  },
});

const openPaywall = async (placementId) => {
  // Implement your paywall opening logic here
};
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14">

Lưu ý rằng trên iOS, chỉ có thể hiển thị một view (paywall hoặc onboarding) trên màn hình tại một thời điểm. Nếu bạn hiển thị paywall chồng lên onboarding, bạn không thể điều khiển onboarding ở nền bằng code. Cố gắng dismiss onboarding sẽ đóng paywall thay vào đó, khiến onboarding vẫn hiển thị. Để tránh điều này, hãy luôn dismiss onboarding view trước khi hiển thị paywall.

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.registerEventHandlers({
  onPaywall(actionId, meta) {
    view.dismiss().then(() => {
      openPaywall(actionId);
    });
  },
});

const openPaywall = async (placementId) => {
  // Implement your paywall opening logic here
};
```

</TabItem>
</Tabs>

<Details>
<summary>Ví dụ sự kiện (Nhấp để mở rộng)</summary>

```json
{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}
```
</Details>

### Theo dõi điều hướng \{#tracking-navigation\}

Bạn nhận được sự kiện analytics khi các sự kiện liên quan đến điều hướng xảy ra trong flow onboarding:

<Tabs groupId="version" queryString>
<TabItem value="new" label="SDK version 3.14 or later" default>

<Tabs groupId="presentation-method" queryString>
<TabItem value="platform" label="React component" default>

```typescript showLineNumbers title="React Native (TSX)"

function MyOnboarding({ onboarding }) {
  const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {
    trackEvent(event.name, meta.onboardingId);
  }, []);

  return (
    <AdaptyOnboardingView
      onboarding={onboarding}
      style={styles.container}
      onAnalytics={onAnalytics}
    />
  );
}
```

</TabItem>
<TabItem value="standalone" label="Modal presentation">

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.setEventHandlers({
  onAnalytics(event, meta) {
    trackEvent(event.name, meta.onboardingId);
  },
});
```

</TabItem>
</Tabs>

</TabItem>

<TabItem value="old" label="SDK version < 3.14">

```javascript showLineNumbers title="React Native"

const view = await createOnboardingView(onboarding);

const unsubscribe = view.registerEventHandlers({
  onAnalytics(event, meta) {
    trackEvent(event.name, meta.onboardingId);
  },
});
```

</TabItem>
</Tabs>

Object `event` có thể là một trong các kiểu sau:

|Kiểu | Mô tả |
|------------|-------------|
| `onboardingStarted` | Khi onboarding đã được tải xong |
| `screenPresented` | Khi bất kỳ màn hình nào được hiển thị |
| `screenCompleted` | Khi một màn hình hoàn thành. Bao gồm `elementId` tùy chọn (định danh của phần tử đã hoàn thành) và `reply` tùy chọn (phản hồi từ người dùng). Được kích hoạt khi người dùng thực hiện bất kỳ hành động nào để thoát khỏi màn hình. |
| `secondScreenPresented` | Khi màn hình thứ hai được hiển thị |
| `userEmailCollected` | Được kích hoạt khi email của người dùng được thu thập qua trường nhập liệu |
| `onboardingCompleted` | Được kích hoạt khi người dùng đến màn hình có ID `final`. Nếu bạn cần sự kiện này, [hãy gán ID `final` cho màn hình cuối cùng](design-onboarding). |
| `unknown` | Dành cho bất kỳ loại sự kiện không được nhận diện. Bao gồm `name` (tên của sự kiện không xác định) và `meta` (metadata bổ sung) |

Mỗi sự kiện bao gồm thông tin `meta` chứa:

| Trường | Mô tả |
|------------|-------------|
| `onboardingId` | Định danh duy nhất của onboarding flow |
| `screenClientId` | Định danh của màn hình hiện tại |
| `screenIndex` | Vị trí của màn hình hiện tại trong flow |
| `screensTotal` | Tổng số màn hình trong flow |

<Details>
<summary>Ví dụ sự kiện (Nhấp để mở rộng)</summary>

```javascript
// onboardingStarted
{
  "name": "onboarding_started",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
  }
}

// screenPresented
{
    "name": "screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "interests_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

// screenCompleted
{
    "name": "screen_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    },
    "params": {
        "element_id": "profile_form",
        "reply": "success"
    }
}

// secondScreenPresented
{
    "name": "second_screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// userEmailCollected
{
    "name": "user_email_collected",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// onboardingCompleted
{
    "name": "onboarding_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "final_screen",
        "screen_index": 3,
        "total_screens": 4
    }
}
```
</Details>

---


# File: react-native-onboarding-input
---

---
title: "Xử lý dữ liệu từ onboarding trong React Native SDK"
description: "Lưu và sử dụng dữ liệu từ onboarding trong ứng dụng React Native của bạn với Adapty SDK."
---

Khi người dùng trả lời câu hỏi trong bài quiz hoặc nhập dữ liệu vào trường nhập liệu, phương thức `onStateUpdatedAction` sẽ được gọi. Bạn có thể lưu hoặc xử lý loại trường đó trong code của mình.

Ví dụ:
```javascript
// Full-screen presentation
const unsubscribe = view.setEventHandlers({
  onStateUpdated(action, meta) {
    // Process data 
  },
});

// Embedded widget
<AdaptyOnboardingView
  onboarding={onboarding}
  eventHandlers={{
    onStateUpdated(action, meta) {
      // Process data 
    },
  }}
/>
```

Xem định dạng action [tại đây](https://react-native.adapty.io/types/onboardingstateupdatedaction).

<Details>
<summary>Ví dụ về dữ liệu đã lưu (định dạng có thể khác nhau tùy theo cách triển khai của bạn)</summary>
```javascript
// Example of a saved select action
{
    "elementId": "preference_selector",
    "meta": {
        "onboardingId": "onboarding_123",
        "screenClientId": "preferences_screen",
        "screenIndex": 1,
        "screensTotal": 3
    },
    "params": {
        "type": "select",
        "value": {
            "id": "option_1",
            "value": "premium",
            "label": "Premium Plan"
        }
    }
}

// Example of a saved multi-select action
{
    "elementId": "interests_selector",
    "meta": {
        "onboardingId": "onboarding_123",
        "screenClientId": "interests_screen",
        "screenIndex": 2,
        "screensTotal": 3
    },
    "params": {
        "type": "multiSelect",
        "value": [
            {
                "id": "interest_1",
                "value": "sports",
                "label": "Sports"
            },
            {
                "id": "interest_2",
                "value": "music",
                "label": "Music"
            }
        ]
    }
}

// Example of a saved input action
{
    "elementId": "name_input",
    "meta": {
        "onboardingId": "onboarding_123",
        "screenClientId": "profile_screen",
        "screenIndex": 0,
        "screensTotal": 3
    },
    "params": {
        "type": "input",
        "value": {
            "type": "text",
            "value": "John Doe"
        }
    }
}

// Example of a saved date picker action
{
    "elementId": "birthday_picker",
    "meta": {
        "onboardingId": "onboarding_123",
        "screenClientId": "profile_screen",
        "screenIndex": 0,
        "screensTotal": 3
    },
"params": {
    "type": "datePicker",
    "value": {
        "day": 15,
        "month": 6,
        "year": 1990
        }
    }
}
```
</Details>
## Các trường hợp sử dụng \{#use-cases\}

### Làm phong phú hồ sơ người dùng với dữ liệu \{#enrich-user-profiles-with-data\}

Nếu bạn muốn liên kết ngay dữ liệu đầu vào với hồ sơ người dùng và tránh hỏi họ hai lần cùng một thông tin, bạn cần [cập nhật hồ sơ người dùng](react-native-setting-user-attributes) với dữ liệu đầu vào khi xử lý action.

Ví dụ, bạn yêu cầu người dùng nhập tên vào trường văn bản có ID là `name`, và bạn muốn đặt giá trị của trường này làm tên của người dùng. Ngoài ra, bạn yêu cầu họ nhập email vào trường `email`. Trong code của ứng dụng, nó có thể trông như thế này:
```javascript showLineNumbers
// Full-screen presentation
const unsubscribe = view.setEventHandlers({
  onStateUpdated(action, meta) {
    // Store user preferences or responses
    if (action.elementType === 'input') {
      const profileParams = {};
      
      // Map elementId to appropriate profile field
      switch (action.elementId) {
        case 'name':
          if (action.value.type === 'text') {
            profileParams.firstName = action.value.value;
          }
          break;
        case 'email':
          if (action.value.type === 'email') {
            profileParams.email = action.value.value;
          }
          break;
      }
      
      // Update profile if we have data to update
      if (Object.keys(profileParams).length > 0) {
        adapty.updateProfile(profileParams).catch(error => {
          // handle the error
        });
      }
    }
  },
});

// Embedded widget
<AdaptyOnboardingView
  onboarding={onboarding}
  eventHandlers={{
    onStateUpdated(action, meta) {
      // Store user preferences or responses
      if (action.elementType === 'input') {
        const profileParams = {};
        
        // Map elementId to appropriate profile field
        switch (action.elementId) {
          case 'name':
            if (action.value.type === 'text') {
              profileParams.firstName = action.value.value;
            }
            break;
          case 'email':
            if (action.value.type === 'email') {
              profileParams.email = action.value.value;
            }
            break;
        }
        
        // Update profile if we have data to update
        if (Object.keys(profileParams).length > 0) {
          adapty.updateProfile(profileParams).catch(error => {
            // handle the error
          });
        }
      }
    },
  }}
/>
```

### Tùy chỉnh paywall dựa trên câu trả lời \{#customize-paywalls-based-on-answers\}

Sử dụng quiz trong onboarding, bạn có thể tùy chỉnh các paywall hiển thị cho người dùng sau khi họ hoàn thành onboarding.

Ví dụ: bạn có thể hỏi người dùng về kinh nghiệm thể thao của họ và hiển thị các CTA cũng như sản phẩm khác nhau cho từng nhóm người dùng.

1. [Thêm quiz](onboarding-quizzes) trong trình xây dựng onboarding và gán ID có ý nghĩa cho các lựa chọn.

2. Xử lý các phản hồi quiz dựa trên ID của chúng và [đặt thuộc tính tùy chỉnh](react-native-setting-user-attributes) cho người dùng.
```javascript showLineNumbers
// Full-screen presentation
const unsubscribe = view.setEventHandlers({
  onStateUpdated(action, meta) {
    // Handle quiz responses and set custom attributes
    if (action.elementType === 'select') {
      const profileParams = {};
      
      // Map quiz responses to custom attributes
      switch (action.elementId) {
        case 'experience':
          // Set custom attribute 'experience' with the selected value (beginner, amateur, pro)
          profileParams.codableCustomAttributes = {
            experience: action.value.value
          };
          break;
      }
      
      // Update profile if we have data to update
      if (Object.keys(profileParams).length > 0) {
        adapty.updateProfile(profileParams).catch(error => {
          // handle the error
        });
      }
    }
  },
});

// Embedded widget
<AdaptyOnboardingView
  onboarding={onboarding}
  eventHandlers={{
    onStateUpdated(action, meta) {
      // Handle quiz responses and set custom attributes
      if (action.elementType === 'select') {
        const profileParams = {};
        
        // Map quiz responses to custom attributes
        switch (action.elementId) {
          case 'experience':
            // Set custom attribute 'experience' with the selected value (beginner, amateur, pro)
            profileParams.codableCustomAttributes = {
              experience: action.value.value
            };
            break;
        }
        
        // Update profile if we have data to update
        if (Object.keys(profileParams).length > 0) {
          adapty.updateProfile(profileParams).catch(error => {
            // handle the error
          });
        }
      }
    },
  }}
/>
```

3. [Tạo phân khúc](segments) cho từng giá trị thuộc tính tùy chỉnh.
4. Tạo một [placement](placements) và thêm [đối tượng](audience) cho từng phân khúc bạn đã tạo.
5. [Hiển thị paywall](react-native-paywalls) cho placement trong code ứng dụng của bạn. Nếu onboarding của bạn có nút mở paywall, hãy triển khai code paywall như một [phản hồi cho hành động của nút này](react-native-handling-onboarding-events#opening-a-paywall).

---


# File: react-native-sdk-call-order
---

---
title: "Thứ tự gọi trong React Native SDK"
description: "Tránh mất quyền truy cập premium, thiếu attribution, và lỗi #2002 không ổn định bằng cách gọi các phương thức Adapty SDK theo đúng thứ tự."
---

`adapty.activate()` phải hoàn thành trước khi bạn gọi bất kỳ phương thức nào khác của Adapty SDK. Cho đến khi nó resolve, SDK chưa có trạng thái. Bất kỳ lệnh gọi nào được thực hiện trước hoặc song song với `activate()` đều thất bại với lỗi [`#2002 notActivated`](react-native-handle-errors#custom-network-codes).

Nếu ứng dụng của bạn xác thực người dùng và bạn thu thập customer user ID sau khi khởi chạy, hãy gọi `adapty.identify()` tại thời điểm đó. Đừng gọi các phương thức liên quan đến hành động của người dùng cho đến khi `identify` resolve. Các lệnh gọi chạy đua với nó hoặc thất bại với lỗi [`#3006 profileWasChanged`](react-native-handle-errors#custom-network-codes), hoặc tác động lên hồ sơ người dùng ẩn danh được tạo lúc kích hoạt. Khi điều này xảy ra, attribution, MMP ID như `appsflyer_id`, và quyền sở hữu cài đặt không phải lúc nào cũng được chuyển sang hồ sơ người dùng đã xác định. Nếu ứng dụng của bạn không xác thực người dùng, hãy bỏ qua `identify` và tiếp tục làm việc với hồ sơ người dùng ẩn danh.

Các SDK MMP và analytics (AppsFlyer, Adjust, Branch, PostHog) tuân theo quy tắc tương tự. Hãy khởi tạo chúng trước và chờ callback UID của chúng trước khi gọi `adapty.activate`. Nếu không, MMP ID sẽ được gán vào hồ sơ người dùng ẩn danh tạm thời và không phải lúc nào cũng được chuyển sang hồ sơ người dùng đã xác định. Để biết thêm chi tiết về AppsFlyer, xem [AppsFlyer](appsflyer).

## Thứ tự đúng \{#the-correct-order\}

Quy trình của bạn phụ thuộc vào hai yếu tố: thời điểm bạn biết customer user ID, và liệu bạn có dùng MMP hoặc analytics SDK hay không.

- **Bước 2 và 5**: Bắt buộc cho mọi ứng dụng. Kích hoạt SDK, sau đó gọi các phương thức SDK.
- **Bước 1 và 3**: Chỉ bắt buộc nếu bạn tích hợp MMP hoặc analytics SDK (AppsFlyer, Adjust, Branch, PostHog).
- **Bước 4**: Chỉ bắt buộc nếu ứng dụng của bạn xác thực người dùng và thu thập customer user ID sau khi khởi chạy.

Nếu bạn có customer user ID ngay lúc khởi chạy ứng dụng, hãy truyền trực tiếp vào `activate()` (bước 2a). Cách này không bao giờ tạo hồ sơ người dùng ẩn danh, nên bước 4 là không cần thiết.

| Bước | Lệnh gọi                                                                                                      | Thời điểm                                                                              | Ghi chú                                                                                        |
|------|---------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| 1    | Khởi tạo MMP hoặc analytics SDK của bạn (AppsFlyer, Adjust, PostHog, Branch)                                  | Khởi chạy ứng dụng, đầu tiên                                                           | Chờ callback UID của MMP, ví dụ `getAppsFlyerUID`.                                             |
| 2a   | `adapty.activate('YOUR_PUBLIC_SDK_KEY', { customerUserId: 'YOUR_USER_ID' })`                                  | Khởi chạy ứng dụng, sau bước 1, nếu bạn có customer user ID                           | Khuyến nghị. Không bao giờ tạo hồ sơ người dùng ẩn danh.                                      |
| 2b   | `adapty.activate('YOUR_PUBLIC_SDK_KEY')` không có `customerUserId`                                            | Khởi chạy ứng dụng, sau bước 1, nếu bạn chưa có customer user ID (hoặc không bao giờ thu thập) | Adapty tạo hồ sơ người dùng ẩn danh.                                                  |
| 3    | `adapty.updateAttribution(data, source, networkUserId)` cho từng MMP                                          | Sau bước 2, trước bất kỳ lệnh gọi hành động người dùng nào                             | Bắt buộc để MMP ID được gán vào đúng hồ sơ người dùng.                                        |
| 4    | `await adapty.identify('YOUR_USER_ID')`                                                                       | Sau bước 3 (hoặc bước 2 nếu không có MMP), trước bước 5 — chỉ trên đường dẫn 2b với xác thực | Luôn dùng `await`. Các lệnh gọi đồng thời trong `identify` sẽ gây ra `#3006 profileWasChanged`. |
| 5    | `getPaywall`, `getPaywallProducts`, `restorePurchases`, `makePurchase`, `updateAttribution`, `updateProfile`  | Sau bước 4 nếu bạn gọi `identify`; ngược lại sau bước 3 (hoặc bước 2 nếu không có MMP) | Các lệnh gọi này cần một hồ sơ người dùng ổn định.                                            |

:::important
Bỏ qua các bước này gây ra mất quyền truy cập premium cho người dùng quay lại, thiếu `appsflyer_id` trên hồ sơ người dùng, và paywall được trả về sai đối tượng.
:::

## Cài đặt web2app và web-funnel \{#web2app-and-web-funnel-installs\}

Nếu người dùng mua hàng qua web checkout (Stripe, Paddle) và sau đó cài đặt ứng dụng native, lần `activate()` đầu tiên trên thiết bị sẽ tạo một hồ sơ người dùng ẩn danh mới. Hồ sơ người dùng này không được liên kết với hồ sơ người dùng web. Nếu bạn có thể xác định customer user ID trước khi khởi chạy ứng dụng (từ luồng xác thực hoặc install referrer), hãy truyền trực tiếp vào `activate()`. Nếu không, giao dịch mua trên web sẽ không hiển thị trên thiết bị cho đến khi bạn gọi `identify('YOUR_USER_ID')` và sau đó là `restorePurchases`.

Để biết metadata cần gửi kèm theo từng web checkout, xem:

- [Stripe](stripe)
- [Paddle](paddle)

---


# File: react-native-optimize-paywall-fetching
---

---
title: "Tối ưu hóa việc lấy paywall trong React Native SDK"
description: "Lấy paywall Adapty đáng tin cậy: thời điểm, bộ nhớ đệm và các mẫu dự phòng cho React Native."
---

Một lần lấy paywall đáng tin cậy trên React Native cần đảm bảo ba điều: hiển thị nhanh, trả về paywall đúng với đối tượng được nhắm mục tiêu, và có phương án dự phòng hợp lý khi mạng chậm. Các quy tắc dưới đây đề cập đến thời điểm, bộ nhớ đệm và các mẫu dự phòng để đạt được điều đó.

:::tip
Các quy tắc này giả định rằng `adapty.activate()` và `adapty.identify()` đã được resolve xong. Xem [Thứ tự gọi trong React Native SDK](react-native-sdk-call-order).
:::

## Quy tắc và những lỗi thường gặp \{#rules-and-pitfalls\}

| Nên làm | Không nên làm | Lý do |
|---|---|---|
| Lấy placement mà bạn sắp hiển thị.                                                                                  | Prefetch tất cả các placement cùng lúc khi khởi động.        | Bulk prefetch chặn JS thread và gây ra màn hình đen trong khoảng thời gian đó.                                  |
| Gọi `getPaywall` sau khi attribution đã có cơ hội resolve — ví dụ, 1–2 giây sau `activate` hoặc sau khi `onProfileUpdate` kích hoạt. | Gọi `getPaywall` tại component gốc khi mount. | Attribution chưa hoàn tất. Paywall sẽ resolve theo đối tượng mặc định và âm thầm bỏ qua các phân khúc và cá nhân hóa ASA. |
| Đặt `loadTimeoutMs` và cấu hình [paywall dự phòng](fallback-paywalls) cho mọi placement.                             | Chờ `getPaywall` vô thời hạn.                     | Nếu không có timeout, người dùng ở kết nối kém sẽ thấy màn hình trắng cho đến khi mạng phản hồi — hoặc họ sẽ tắt ứng dụng.     |

Xem [Lấy paywall và sản phẩm](fetch-paywalls-and-products-react-native) để tham khảo các tham số `fetchPolicy` và `loadTimeoutMs`, và [Placements](placements) để chọn placement phù hợp.

## Tối ưu cho kết nối kém \{#tune-for-poor-connectivity\}

Đối với các thị trường có kết nối kém liên tục (khu vực nông thôn, phương tiện giao thông, vùng bị ảnh hưởng bởi định tuyến mạng):

- Đặt `fetchPolicy: .returnCacheDataElseLoad` cho mọi lần lấy dữ liệu, trừ lần đầu tiên.
- Cấu hình [paywall dự phòng](fallback-paywalls) cho mọi placement trên Adapty Dashboard.
- Đặt `loadTimeoutMs` từ 3–5 giây và chấp nhận phương án dự phòng khi timeout xảy ra.
- Đừng chặn việc hiển thị paywall bằng `getProfile()`. Gọi `getPaywall` độc lập để tránh trường hợp profile chậm làm chặn giao diện.

---


# File: react-native-show-aa-targeted-paywall
---

---
title: "Hiển thị paywall nhắm mục tiêu AA ngay khi khởi chạy lần đầu trong React Native SDK"
description: "Hiển thị paywall ngay lập tức và cập nhật cho người dùng Apple Ads khi attribution được áp dụng trong React Native, sử dụng AdaptyProfile.appliedAttributionSources."
---

Attribution của Apple Ads (AA) được nhận không đồng bộ sau khi `adapty.activate()` được gọi. Ở lần khởi chạy đầu tiên, attribution thường chưa có, nên `getPaywall` sẽ giải quyết theo đối tượng mặc định và người dùng Apple Ads sẽ bỏ lỡ paywall được phân khúc theo AA của bạn. Thay vì chờ attribution đến mới hiển thị paywall, hãy hiển thị paywall ngay lập tức và làm mới khi attribution AA được áp dụng — để người dùng Apple Ads nhận được biến thể nhắm mục tiêu còn những người khác thấy paywall ngay không cần chờ. `AdaptyProfile.appliedAttributionSources` cho bạn biết khi nào attribution AA đã được áp dụng.

## Trước khi bắt đầu \{#before-you-start\}

Bạn cần:
- Adapty React Native SDK phiên bản **3.17.1** trở lên.
- Apple Ads đã được cấu hình cho ứng dụng trong Adapty. Xem [Apple Ads](apple-search-ads).

## Cách hoạt động \{#how-it-works\}

Sau khi `adapty.activate()` được gọi, SDK sẽ yêu cầu attribution Apple Ads từ Apple ở chế độ nền và chuyển kết quả đến backend của Adapty. Khi AA trở thành nguồn attribution đang hoạt động cho hồ sơ người dùng, SDK sẽ gửi một `AdaptyProfile` được cập nhật đến listener `onLatestProfileLoad` của bạn, với `'apple_search_ads'` trong mảng `appliedAttributionSources`.

Điều này cho phép bạn tải paywall theo hai bước:

1. Gọi `getPaywall` ngay lập tức. Khi chưa có attribution nào được áp dụng, Adapty sẽ giải quyết yêu cầu theo đối tượng mặc định, người dùng thấy paywall ngay.
2. Khi `'apple_search_ads'` xuất hiện, gọi lại `getPaywall`. Lúc này Adapty giải quyết yêu cầu theo đối tượng Apple Ads và trả về paywall nhắm mục tiêu, thay thế paywall đầu tiên.

`appliedAttributionSources` có thể rỗng hoặc không có giá trị. Điều đó có nghĩa là:

- Attribution Apple Ads chưa được xử lý cho hồ sơ người dùng này, hoặc
- Chưa có attribution nào đến.

Dù thế nào, bước 1 vẫn an toàn — Adapty giải quyết yêu cầu theo đối tượng phù hợp với trạng thái hồ sơ người dùng hiện tại, thường là đối tượng mặc định. Bước 2 chỉ chạy khi `'apple_search_ads'` xuất hiện.

:::important
Ở mỗi lần khởi chạy tiếp theo, hồ sơ người dùng đã được cache sẵn với `'apple_search_ads'` trong `appliedAttributionSources`, nên lần `getPaywall` đầu tiên đã trả về paywall được phân khúc theo Apple Ads — không có lần tải thứ hai hay thay đổi nào hiển thị. Luồng hai bước chỉ quan trọng ở lần khởi chạy đầu tiên, khi attribution vẫn đang trong quá trình xử lý.
:::

## Triển khai \{#implementation\}

Hiển thị paywall ngay lập tức, sau đó lắng nghe `'apple_search_ads'` và làm mới paywall khi nó xuất hiện.

1. **Kích hoạt SDK.** Xem [Cài đặt & cấu hình React Native SDK](sdk-installation-reactnative).
2. **Tải và hiển thị paywall** bằng `getPaywall` như bình thường — không chặn chờ attribution.
3. **Đăng ký nhận cập nhật hồ sơ người dùng** bằng `adapty.addEventListener('onLatestProfileLoad', …)` và theo dõi `'apple_search_ads'`. Khi nó xuất hiện, tải lại paywall và hiển thị paywall mới. Nếu bạn chưa thiết lập listener, xem [Lắng nghe cập nhật gói đăng ký](react-native-check-subscription-status#listen-to-subscription-updates):

```typescript
const subscription = adapty.addEventListener('onLatestProfileLoad', async profile => {
  if (!profile.appliedAttributionSources?.includes('apple_search_ads')) return;
  const targeted = await adapty.getPaywall(placementId);
  // present the targeted paywall in place of the first one
});

// Call subscription.remove() after the upgrade, or after a timeout (see below).
```

4. **Dừng lắng nghe sau một khoảng thời gian.** Hầu hết người dùng không bao giờ nhận được attribution Apple Ads, vì vậy hãy xóa listener sau một khoảng thời gian thay vì giữ nó mở suốt phiên. Cấu hình [paywall dự phòng](react-native-use-fallback-paywalls) cho placement để người dùng luôn thấy gì đó nếu yêu cầu thất bại.

## Ví dụ hoàn chỉnh \{#complete-example\}

`onAppleAdsAttribution` sẽ resolve khi attribution Apple Ads được áp dụng, hoặc reject sau `timeoutMs`. Đoạn code bên dưới tải paywall ngay lập tức, sau đó tải lại khi attribution đến — người dùng Apple Ads nhận được paywall nhắm mục tiêu, và nếu attribution không bao giờ đến thì paywall đầu tiên vẫn được giữ nguyên:

```typescript

const APPLE_ADS_SOURCE = 'apple_search_ads';
const placementId = 'YOUR_PLACEMENT_ID';

function hasAppleAdsAttribution(profile: AdaptyProfile): boolean {
  return profile.appliedAttributionSources?.includes(APPLE_ADS_SOURCE) ?? false;
}

/**
 * Resolves once Apple Ads attribution is applied to the profile.
 * Rejects with a timeout error if attribution never arrives within `timeoutMs`.
 * Call after `adapty.activate()`.
 */
export function onAppleAdsAttribution(timeoutMs: number): Promise<void> {
  return new Promise((resolve, reject) => {
    let timer: ReturnType<typeof setTimeout> | undefined;
    let subscription: { remove: () => void } | undefined;

    const stop = () => {
      clearTimeout(timer);
      subscription?.remove();
    };

    subscription = adapty.addEventListener('onLatestProfileLoad', profile => {
      if (!hasAppleAdsAttribution(profile)) return;
      stop();
      resolve();
    });

    timer = setTimeout(() => {
      stop();
      reject(new Error(`Apple Ads attribution timed out after ${timeoutMs}ms`));
    }, timeoutMs);
  });
}

let paywall = await adapty.getPaywall(placementId);

onAppleAdsAttribution(30_000)
  .then(() => adapty.getPaywall(placementId))
  .then(updated => {
    paywall = updated;
  })
  .catch(() => {
    console.log('Apple Ads attribution or loading failed');
  });
```

Ở lần khởi chạy đầu tiên, người dùng Apple Ads sẽ thấy paywall mặc định trong một khoảnh khắc trước khi nó được thay thế. Nếu bạn hiển thị paywall bằng Paywall Builder, hãy cân nhắc xem việc hiển thị lại có phù hợp không, hoặc chỉ áp dụng bản cập nhật trước khi paywall được hiển thị. Điều chỉnh `timeoutMs` tùy theo thời gian bạn sẵn sàng lắng nghe — attribution khi đến thường xuất hiện trong vài giây sau khi khởi chạy.

Nếu ứng dụng của bạn đã lắng nghe `onLatestProfileLoad` cho các mục đích khác (ví dụ, [kiểm tra trạng thái gói đăng ký](react-native-check-subscription-status#listen-to-subscription-updates)), bạn không cần thay đổi gì. `adapty.addEventListener` hỗ trợ nhiều listener độc lập, nên listener này sẽ được thêm vào mà không ảnh hưởng đến các listener khác.

---


# File: react-native-test
---

---
title: "Test & release in React Native SDK"
description: "Learn how to test and release your React Native app with Adapty SDK."
---

Nếu bạn đã tích hợp Adapty SDK vào ứng dụng React Native của mình, bạn sẽ muốn kiểm tra xem mọi thứ đã được thiết lập đúng chưa và các giao dịch mua có hoạt động như mong đợi trên cả hai nền tảng iOS và Android không. Quá trình này bao gồm kiểm thử cả tích hợp SDK lẫn luồng mua hàng thực tế với môi trường sandbox của Apple và môi trường kiểm thử của Google Play.

## Kiểm thử ứng dụng \{#test-your-app\}

Để kiểm thử in-app purchase một cách toàn diện, hãy xem các hướng dẫn kiểm thử theo nền tảng: [Hướng dẫn kiểm thử iOS](test-purchases-in-sandbox) và [Hướng dẫn kiểm thử Android](testing-on-android).

## Chuẩn bị phát hành \{#prepare-for-release\}

Trước khi gửi ứng dụng lên cửa hàng, hãy làm theo [Danh sách kiểm tra phát hành](release-checklist) để xác nhận:

- Kết nối với cửa hàng và thông báo máy chủ đã được cấu hình
- Giao dịch mua hoàn tất và được báo cáo về Adapty
- Quyền truy cập được mở khóa và khôi phục đúng cách
- Các yêu cầu về quyền riêng tư và kiểm duyệt đã được đáp ứng

---


# File: InvalidProductIdentifiers-react-native
---

---
title: "Sửa lỗi Code-1000 noProductIDsFound trong React Native SDK"
description: "Khắc phục lỗi mã sản phẩm không hợp lệ khi quản lý gói đăng ký trong Adapty."
---

Lỗi mã 1000, `noProductIDsFound`, cho biết không có sản phẩm nào bạn yêu cầu trên paywall khả dụng để mua trong App Store, dù chúng đã được liệt kê ở đó. Lỗi này đôi khi đi kèm cảnh báo `InvalidProductIdentifiers`. Nếu cảnh báo xuất hiện mà không có lỗi, bạn có thể bỏ qua an toàn.

Nếu bạn gặp lỗi `noProductIDsFound`, hãy làm theo các bước sau để khắc phục:

## Bước 1. Kiểm tra bundle ID \{#step-2-check-bundle-id\}

---
no_index: true 
---

1. Mở [App Store Connect](https://appstoreconnect.apple.com/apps). Chọn ứng dụng của bạn và điều hướng đến phần **General** → **App Information**.

2. Sao chép **Bundle ID** trong mục **General Information**.

   

<Zoom>
  <img src="/docs/img/afd5012-bundle_id_apple.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>
</Zoom>

3. Mở tab [**App settings** -> **iOS SDK**](https://app.adapty.io/settings/ios-sdk) từ menu trên cùng của Adapty và dán giá trị vừa sao chép vào trường **Bundle ID**.

   

<Zoom>
  <img src="/docs/img/2d64163-bundle_id.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>
</Zoom>

4. Quay lại trang **App information** trong App Store Connect và sao chép **Apple ID** tại đó.
5. Trên trang [**App settings** -> **iOS SDK**](https://app.adapty.io/settings/ios-sdk) trong Adapty dashboard, dán ID vào trường **Apple app ID**.

## Bước 2. Kiểm tra sản phẩm \{#step-3-check-products\}

1. Vào **App Store Connect** và điều hướng đến [**Monetization** → **Subscriptions**](https://appstoreconnect.apple.com/apps/6477523342/distribution/subscriptions) trong menu bên trái.

 <img src="/assets/shared/img/subscription_group_open.webp"
 style={{
   border: '1px solid #727272', /* border width and color */
   width: '700px', /* image width */
   display: 'block', /* for alignment */
   margin: '0 auto' /* center alignment */
 }}
  />

2. Nhấp vào tên nhóm gói đăng ký. Bạn sẽ thấy các sản phẩm được liệt kê trong mục **Subscriptions**.

3. Đảm bảo sản phẩm bạn đang kiểm tra được đánh dấu là **Ready to Submit**.
    
   <img src="/assets/shared/img/ready-to-submit.webp"
      style={{
        border: '1px solid #727272', /* border width and color */
        width: '700px', /* image width */
        display: 'block', /* for alignment */
        margin: '0 auto' /* center alignment */
      }}
    />
    

4. So sánh ID sản phẩm trong bảng với ID trong tab [**Products**](https://app.adapty.io/products) trên Adapty Dashboard. Nếu các ID không khớp, hãy sao chép ID sản phẩm từ bảng và [tạo một sản phẩm](create-product) với ID đó trong Adapty Dashboard.

  

 <img src="/assets/shared/img/product-id-copy.webp"
 style={{
   border: '1px solid #727272', /* border width and color */
   width: '700px', /* image width */
   display: 'block', /* for alignment */
   margin: '0 auto' /* center alignment */
 }}
/>

## Bước 3. Kiểm tra tình trạng khả dụng của sản phẩm \{#step-4-check-product-availability\}

1. Quay lại **App Store Connect** và mở mục **Subscriptions** tương tự.

 
   <img src="/assets/shared/img/subscription_group_open.webp"
   style={{
     border: '1px solid #727272', /* border width and color */
     width: '700px', /* image width */
     display: 'block', /* for alignment */
     margin: '0 auto' /* center alignment */
   }}
    />
 

2. Nhấp vào tên nhóm gói đăng ký để xem các sản phẩm.

3. Chọn sản phẩm bạn đang kiểm tra.
   
   <img src="/assets/shared/img/click-product.webp"
    style={{
      border: '1px solid #727272', /* border width and color */
      width: '700px', /* image width */
      display: 'block', /* for alignment */
      margin: '0 auto' /* center alignment */
    }}
     />
     

4. Cuộn xuống mục **Availability** và kiểm tra rằng tất cả các quốc gia và khu vực cần thiết đều được liệt kê.

   
   <img src="/assets/shared/img/product-availability.webp"
    style={{
      border: '1px solid #727272', /* border width and color */
      width: '700px', /* image width */
      display: 'block', /* for alignment */
      margin: '0 auto' /* center alignment */
    }}
     />
     

## Bước 4. Kiểm tra giá sản phẩm \{#step-5-check-product-prices\}

1. Truy cập lại mục **Monetization** → **Subscriptions** trong **App Store Connect**.

 
   <img src="/assets/shared/img/subscription_group_open.webp"
   style={{
     border: '1px solid #727272', /* border width and color */
     width: '700px', /* image width */
     display: 'block', /* for alignment */
     margin: '0 auto' /* center alignment */
   }}
    />
 

2. Nhấp vào tên nhóm gói đăng ký.

3. Chọn sản phẩm bạn đang kiểm tra.
    
    <img src="/assets/shared/img/click-product.webp"
    style={{
      border: '1px solid #727272', /* border width and color */
      width: '700px', /* image width */
      display: 'block', /* for alignment */
      margin: '0 auto' /* center alignment */
    }}
    />
    

4. Cuộn xuống **Subscription Pricing** và mở rộng mục **Current Pricing for New Subscribers**.
    
    <img src="/assets/shared/img/check-prices.webp"
    style={{
      border: '1px solid #727272', /* border width and color */
      width: '700px', /* image width */
      display: 'block', /* for alignment */
      margin: '0 auto' /* center alignment */
    }}
    />
    

5. Đảm bảo rằng tất cả các mức giá cần thiết đều được liệt kê.
    
    <img src="/assets/shared/img/product-pricing.webp"
    style={{
      border: '1px solid #727272', /* border width and color */
      width: '700px', /* image width */
      display: 'block', /* for alignment */
      margin: '0 auto' /* center alignment */
    }}
    />
    

    

## Bước 5. Kiểm tra trạng thái thanh toán ứng dụng, tài khoản ngân hàng và biểu mẫu thuế còn hiệu lực \{#step-5-check-app-paid-status-bank-account-and-tax-forms-are-active\}

1. Trên trang chủ [**App Store Connect**](https://appstoreconnect.apple.com/), nhấp vào **Business**.

    
        <img src="/assets/shared/img/business.webp"
    style={{
        border: '1px solid #727272', /* border width and color */
        width: '700px', /* image width */
        display: 'block', /* for alignment */
        margin: '0 auto' /* center alignment */
    }}
    />
    

2. Chọn tên công ty của bạn.

    
        <img src="/assets/shared/img/business-name.webp"
    style={{
        border: '1px solid #727272', /* border width and color */
        width: '700px', /* image width */
        display: 'block', /* for alignment */
        margin: '0 auto' /* center alignment */
    }}
    />
    

3. Cuộn xuống và kiểm tra rằng **Paid Apps Agreement**, **Bank Account** và **Tax forms** đều hiển thị trạng thái **Active**.

    
        <img src="/assets/shared/img/appstore-connect-status.webp"
    style={{
        border: '1px solid #727272', /* border width and color */
        width: '700px', /* image width */
        display: 'block', /* for alignment */
        margin: '0 auto' /* center alignment */
    }}
    />
    

Bằng cách làm theo các bước trên, bạn sẽ có thể khắc phục cảnh báo `InvalidProductIdentifiers` và đưa sản phẩm của mình lên cửa hàng.

## Bước 6. Tạo lại sản phẩm nếu bị kẹt \{#step-6-recreate-the-product-if-its-stuck\}

Các bước 1–5 có thể đều vượt qua — trạng thái `Approved`, Bundle ID khớp, API key hợp lệ — nhưng SDK vẫn trả về `1000 noProductIDsFound`. Trong trường hợp đó, sản phẩm có thể đang bị kẹt trong registry của Apple. Registry sản phẩm của Apple đôi khi rơi vào trạng thái mà sản phẩm tồn tại trong giao diện App Store Connect nhưng không được hiển thị qua đường tra cứu StoreKit.

Hãy xóa sản phẩm trong App Store Connect và tạo lại với cùng ID sản phẩm đó. Chờ tối đa 24 giờ sau khi tạo lại để thay đổi được phổ biến.

---


# File: cantMakePayments-react-native
---

---
title: "Sửa lỗi Code-1003 cantMakePayment trong React Native SDK"
description: "Giải quyết lỗi thực hiện thanh toán khi quản lý gói đăng ký trong Adapty."
---

Lỗi 1003, `cantMakePayments`, cho biết thiết bị không thể thực hiện in-app purchase.

Nếu bạn gặp lỗi `cantMakePayments`, thường là do một trong các nguyên nhân sau:

- Giới hạn thiết bị: Lỗi này không liên quan đến Adapty. Xem cách khắc phục bên dưới.
- Cấu hình Observer mode: Không thể dùng đồng thời phương thức `makePurchase` và Observer mode. Xem phần bên dưới.

## Sự cố: Giới hạn thiết bị \{#issue-device-restrictions\}

| Sự cố                         | Giải pháp                                                                                                                   |
|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| Giới hạn Screen Time          | Tắt giới hạn In-App Purchase trong [Screen Time](https://support.apple.com/en-us/102470)                                   |
| Tài khoản bị tạm khóa         | Liên hệ Apple Support để giải quyết vấn đề tài khoản                                                                       |
| Giới hạn khu vực              | Sử dụng tài khoản App Store từ vùng được hỗ trợ                                                                             |

## Sự cố: Dùng đồng thời Observer mode và makePurchase \{#issue-using-both-observer-mode-and-makepurchase\}

Nếu bạn đang dùng `makePurchases` để xử lý giao dịch mua, bạn không cần dùng Observer mode. [Observer mode](observer-vs-full-mode) chỉ cần thiết khi bạn tự triển khai logic mua hàng.

Vì vậy, nếu bạn đang dùng `makePurchase`, bạn có thể xóa phần kích hoạt Observer mode khỏi code khởi tạo SDK một cách an toàn.

---


# File: migration-react-native-314
---

---
title: "Migrate Adapty React Native SDK to v3.14"
description: "Migrate to Adapty React Native SDK v3.14 for better performance and new monetization features."
---

Adapty React Native SDK 3.14.0 là một bản phát hành lớn với các cải tiến yêu cầu bạn thực hiện các bước migration:

- Phương thức `registerEventHandlers` đã được thay thế bằng phương thức `setEventHandlers`.
- Trong `AdaptyOnboardingView`, các event handler giờ được truyền dưới dạng các prop riêng lẻ thay vì một object `eventHandlers`
- Một kiểu import mới, đơn giản hơn đã được giới thiệu cho các UI component
- Phương thức `logShowOnboarding` đã bị xóa
- Phiên bản React Native tối thiểu đã được cập nhật lên 0.73.0
- Style trình bày iOS mặc định cho paywall và onboarding đã thay đổi từ page sheet sang full screen

## Thay thế `registerEventHandlers` bằng `setEventHandlers` \{#replace-registereventhandlers-with-seteventhandlers\}

Phương thức `registerEventHandlers` dùng để làm việc với Adapty Paywall và Onboarding Builder đã được thay thế bằng phương thức `setEventHandlers`.
Nếu bạn đang dùng Adapty Paywall Builder và/hoặc Adapty Onboarding Builder, hãy tìm `registerEventHandlers` trong code của bạn và thay thế bằng `setEventHandlers`.

Thay đổi này được thực hiện để làm rõ hơn hành vi của phương thức: Các handler giờ hoạt động lần lượt vì mỗi handler trả về `true`/`false`, và việc có nhiều handler cho một sự kiện khiến hành vi kết quả không rõ ràng.

Lưu ý rằng khi sử dụng các React component như `AdaptyOnboardingView` hoặc `AdaptyPaywallView`, bạn không cần trả về `true`/`false` từ các event handler vì bạn kiểm soát khả năng hiển thị của component thông qua state management của riêng mình. Giá trị trả về chỉ cần thiết khi trình bày màn hình modal, nơi SDK quản lý vòng đời của view.

:::important
Gọi `setEventHandlers` nhiều lần sẽ ghi đè các handler bạn cung cấp, thay thế cả handler mặc định lẫn các handler đã được đặt trước đó cho những sự kiện cụ thể đó.
:::

```diff showLineNumbers 
- const unsubscribe = view.registerEventHandlers({
-    // your event handlers
- })

 const unsubscribe = view.setEventHandlers({
    // your event handlers
 })
``` 

## Cập nhật đường dẫn import cho UI component \{#update-import-paths-for-ui-components\}

Adapty SDK 3.14.0 giới thiệu kiểu import đơn giản hơn cho các UI component. Thay vì import từ `react-native-adapty/dist/ui`, giờ bạn có thể import trực tiếp từ `react-native-adapty`.

Kiểu import mới nhất quán hơn với các thông lệ React Native tiêu chuẩn và giúp các câu lệnh import gọn gàng hơn. Nếu bạn đang sử dụng các UI component như `AdaptyPaywallView` hoặc `AdaptyOnboardingView`, hãy cập nhật các import như bên dưới:

```diff showLineNumbers
- import { AdaptyPaywallView } from 'react-native-adapty/dist/ui';
+ import { AdaptyPaywallView } from 'react-native-adapty';

- import { AdaptyOnboardingView } from 'react-native-adapty/dist/ui';
+ import { AdaptyOnboardingView } from 'react-native-adapty';

- import { createPaywallView } from 'react-native-adapty/dist/ui';
+ import { createPaywallView } from 'react-native-adapty';

- import { createOnboardingView } from 'react-native-adapty/dist/ui';
+ import { createOnboardingView } from 'react-native-adapty';
```

:::note
Để tương thích ngược, kiểu import cũ (`react-native-adapty/dist/ui`) vẫn được hỗ trợ. Tuy nhiên, chúng tôi khuyến nghị sử dụng kiểu import mới để đảm bảo tính nhất quán và rõ ràng.
:::

## Cập nhật event handler của onboarding trong React component \{#update-onboarding-event-handlers-in-the-react-component\}

Các event handler cho onboarding đã được chuyển ra khỏi object `eventHandlers` trong `AdaptyOnboardingView`. Nếu bạn đang hiển thị onboarding bằng `AdaptyOnboardingView`, hãy cập nhật cấu trúc xử lý sự kiện.

:::important
Lưu ý cách chúng tôi khuyến nghị triển khai các event handler. Để tránh tạo lại object mỗi lần render, hãy sử dụng `useCallback` cho các hàm xử lý sự kiện.
:::

```diff showLineNumbers
 import React, { useCallback } from 'react';
- import { AdaptyOnboardingView } from 'react-native-adapty/dist/ui';
+ import { AdaptyOnboardingView } from 'react-native-adapty';
+ import type { OnboardingEventHandlers } from 'react-native-adapty';
+
+ function MyOnboarding({ onboarding }) {
+   const onAnalytics = useCallback<OnboardingEventHandlers['onAnalytics']>((event, meta) => {}, []);
+   const onClose = useCallback<OnboardingEventHandlers['onClose']>((actionId, meta) => {}, []);
+   const onCustom = useCallback<OnboardingEventHandlers['onCustom']>((actionId, meta) => {}, []);
+   const onPaywall = useCallback<OnboardingEventHandlers['onPaywall']>((actionId, meta) => {}, []);
+   const onStateUpdated = useCallback<OnboardingEventHandlers['onStateUpdated']>((action, meta) => {}, []);
+   const onFinishedLoading = useCallback<OnboardingEventHandlers['onFinishedLoading']>((meta) => {}, []);
+   const onError = useCallback<OnboardingEventHandlers['onError']>((error) => {}, []);
+
   return (
     <AdaptyOnboardingView
       onboarding={onboarding}
       style={styles.container}
-       eventHandlers={{
-         onAnalytics(event, meta) { /* ... */ },
-         onClose(actionId, meta) { /* ... */ },
-         onCustom(actionId, meta) { /* ... */ },
-         onPaywall(actionId, meta) { /* ... */ },
-         onStateUpdated(action, meta) { /* ... */ },
-         onFinishedLoading(meta) { /* ... */ },
-         onError(error) { /* ... */ },
-       }}
+       onAnalytics={onAnalytics}
+       onClose={onClose}
+       onCustom={onCustom}
+       onPaywall={onPaywall}
+       onStateUpdated={onStateUpdated}
+       onFinishedLoading={onFinishedLoading}
+       onError={onError}
     />
   );
+ }
```

:::note
Để tương thích ngược, prop `eventHandlers` vẫn được hỗ trợ nhưng đã bị deprecated. Chúng tôi khuyến nghị migrate sang các prop event handler riêng lẻ như minh họa ở trên.
:::

## Xóa `logShowOnboarding` \{#delete-logshowonboarding\}

Trong Adapty SDK 3.14.0, chúng tôi đã xóa phương thức `logShowOnboarding` khỏi SDK.
Nếu bạn đã sử dụng phương thức này, nó sẽ không còn khả dụng khi bạn nâng cấp SDK lên phiên bản 3.14 trở lên.

Thay vào đó, bạn có thể [tạo onboarding trong Adapty no-code onboarding builder](onboardings). Analytics cho các onboarding này được theo dõi tự động và bạn có nhiều tùy chọn tùy chỉnh.

## Cập nhật React Native \{#update-react-native\}

Kể từ Adapty SDK 3.14.0, phiên bản React Native tối thiểu được hỗ trợ là 0.73.0. Nếu bạn đang dùng phiên bản cũ hơn, hãy cập nhật React Native lên phiên bản 0.73.0 trở lên để trải nghiệm với Adapty SDK được nhất quán và ổn định.

## Cập nhật iOS presentation style cho paywall và onboarding modal \{#update-ios-presentation-style-for-modal-paywalls-and-onboardings\}

Trong Adapty SDK 3.14.0, style trình bày iOS mặc định cho paywall và onboarding hiển thị bằng phương thức `view.present()` đã thay đổi từ page sheet sang full screen.

Nếu bạn muốn giữ style page sheet như trước, hãy truyền tham số `iosPresentationStyle` vào phương thức `present()`:

```typescript showLineNumbers title="React Native (TSX)"
try {
  await view.present({ iosPresentationStyle: 'page_sheet' });
} catch (error) {
  // handle the error
}
```

---


# File: react-native-migration-guide-380
---

---
title: "Migrate Adapty React Native SDK to v3.8"
description: "Migrate sang Adapty React Native SDK v3.8 để cải thiện hiệu năng và sử dụng các tính năng kiếm tiền mới."
---

Adapty SDK 3.8.0 là một bản phát hành lớn mang lại một số cải tiến, tuy nhiên có thể yêu cầu bạn thực hiện một số bước migration.

## Cập nhật kiểu đầu vào để lấy tham số placement \{#update-input-type-for-getting-placement-params\}

`GetPaywallParamsInput` đã được đổi tên thành `GetPlacementParamsInput`:

```diff showLineNumbers
- type GetPaywallParamsInput = {
+ type GetPlacementParamsInput = {
   placementId: string;
   locale?: string;
   fetchPolicy?: AdaptyPlacementFetchPolicy;
   loadTimeoutMs?: number;
 }
```

## Cập nhật phương thức fallback \{#update-fallback-method\}

Phương thức để thiết lập paywall dự phòng đã được cập nhật, và kiểu dùng để chỉ định vị trí fallback cũng đã được đổi tên:

```diff showLineNumbers
- adapty.setFallbackPaywalls(paywallsLocation: Input.FallbackPaywallsLocation);
+ adapty.setFallback(fileLocation: Input.FileLocation);
```

## Cập nhật cách truy cập thuộc tính paywall \{#update-paywall-property-access\}

Các thuộc tính sau đã được chuyển từ `AdaptyPaywall` sang `AdaptyPlacement`:

```diff showLineNumbers
- paywall.abTestName
- paywall.audienceName
- paywall.revision
- paywall.placementId
+ paywall.placement.abTestName
+ paywall.placement.audienceName
+ paywall.placement.revision
+ paywall.placement.id
```

---


# File: migration-to-react-native-sdk-34
---

---
title: "Migrate Adapty React Native SDK to v3.4"
description: "Migrate sang Adapty React Native SDK v3.4 để có hiệu suất tốt hơn và các tính năng kiếm tiền mới."
---

Adapty SDK 3.4.0 là bản phát hành lớn với các cải tiến yêu cầu bạn thực hiện một số bước migration.

## Cập nhật file paywall dự phòng \{#update-fallback-paywall-files\}

Cập nhật các file paywall dự phòng để đảm bảo tương thích với phiên bản SDK mới:

1. [Tải xuống các file paywall dự phòng đã cập nhật](fallback-paywalls) từ Adapty Dashboard.
2. [Thay thế các paywall dự phòng hiện có trong ứng dụng mobile](react-native-use-fallback-paywalls) bằng các file mới.

## Cập nhật triển khai Observer Mode \{#update-implementation-of-observer-mode\}

Nếu bạn đang sử dụng Observer Mode, hãy đảm bảo cập nhật cách triển khai của nó.

Trước đây, các phương thức khác nhau được dùng để báo cáo giao dịch cho Adapty. Trong phiên bản mới, phương thức `reportTransaction` nên được sử dụng thống nhất trên cả Android lẫn iOS. Phương thức này báo cáo rõ ràng từng giao dịch cho Adapty, đảm bảo giao dịch được nhận diện. Nếu có sử dụng paywall, hãy truyền variation ID để liên kết giao dịch với paywall đó.

:::warning

**Đừng bỏ qua bước báo cáo giao dịch!**
Nếu bạn không gọi `reportTransaction`, Adapty sẽ không nhận diện giao dịch, giao dịch sẽ không xuất hiện trong analytics và sẽ không được gửi đến các integration.

:::

```diff showLineNumbers 
- if (Platform.OS === 'android') {
-     try {
-         await adapty.restorePurchases();
-     } catch (error) {
-         // handle the error
-     }
- }

  const variationId = paywall.variationId;

  try {
      await adapty.reportTransaction(transactionId, variationId);
  } catch (error) {
      // handle the `AdaptyError`
  }
```

---


# File: migration-to-react-native330
---

---
title: "Migrate Adapty React Native SDK to v3.3"
description: "Migrate to Adapty React Native SDK v3.3 for better performance and new monetization features."
---

Adapty SDK 3.3.1 là bản phát hành lớn mang lại một số cải tiến có thể yêu cầu bạn thực hiện các bước migration.

1. Nâng cấp lên Adapty SDK v3.3.x.
2. Cập nhật các model.
3. Xóa phương thức `getProductsIntroductoryOfferEligibility`.
4. Cập nhật cách thực hiện giao dịch mua.
5. Cập nhật cách hiển thị paywall trong Paywall Builder.
6. Xem lại cách triển khai timer do developer định nghĩa.
7. Cập nhật cách xử lý sự kiện mua hàng trong Paywall Builder.
8. Cập nhật cách xử lý sự kiện custom action trong Paywall Builder.
9. Sửa đổi callback `onProductSelected`.
10. Xóa các tham số tích hợp bên thứ ba khỏi phương thức `updateProfile`.
11. Cập nhật cấu hình tích hợp cho Adjust, AirBridge, Amplitude, AppMetrica, Appsflyer, Branch, Facebook Ads, Firebase and Google Analytics, Mixpanel, OneSignal, và Pushwoosh.
12. Cập nhật cách triển khai Observer mode.

## Nâng cấp Adapty React Native SDK lên 3.3.x \{#upgrade-adapty-react-native-sdk-to-33x\}

Trước phiên bản 3.3.1, SDK `react-native-adapty` là SDK cốt lõi và bắt buộc để Adapty hoạt động đúng trong ứng dụng của bạn. SDK `@adapty/react-native-ui` là tùy chọn và chỉ cần thiết nếu bạn sử dụng Adapty Paywall Builder.

Kể từ phiên bản 3.3.1, SDK `@adapty/react-native-ui` đã bị deprecated và chức năng của nó đã được tích hợp vào SDK `react-native-adapty`. Để nâng cấp lên phiên bản 3.3.1, hãy thực hiện các bước sau:

1. Cập nhật gói `react-native-adapty` lên phiên bản 3.3.1.
2. Xóa gói `@adapty/react-native-ui` khỏi các dependency của dự án.
3. Đồng bộ hóa các dependency của dự án để áp dụng các thay đổi.

## Thay đổi trong các model \{#changes-in-models\}

### Model mới \{#new-models\}

1. [AdaptySubscriptionOffer](https://react-native.adapty.io/interfaces/adaptysubscriptionoffer):

    ```typescript showLineNumbers
    export interface AdaptySubscriptionOffer {
      readonly identifier: AdaptySubscriptionOfferId;

      phases: AdaptyDiscountPhase[];

      android?: {
        offerTags?: string[];
      };
    }
    ```

2. [AdaptySubscriptionOfferId](https://react-native.adapty.io/types/adaptysubscriptionofferid):

    ```typescript showLineNumbers
    export type AdaptySubscriptionOfferId =
      | { id?: string; type: 'introductory'; }
      | { id: string; type: 'promotional' | 'win_back'; };
    ```

### Model đã thay đổi \{#changed-models\}

1. [AdaptyPaywallProduct](https://react-native.adapty.io/interfaces/adaptypaywallproduct):
   
    - Đổi tên thuộc tính `subscriptionDetails` thành `subscription`.
      
      <p> </p>
      
     ```diff showLineNumbers
     -  subscriptionDetails?: AdaptySubscriptionDetails; 
     +  subscription?: AdaptySubscriptionDetails;
     ```
    
2. [AdaptySubscriptionDetails](https://react-native.adapty.io/interfaces/adaptysubscriptiondetails):

    - `promotionalOffer` đã bị xóa. Bây giờ ưu đãi chỉ được trả về trong thuộc tính `offer` nếu có. Trong trường hợp đó, `offer?.identifier?.type` sẽ là `'promotional'`.

    - `introductoryOfferEligibility` đã bị xóa (ưu đãi chỉ được trả về nếu người dùng đủ điều kiện).

    - `offerId` đã bị xóa. ID ưu đãi hiện được lưu trong `AdaptySubscriptionOffer.identifier`.

    - `offerTags` đã được chuyển sang `AdaptySubscriptionOffer.android`.
      
      <p> </p>

    ```diff showLineNumbers
    -  introductoryOffers?: AdaptyDiscountPhase[];
    +  offer?: AdaptySubscriptionOffer;
    
       ios?: {
    -    promotionalOffer?: AdaptyDiscountPhase;
         subscriptionGroupIdentifier?: string;
       };
    
       android?: {
    -    offerId?: string;
         basePlanId: string;
    -    introductoryOfferEligibility: OfferEligibility;
    -    offerTags?: string[];
         renewalType?: 'prepaid' | 'autorenewable';
       };
     }
    ```
3. [AdaptyDiscountPhase](https://react-native.adapty.io/interfaces/adaptydiscountphase):
   
    - Trường `identifier` đã bị xóa khỏi model `AdaptyDiscountPhase`. Identifier của ưu đãi hiện được lưu trong `AdaptySubscriptionOffer.identifier`.
      
      <p> </p>
      
     ```diff showLineNumbers
     -  ios?: {
     -    readonly identifier?: string;
     -  };
     ```

### Xóa các model \{#remove-models\}

1. `AttributionSource`:
   - Chuỗi string hiện được sử dụng ở những nơi trước đây dùng `AttributionSource`.
2. `OfferEligibility`:
   - Model này đã bị xóa vì không còn cần thiết. Hiện tại, ưu đãi chỉ được trả về nếu người dùng đủ điều kiện.

## Xóa phương thức `getProductsIntroductoryOfferEligibility` \{#remove-getproductsintroductoryoffereligibility-method\}

Trước Adapty SDK 3.3.1, các object sản phẩm luôn bao gồm ưu đãi, ngay cả khi người dùng không đủ điều kiện. Điều này yêu cầu bạn phải kiểm tra điều kiện thủ công trước khi sử dụng ưu đãi.

Kể từ phiên bản 3.3.1, object sản phẩm chỉ bao gồm ưu đãi nếu người dùng đủ điều kiện. Điều này đơn giản hóa quy trình vì bạn có thể giả định người dùng đủ điều kiện nếu có ưu đãi.

## Cập nhật cách thực hiện giao dịch mua \{#update-making-purchase\}

Trong các phiên bản trước, giao dịch bị hủy và đang chờ xử lý được coi là lỗi và trả về mã `2: 'paymentCancelled'` và `25: 'pendingPurchase'` tương ứng.

Kể từ phiên bản 3.3.1, giao dịch bị hủy và đang chờ xử lý hiện được coi là kết quả thành công và nên được xử lý tương ứng:

```typescript showLineNumbers
try {
    const purchaseResult = await adapty.makePurchase(product);
    switch (purchaseResult.type) {
      case 'success':
        const isSubscribed = purchaseResult.profile?.accessLevels['YOUR_ACCESS_LEVEL']?.isActive;

        if (isSubscribed) {
          // Grant access to the paid features
        }
        break;
      case 'user_cancelled':
        // Handle the case where the user canceled the purchase
        break;
      case 'pending':
        // Handle deferred purchases (e.g., the user will pay offline with cash)
        break;
    }
} catch (error) {
    // Handle the error
}
```

## Cập nhật cách hiển thị paywall trong Paywall Builder \{#update-paywall-builder-paywall-presentation\}

Để xem các ví dụ cập nhật, hãy tham khảo tài liệu [Hiển thị paywall mới từ Paywall Builder trong React Native](react-native-present-paywalls).

```diff showLineNumbers
- import { createPaywallView } from '@adapty/react-native-ui';
+ import { createPaywallView } from 'react-native-adapty/dist/ui';

const view = await createPaywallView(paywall);

view.registerEventHandlers(); // handle close press, etc

try {
  await view.present();
} catch (error) {
  // handle the error
}
```

## Cập nhật cách triển khai timer do developer định nghĩa \{#update-developer-defined-timer-implementation\}

Đổi tên tham số `timerInfo` thành `customTimers`:

```diff showLineNumbers
- let timerInfo = { 'CUSTOM_TIMER_NY': new Date(2025, 0, 1) }
+ let customTimers = { 'CUSTOM_TIMER_NY': new Date(2025, 0, 1) }
 //and then you can pass it to createPaywallView as follows:
- view = await createPaywallView(paywall, { timerInfo })
+ view = await createPaywallView(paywall, { customTimers })
```

## Sửa đổi sự kiện mua hàng trong Paywall Builder \{#modify-paywall-builder-purchase-events\}

Trước đây:

- Giao dịch bị hủy kích hoạt callback `onPurchaseCancelled`.
- Giao dịch đang chờ xử lý trả về mã lỗi `25: 'pendingPurchase'`.

Bây giờ:

- Cả hai trường hợp đều được xử lý bởi callback `onPurchaseCompleted`.

#### Các bước migration:

1. Xóa callback `onPurchaseCancelled`.
2. Xóa phần xử lý mã lỗi `25: 'pendingPurchase'`.
3. Cập nhật callback `onPurchaseCompleted`:

```typescript showLineNumbers

const view = await createPaywallView(paywall);

const unsubscribe = view.registerEventHandlers({
  // ... other optional callbacks
  onPurchaseCompleted(purchaseResult, product) {
    switch (purchaseResult.type) {
      case 'success':
        const isSubscribed = purchaseResult.profile?.accessLevels['YOUR_ACCESS_LEVEL']?.isActive;

        if (isSubscribed) {
          // Grant access to the paid features
        }
        break;
// highlight-start
      case 'user_cancelled':
        // Handle the case where the user canceled the purchase
        break;
      case 'pending':
        // Handle deferred purchases (e.g., the user will pay offline with cash)
        break;
// highlight-end
    }
// highlight-start
    return purchaseResult.type !== 'user_cancelled';
// highlight-end
  },
});
```

## Sửa đổi sự kiện custom action trong Paywall Builder \{#modify-paywall-builder-custom-action-events\}

Các callback đã bị xóa:

-  `onAction`
-  `onCustomEvent`

Callback mới được thêm vào:

- Callback `onCustomAction(actionId)` mới. Sử dụng nó cho các custom action.

## Sửa đổi callback `onProductSelected` \{#modify-onproductselected-callback\}

Trước đây, `onProductSelected` yêu cầu object `product`. Bây giờ yêu cầu `productId` dưới dạng chuỗi string.

## Xóa các tham số tích hợp bên thứ ba khỏi phương thức `updateProfile` \{#remove-third-party-integration-parameters-from-updateprofile-method\}

Các identifier tích hợp bên thứ ba hiện được thiết lập bằng phương thức `setIntegrationIdentifier`. Phương thức `updateProfile` không còn chấp nhận chúng nữa.

## Cập nhật cấu hình SDK tích hợp bên thứ ba \{#update-third-party-integration-sdk-configuration\}

Để đảm bảo các tích hợp hoạt động đúng với Adapty React Native SDK 3.3.1 trở lên, hãy cập nhật cấu hình SDK của bạn cho các tích hợp sau đây như được mô tả trong các phần bên dưới.

Ngoài ra, nếu bạn đã sử dụng `AttributionSource` để lấy attribution identifier, hãy thay đổi code của bạn để cung cấp identifier cần thiết dưới dạng chuỗi string.

### Adjust \{#adjust\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp Adjust](adjust#connect-your-app-to-adjust).

```diff showLineNumbers
 import { Adjust, AdjustConfig } from "react-native-adjust";
 import { adapty } from "react-native-adapty";

 var adjustConfig = new AdjustConfig(appToken, environment);

 // Before submiting Adjust config...
 adjustConfig.setAttributionCallbackListener(attribution => {
   // Make sure Adapty SDK is activated at this point
   // You may want to lock this thread awaiting of `activate`
   adapty.updateAttribution(attribution, "adjust");
 });

 // ...
 Adjust.create(adjustConfig);

+ Adjust.getAdid((adid) => {
+   if (adid)
+     adapty.setIntegrationIdentifier("adjust_device_id", adid);
+ });
```

### AirBridge \{#airbridge\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp AirBridge](airbridge#connect-your-app-to-airbridge).

```diff showLineNumbers
 import Airbridge from 'airbridge-react-native-sdk';
 import { adapty } from 'react-native-adapty';

 try {
   const deviceId = await Airbridge.state.deviceUUID();

-  await adapty.updateProfile({
-    airbridgeDeviceId: deviceId,
-  });
+  await adapty.setIntegrationIdentifier("airbridge_device_id", deviceId);
 } catch (error) {
   // handle `AdaptyError`
 }
```

### Amplitude \{#amplitude\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp Amplitude](amplitude#sdk-configuration).

```diff showLineNumbers
  import { adapty } from 'react-native-adapty';

 try {
-   await adapty.updateProfile({
-     amplitudeDeviceId: deviceId,
-     amplitudeUserId: userId,
-   });
+   await adapty.setIntegrationIdentifier("amplitude_device_id", deviceId);
+   await adapty.setIntegrationIdentifier("amplitude_user_id", userId);
 } catch (error) {
   // handle `AdaptyError`
 }
```

### AppMetrica \{#appmetrica\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp AppMetrica](appmetrica#sdk-configuration).

```diff showLineNumbers
 import { adapty } from 'react-native-adapty';
 import AppMetrica, { DEVICE_ID_KEY, StartupParams, StartupParamsReason } from '@appmetrica/react-native-analytics';

 // ...
 const startupParamsCallback = async (
   params?: StartupParams,
   reason?: StartupParamsReason
 ) => {
   const deviceId = params?.deviceId
   if (deviceId) {
     try {
-       await adapty.updateProfile({
-         appmetricaProfileId: 'YOUR_ADAPTY_CUSTOMER_USER_ID',
-         appmetricaDeviceId: deviceId,
-       });
+       await adapty.setIntegrationIdentifier("appmetrica_profile_id", 'YOUR_ADAPTY_CUSTOMER_USER_ID');
+       await adapty.setIntegrationIdentifier("appmetrica_device_id", deviceId);
     } catch (error) {
       // handle `AdaptyError`
     }
   }
 }

 AppMetrica.requestStartupParams(startupParamsCallback, [DEVICE_ID_KEY])
```

### AppsFlyer \{#appsflyer\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp AppsFlyer](appsflyer#connect-your-app-to-appsflyer).

```diff showLineNumbers
 import { adapty, AttributionSource } from 'react-native-adapty';
 import appsFlyer from 'react-native-appsflyer';

 appsFlyer.onInstallConversionData(installData => {
     try {
-        const networkUserId = appsFlyer.getAppsFlyerUID();
-        adapty.updateAttribution(installData, AttributionSource.AppsFlyer, networkUserId);
+        const uid = appsFlyer.getAppsFlyerUID();
+        adapty.setIntegrationIdentifier("appsflyer_id", uid);
+        adapty.updateAttribution(installData, "appsflyer");
     } catch (error) {
         // handle the error
     }
 });

 // ...
 appsFlyer.initSdk(/*...*/);
```

### Branch \{#branch\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp Branch](branch#connect-your-app-to-branch).

```diff showLineNumbers
 import { adapty, AttributionSource } from 'react-native-adapty';
 import branch from 'react-native-branch';

 branch.subscribe({
   enComplete: ({
     params,
   }) => {
-    adapty.updateAttribution(params, AttributionSource.Branch);
+    adapty.updateAttribution(params, "branch");
   },
 });
```

### Facebook Ads \{#facebook-ads\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp Facebook Ads](facebook-ads#connect-your-app-to-facebook-ads).

```diff showLineNumbers
 import { adapty } from 'react-native-adapty';
 import { AppEventsLogger } from 'react-native-fbsdk-next';

 try {
   const anonymousId = await AppEventsLogger.getAnonymousID();

-  await adapty.updateProfile({
-    facebookAnonymousId: anonymousId,
-  });
+  await adapty.setIntegrationIdentifier("facebook_anonymous_id", anonymousId);
 } catch (error) {
   // handle `AdaptyError`
 }
```

### Firebase and Google Analytics \{#firebase-and-google-analytics\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp Firebase and Google Analytics](firebase-and-google-analytics).

```diff showLineNumbers
 import analytics from '@react-native-firebase/analytics';
 import { adapty } from 'react-native-adapty';

 try {
   const appInstanceId = await analytics().getAppInstanceId();

-   await adapty.updateProfile({
-     firebaseAppInstanceId: appInstanceId,
-   });
+   await adapty.setIntegrationIdentifier("firebase_app_instance_id", appInstanceId);
 } catch (error) {
   // handle `AdaptyError`
 }
```

### Mixpanel \{#mixpanel\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp Mixpanel](mixpanel#sdk-configuration).

```diff showLineNumbers
 import { adapty } from 'react-native-adapty';
 import { Mixpanel } from 'mixpanel-react-native';

 // ...
 try {
-   await adapty.updateProfile({
-     mixpanelUserId: mixpanelUserId,
-   });
+   await adapty.setIntegrationIdentifier("mixpanel_user_id", mixpanelUserId);
 } catch (error) {
   // handle `AdaptyError`
 }
```

### OneSignal \{#onesignal\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp OneSignal](onesignal#sdk-configuration).

<Tabs groupId="current-os" queryString> 

<TabItem value="v5+" label="OneSignal SDK v5+ (current)" default> 

```diff showLineNumbers
 import { adapty } from 'react-native-adapty';
 import OneSignal from 'react-native-onesignal';

 OneSignal.User.pushSubscription.addEventListener('change', (subscription) => {
   const subscriptionId = subscription.current.id;

   if (subscriptionId) {
-    adapty.updateProfile({
-      oneSignalSubscriptionId: subscriptionId,
-    });
+    adapty.setIntegrationIdentifier("one_signal_subscription_id", subscriptionId);
   }
 });
```

 </TabItem> 

<TabItem value="pre-v5" label="OneSignal SDK v. up to 4.x (legacy)" default> 

```diff showLineNumbers
 import { adapty } from 'react-native-adapty';
 import OneSignal from 'react-native-onesignal';

 OneSignal.addSubscriptionObserver(event => {
   const playerId = event.to.userId;
   
-  adapty.updateProfile({
-    oneSignalPlayerId: playerId,
-  });
+  adapty.setIntegrationIdentifier("one_signal_player_id", playerId);
 });
```

 </TabItem> 

</Tabs>

### Pushwoosh \{#pushwoosh\}

Cập nhật code ứng dụng di động của bạn như hướng dẫn bên dưới. Để xem ví dụ code đầy đủ, hãy xem [Cấu hình SDK cho tích hợp Pushwoosh](pushwoosh#sdk-configuration).

```diff showLineNumbers
 import { adapty } from 'react-native-adapty';
 import Pushwoosh from 'pushwoosh-react-native-plugin';

 // ...
 try {
-  await adapty.updateProfile({
-    pushwooshHWID: hwid,
-  });
+  await adapty.setIntegrationIdentifier("pushwoosh_hwid", hwid);
 } catch (error) {
   // handle `AdaptyError`
 }
```

## Cập nhật cách triển khai Observer mode \{#update-observer-mode-implementation\}

Cập nhật cách bạn liên kết paywall với giao dịch. Trước đây, bạn sử dụng phương thức `setVariationId` để gán `variationId`. Bây giờ, bạn có thể đưa `variationId` trực tiếp khi ghi lại giao dịch bằng phương thức `reportTransaction` mới. Xem ví dụ code hoàn chỉnh trong [Liên kết paywall với giao dịch mua trong Observer mode](report-transactions-observer-mode-react-native).

:::warning

Đừng quên ghi lại giao dịch bằng phương thức `reportTransaction`. Bỏ qua bước này đồng nghĩa với việc Adapty sẽ không nhận ra giao dịch, không cấp mức độ truy cập, không đưa vào analytics, và không gửi đến các tích hợp. Đây là bước không thể bỏ qua!

:::

:::note

Hãy lưu ý rằng thứ tự các tham số của phương thức `reportTransaction` khác với phương thức `setVariationId`.

:::

```diff showLineNumbers
  const variationId = paywall.variationId;

 try {
-    await adapty.setVariationId(variationId, transactionId);
+    await adapty.reportTransaction(transactionId, variationId);
 } catch (error) {
     // handle the `AdaptyError`
 }

```

---


# File: migration-to-react-native-sdk-v3
---

---
title: "Migrate Adapty React Native SDK to v3.0"
description: "Migrate to Adapty React Native SDK v3.0 for better performance and new monetization features."
---

Adapty SDK v3.0 hỗ trợ [Adapty Paywall Builder](adapty-paywall-builder) mới — công cụ no-code thân thiện với người dùng để tạo paywall. Với tính linh hoạt tối đa và khả năng thiết kế phong phú, paywall của bạn sẽ trở nên hiệu quả và sinh lời hơn bao giờ hết.

## Nâng cấp lên phiên bản 3.0.1 \{#upgrade-to-version-301\}

1. Nâng cấp lên phiên bản 3.0.1 như bình thường.
2. Thay thế các tệp paywall dự phòng:
   1. [Tải phiên bản mới nhất](fallback-paywalls) từ Adapty Dashboard.
   2. Lưu chúng trên thiết bị của người dùng và truyền vào phương thức `.setFallbackPaywalls` như mô tả [tại đây](react-native-use-fallback-paywalls).

---


# End of Documentation

_Generated on: 2026-06-24T14:36:38.818Z_
_Successfully processed: 44/44 files_