---
title: "Phần tử tùy chỉnh"
description: "Thêm một view gốc, chẳng hạn như hoạt ảnh Lottie / Rive, biểu đồ tương tác hoặc xem trước camera, vào màn hình flow."
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

Với phần tử tùy chỉnh trong Flow & Paywall Builder, bạn có thể thêm một native view vào màn hình flow. Đó có thể là animation Lottie / Rive, biểu đồ tương tác, bản đồ, bản xem trước camera — hoặc bất kỳ view nào mà ứng dụng của bạn có thể hiển thị. Người dùng chỉ thấy native view trong các ứng dụng sử dụng Adapty iOS SDK 4.4 trở lên. Các ứng dụng sử dụng Adapty Android SDK hoặc SDK cho framework đa nền tảng như Flutter hay React Native sẽ hiển thị fallback cho mọi phần tử tùy chỉnh.

Để hiển thị một native view trên màn hình flow:

1. [Thêm phần tử tùy chỉnh](#add-and-configure) vào màn hình và nhập **Type** và **ID** của nó.
2. [Thêm nội dung dự phòng](#set-fallback-content) bên trong phần tử tùy chỉnh. Người dùng sẽ thấy nội dung này khi ứng dụng của bạn không hiển thị view.
3. [Thiết lập native view trong ứng dụng của bạn](#set-up-your-app-code). Sử dụng Adapty SDK để gán cho nó cùng Type và ID.
4. [Xuất bản flow](#publish-and-test) và kiểm tra trên thiết bị.
5. [Phát hành bản cập nhật ứng dụng với native view](#what-changes-require-an-app-release). Người dùng các phiên bản ứng dụng không có native view sẽ thấy nội dung dự phòng.

:::tip
Để hiển thị hình ảnh hoặc video hoạt hình, hãy dùng phần tử [**Image**](custom-media#image) hoặc [**Video**](custom-media#video) thay vì custom element. Cả hai đều không cần code trong app, và bạn có thể thay file mà không cần phát hành lại app.
:::

## 1. Thêm phần tử tùy chỉnh vào màn hình \{#add-and-configure\}

1. Mở bảng **Add element**. Trong nhóm **Media**, nhấp vào **Custom element**.

2. Nếu native view phản hồi thao tác chạm, hãy giữ custom element ra khỏi các container cũng phản hồi thao tác chạm, chẳng hạn như carousel. Như vậy, thao tác vuốt trong native view sẽ không làm carousel di chuyển.
3. Trong trường **Type**, nhập Type cho loại native view, ví dụ như `lottie_animation`:
   - **Quy tắc đặt tên**: Chỉ sử dụng chữ thường, số và dấu gạch dưới.
   - **Khớp chính xác**: Type phải khớp với Type trong ứng dụng của bạn, từng chữ một. Nếu viết khác đi, người dùng sẽ thấy fallback.
   - **Gợi ý**: Trường này gợi ý các Type đã được dùng trong flow này, không phải các Type trong ứng dụng của bạn.
4. Trong trường **ID**, thay giá trị được điền sẵn, chẳng hạn như `custom_1`, bằng một ID tùy chọn, ví dụ như `welcome_wave`. ID dùng để phân biệt các custom element có cùng Type.

5. Để dành một lượng không gian cố định cho native view, giữ nguyên chiều cao **Fixed** mặc định. Đặt nó bằng chiều cao mà view cần.
   - **Shared area**: Native view và nội dung dự phòng dùng chung cùng một vùng.
   - **Alignment**: Nếu native view nhỏ hơn vùng này, theo mặc định nó sẽ xuất hiện ở góc trên bên trái. Để di chuyển nó, hãy thay đổi căn chỉnh trong phần **Layout** của phần tử tùy chỉnh.

   :::important
   Với chiều cao **Hug**, một native view không có chiều cao riêng, chẳng hạn như bản đồ hoặc danh sách cuộn, sẽ bị thu gọn xuống gần bằng không.
   :::

6. (Tùy chọn) Để cắt native view theo các **Corners** bo tròn của phần tử tùy chỉnh, trong phần **Layout**, chọn hộp kiểm **Clip content**.

### Sử dụng native views trong nhiều custom elements \{#use-native-views-in-several-custom-elements\}

Các quy tắc sau áp dụng cho Type và ID của custom elements:

- **Type**: Nhập một Type cho mỗi loại native view, ví dụ `lottie_animation` cho Lottie player và `map` cho bản đồ.
- **ID**: Trong cùng một Type, gán ID duy nhất cho mỗi phần nội dung, ví dụ `streak_ring` và `welcome_wave` cho hai animation Lottie. Ứng dụng của bạn đọc ID này để chọn nội dung. Nếu hai custom element trên cùng một màn hình có cùng Type và ID, trường **ID** sẽ hiển thị cảnh báo: *Same type and ID as another element on this screen.* Bạn vẫn có thể publish flow.
- **Element copies**: Khi bạn nhân đôi hoặc dán một element, hoặc thêm một [tab](builder-tabs), builder sẽ tự đổi tên mỗi ID bị trùng trong màn hình hoặc component đó. Ví dụ: `custom_1` thành `custom_2`, và `hero` thành `hero_2`. Hãy đảm bảo code trong ứng dụng của bạn tham chiếu đúng ID.

## 2. Thêm nội dung dự phòng \{#set-fallback-content\}

Người dùng sẽ thấy nội dung dự phòng thay cho native view khi:

- Phiên bản ứng dụng của họ không có code cho view đó.
- Ứng dụng của bạn dùng Adapty Android SDK, SDK cho framework đa nền tảng, hoặc Adapty iOS SDK phiên bản cũ hơn 4.4.
- Type và ID của custom element không khớp với bất kỳ view nào trong code ứng dụng.
- Code ứng dụng khớp với Type và ID nhưng không trả về view nào. Ví dụ: view cần một file không có trên thiết bị, hoặc một quyền mà người dùng đã từ chối.

Để đặt fallback, hãy thêm các phần tử vào custom element container. Khi native view không hiển thị, một custom element không có fallback sẽ hiển thị trống.

Flow & Paywall Builder không thể chạy code của ứng dụng, vì vậy canvas của nó chỉ hiển thị fallback. [Bản xem trước trong ứng dụng Adapty trên di động](paywall-device-compatibility-preview#preview-on-devices) cũng chỉ hiển thị fallback. Để xem trước native view, hãy [kiểm thử flow trên thiết bị](#publish-and-test) trong một bản build của ứng dụng.

:::important
Giữ các nút điều hướng, nút mua hàng và các thành phần UI quan trọng khác bên ngoài custom element. Người dùng chỉ thấy một trong hai: native view hoặc fallback, không bao giờ thấy cả hai cùng lúc.
:::

Bạn không thể thêm **Footer**, **Sliding sheet** hay **Bottom Sheet** bên trong một custom element.

## 3. Thiết lập native view trong ứng dụng của bạn \{#set-up-your-app-code\}

Khi một màn hình có custom element được mở, Adapty SDK sẽ truyền Type và ID của element đó vào một hàm resolver trong code ứng dụng của bạn. Hàm resolver trả về một trong các trường hợp sau:

- **View khớp với Type và ID**: Người dùng sẽ thấy native view. Trong code, hãy viết đúng chính xác Type và ID như trong builder.
- **Không có view**: Người dùng sẽ thấy fallback. Ví dụ, trả về không có view khi file mà view cần không có trên thiết bị.

Đối với code iOS, hãy xem [Hiển thị các phần tử tùy chỉnh với iOS SDK](ios-flow-custom-elements). Bài viết đó hướng dẫn cách viết resolver và kiểm tra native view trên thiết bị.

:::tip
Một native view có thể hiển thị dữ liệu người dùng, chẳng hạn như câu trả lời từ một flow trước đó. Xem [Hiển thị biểu đồ mục tiêu cân nặng tương tác trong paywall](custom-element-interactive-chart).
:::

## 4. Xuất bản và kiểm tra flow \{#publish-and-test\}

Để [xuất bản flow](builder-save-publish), hãy đảm bảo rằng mỗi phần tử tùy chỉnh đều có Type tuân theo [quy tắc đặt tên](#add-and-configure). Bạn có thể xuất bản flow trước khi phát hành ứng dụng. Cho đến khi người dùng cập nhật ứng dụng, họ sẽ thấy paywall dự phòng.

Lỗi trong native view có thể làm crash app. Trước khi phát hành, hãy kiểm thử mọi màn hình có custom element trong bản build sử dụng native view. Để test một flow mà người dùng thực chưa thấy, hãy thêm nó vào một [placement](create-placement) mà bản build này gọi nhưng app đã phát hành chưa dùng. Để xem flow đã publish mới nhất thay vì bản cache, hãy đăng ký thiết bị làm [test device](test-devices). Xem toàn bộ quy trình tại [Test on a device](ios-flow-custom-elements#test-on-a-device).

## Những thay đổi nào yêu cầu phát hành ứng dụng \{#what-changes-require-an-app-release\}

Native views là một phần trong mã nguồn ứng dụng của bạn. Để thay đổi native view, hãy phát hành bản cập nhật ứng dụng. Để thay đổi nội dung dự phòng hoặc bất kỳ cài đặt nào của custom element ngoại trừ Type và ID, hãy publish flow.

| Nội dung thay đổi | Bạn cần làm gì | Người dùng chưa cập nhật app sẽ thấy |
|---|---|---|
| Native view của một custom element hiện có, chẳng hạn như animation khác | Phát hành bản cập nhật app với native view mới | Native view trước đó, nếu phiên bản app của họ có chứa nó |
| Native view cho một custom element mới | Phát hành bản cập nhật app với native view mới. Thêm custom element với Type và ID mới, rồi publish flow | Fallback content |
| Một native view hiện có trên màn hình khác, trong flow khác hoặc trong A/B test | Thêm custom element với cùng Type và ID, rồi publish flow. Không cần cập nhật app nếu [app-wide resolver](ios-flow-custom-elements#set-an-app-wide-resolver) của bạn trả về view đó | Native view, nếu phiên bản app của họ có chứa nó |
| Type hoặc ID của một custom element | Phát hành bản cập nhật app với native view cho Type và ID mới, rồi publish flow | Fallback content |
| Fallback content, các cài đặt khác của custom element | Publish flow. Không cần cập nhật app | Nội dung đã được cập nhật |

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

Mỗi ví dụ bao gồm cách thiết lập trong builder và code cho ứng dụng của bạn:

- [Hiển thị tiến trình người dùng bằng hoạt ảnh Lottie](custom-element-lottie-animation): Một vòng tròn điền đầy khi streak tăng lên.
- [Hiển thị biểu đồ mục tiêu cân nặng tương tác trong paywall](custom-element-interactive-chart): Biểu đồ mục tiêu cân nặng, trong flow paywall tiếp theo sau onboarding flow.
- [Hiển thị các địa điểm gần đây trên bản đồ trong một flow](custom-element-map): Bản đồ các trung tâm thể dục gần mỗi người dùng.

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

- **Người dùng thấy fallback thay vì native view**: Hãy đảm bảo Type và ID khớp với những gì trong ứng dụng của bạn, từng chữ một. Người dùng các phiên bản ứng dụng chưa có view sẽ thấy fallback cho đến khi họ cập nhật ứng dụng. Để tìm nguyên nhân trong code, hãy làm theo [Test on a device](ios-flow-custom-elements#test-on-a-device) trong hướng dẫn iOS.
- **Người dùng thấy vùng trống**: [Thêm fallback](#set-fallback-content) và publish flow. Nếu bạn vẫn thấy vùng trống trên [thiết bị test](test-devices), native view xuất hiện nhưng không có nội dung. Hãy đảm bảo resolver trả về `nil` khi thiếu nội dung, như trong [Set conditions for fallback content](ios-flow-custom-elements#set-conditions-for-fallback-content).
- **Native view không vừa với custom element**: Hãy đảm bảo ứng dụng của bạn fit view vào vùng của custom element. Để cắt view theo **Corners** bo tròn, trong mục **Layout**, hãy chọn checkbox **Clip content**.