Phần tử tùy chỉnh

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 vào màn hình và nhập Type và ID của nó.
  2. Thêm nội dung dự phòng 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. Sử dụng Adapty SDK để gán cho nó cùng Type và ID.
  4. Xuất bản flow 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. 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 hoặc 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

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

    Custom element trong nhóm Media của bảng Add 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.

    Các trường Type và ID trong phần Element của cài đặt phần tử tùy chỉnh
  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

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

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 cũng chỉ hiển thị fallback. Để xem trước native view, hãy kiểm thử flow trên thiết bị trong một bản build của ứng dụng.

Empty custom element on the canvas with the text Add elements here as a fallback
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

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

4. Xuất bản và kiểm tra flow

Để xuất bản flow, 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. 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 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. Xem toàn bộ quy trình tại Test on a device.

Những thay đổi nào yêu cầu phát hành ứng dụng

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 đổiBạ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ácPhát hành bản cập nhật app với native view mớiNative 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ớiPhá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 flowFallback 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 testThê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 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 elementPhát hành bản cập nhật app với native view cho Type và ID mới, rồi publish flowFallback content
Fallback content, các cài đặt khác của custom elementPublish flow. Không cần cập nhật appNội dung đã được cập nhật

Ví dụ

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:

Khắc phục sự cố

  • 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 trong hướng dẫn iOS.
  • Người dùng thấy vùng trống: Thêm fallback và publish flow. Nếu bạn vẫn thấy vùng trống trên thiết bị test, 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.
  • 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.