Hiển thị các phần tử tùy chỉnh với Android SDK

Khi một màn hình có phần tử tùy chỉnh mở ra, Adapty SDK sẽ truyền Type và ID của phần tử đó đến một resolver trong mã nguồn ứng dụng của bạn. Resolver trả về một trong các kết quả sau:

  • View khớp với Type và ID: Người dùng thấy native view, chẳng hạn như animation Lottie, biểu đồ tương tác, hoặc camera preview.
  • Không có view: Người dùng thấy nội dung dự phòng, tức là nội dung bên trong phần tử tùy chỉnh trong Flow & Paywall Builder.

Người dùng các phiên bản ứng dụng chưa có resolver cũng sẽ thấy nội dung dự phòng. Vì vậy, bạn có thể xuất bản flow trước khi phát hành ứng dụng.

Trước khi bắt đầu

Bạn cần:

  • Adapty Android SDK 4.4 trở lên: Các phiên bản cũ hơn sẽ hiển thị fallback cho mọi custom element.
  • Ứng dụng Android native: Các Adapty SDK dành cho framework đa nền tảng như Flutter sẽ hiển thị fallback cho mọi custom element.
  • Quy tắc đặt tên cho custom element: Gán cho mỗi native view một Type, chẳng hạn như lottie_animation. Chỉ sử dụng chữ thường, số và dấu gạch dưới trong Type. Để phân biệt các custom element cùng Type, gán cho mỗi element một ID, chẳng hạn như welcome_wave. Type và ID trong code phải khớp với những gì bạn đã cấu hình trong Flow & Paywall Builder.

Nếu ứng dụng iOS của bạn đã hiển thị các phần tử tùy chỉnh, hãy tái sử dụng Types và IDs của chúng. Trừ khi bạn thiết lập một đối tượng riêng cho từng nền tảng, người dùng iOS và Android sẽ thấy cùng một flow.

Tạo view cho các phần tử tùy chỉnh

Với mỗi Type, hãy tạo mới hoặc tái sử dụng một composable/Android View. Các view sau đây thuộc Type lottie_animation sẽ phát một hoạt ảnh Lottie từ thư mục assets trong ứng dụng của bạn. Ví dụ Kotlin là một composable sử dụng thư viện com.airbnb.android:lottie-compose. Ví dụ Java tạo một Android View từ thư viện com.airbnb.android:lottie:

Yêu cầu và các phương pháp tốt nhất

  • Kích thước:

    • Padding và căn chỉnh: Đảm bảo native view vừa khít với container bạn đã phân bổ trong Flow & Paywall Builder, trừ phần padding. Nếu view không chiếm toàn bộ diện tích, mặc định nó sẽ hiển thị ở góc trên bên trái của vùng đó. Để di chuyển nó, hãy thay đổi căn chỉnh trong phần Layout của custom element.
    • Hug height: Nếu chiều cao của custom element được đặt thành Hug, một view kéo dài để lấp đầy không gian có sẵn (như lazy list) sẽ bị thu gọn hoặc kéo dài đến chiều cao của màn hình. Hãy đặt chiều cao Fixed cho custom element thay vào đó.
  • Theme: Để hiển thị composable theo màu sắc và font chữ của ứng dụng trên màn hình được xây dựng bằng Views, hãy bọc nó trong Compose theme của bạn.

  • Flow actions: Native view không thể kích hoạt các flow action, chẳng hạn như chuyển sang màn hình tiếp theo. Hãy giữ các nút điều hướng, nút mua hàng và các nút có flow action khác bên ngoài custom element.

  • Selectable elements: Giữ custom element bên ngoài các thẻ sản phẩm và các selectable element khác. Khi lựa chọn thay đổi, native view có thể mất trạng thái của nó.

  • Xử lý điều hướng: Khi người dùng chuyển sang màn hình tiếp theo, SDK sẽ xóa native view khỏi màn hình. Hãy dừng những gì view đã khởi động, chẳng hạn như camera session, player và cập nhật vị trí:

    • Composable: Sử dụng khối onDispose của DisposableEffect. Với các tác vụ bất đồng bộ, hãy dùng LaunchedEffect: Compose sẽ hủy nó khi composable rời khỏi composition.
    • Android View: Override onDetachedFromWindow trong subclass View của bạn, hoặc thêm View.OnAttachStateChangeListener vào View.

    Khi người dùng quay lại, hoặc sau khi có thay đổi cấu hình như xoay màn hình, SDK sẽ gọi lại resolver và tạo một native view mới mà không có trạng thái của view trước đó.

  • Carousel: Trong một carousel, các native view trên tất cả các slide đều hoạt động trong khi màn hình đang mở, không chỉ view trên slide đang hiển thị. Hãy tránh đặt camera preview và trình phát có âm thanh vào carousel.

Viết resolver để khớp các phần tử và view tùy chỉnh

Để viết một resolver, hãy implement interface AdaptyCustomElementsResolver. Phương thức resolve của nó nhận Type và ID của một phần tử tùy chỉnh, và trả về view tương ứng theo một trong các dạng sau:

  • Một composable: Trả về AdaptyCustomElementContent.compose, với composable bên trong lambda của nó.
  • Một Android View: Trả về AdaptyCustomElementContent.view, với một hàm tạo ra View. Trong Kotlin, hãy đặt tên cho tham số factory: AdaptyCustomElementContent.view(factory = { context, _ -> ChartView(context) }). Nếu không đặt tên, Kotlin sẽ truyền một trailing lambda vào tham số update tùy chọn, và code sẽ không biên dịch được.

Cho kiểu lottie_animation, resolver sau đây trả về Lottie view. ID là tên file animation trong thư mục assets, ví dụ welcome_wave cho welcome_wave.json:

Đối với bất kỳ Type nào khác, hãy trả về null. Nếu bạn thêm một phần tử tùy chỉnh với Type mới sau khi phát hành ứng dụng, người dùng của phiên bản đã phát hành sẽ thấy fallback của nó.

Resolver có các yêu cầu sau:

  • Dữ liệu mạng và player: Giữ dữ liệu mạng và player trong state của native view, không phải trong resolver. SDK gọi resolver nhiều lần trong khi màn hình đang mở. Code trong resolver chạy lại mỗi lần được gọi, do đó các yêu cầu mạng sẽ lặp lại và player sẽ bắt đầu lại từ đầu. SDK không tạo lại native view giữa các lần gọi này, nên dữ liệu chỉ tải một lần và player vẫn tiếp tục phát. Hãy tạo player, session và các yêu cầu mạng bên trong native view:

    • Composable: Tạo player và session trong remember, và các yêu cầu mạng trong LaunchedEffect.
    • Android View: Tạo player, session và các yêu cầu mạng trong onAttachedToWindow.
  • Một native view cho mỗi custom element: Một số native view thay đổi khi màn hình đang mở, ví dụ khi dữ liệu của chúng tải xong hoặc khi người dùng nhấn vào. Hãy triển khai logic này trong native view, không phải trong resolver. Nếu resolver trả về một composable khác cho cùng một custom element, Compose sẽ reset state của view.

  • Một View mới cho mỗi lần hiển thị: Tạo một View mới trong mỗi lần gọi factory. SDK gọi factory mỗi khi custom element xuất hiện, chẳng hạn khi màn hình mở, khi người dùng quay lại màn hình, hoặc sau khi xoay màn hình.

  • Dữ liệu ứng dụng: Lưu một đối tượng chứa dữ liệu, chẳng hạn như StateFlow hoặc LiveData với daily streak, trong một property của resolver. Truyền đối tượng đó vào native view và theo dõi (observe) đối tượng ở đó:

    • Composable: Collect một StateFlow bằng collectAsState, hoặc observe một LiveData bằng observeAsState.
    • Android View: Observe đối tượng trong onAttachedToWindow, và dừng lại trong onDetachedFromWindow.

    Một giá trị bạn sao chép vào resolver, chẳng hạn như số streak, sẽ giữ nguyên như lúc bạn tạo resolver đó.

Đặt điều kiện cho nội dung dự phòng

Để hiển thị nội dung dự phòng thay vì một custom element trống, hãy trả về không có view trong các trường hợp sau:

  • Không có gì để hiển thị — file animation hoặc file dữ liệu cần thiết bị thiếu.
  • Không có gì để xử lý — người dùng đã bỏ qua một câu hỏi trong quiz và dữ liệu không đầy đủ.
  • Bị từ chối quyền truy cập — một quyền bị từ chối ngăn view truy cập vào tài nguyên.

Ví dụ, resolver trả về không có view khi file animation bị thiếu.

Đối với một quyền, chỉ trả về null khi người dùng đã từ chối quyền đó trước khi màn hình được mở. ContextCompat.checkSelfPermission trả về cùng một giá trị, PERMISSION_DENIED, trong hai trường hợp: trước khi ứng dụng lần đầu yêu cầu người dùng cấp quyền, và sau khi người dùng từ chối. Để phân biệt hai trường hợp này, hãy lưu kết quả của yêu cầu quyền và đọc kết quả đã lưu đó trong resolver. Nếu ứng dụng chưa yêu cầu quyền, hãy trả về native view thay vì null, và yêu cầu quyền bên trong view đó. Ví dụ: yêu cầu quyền truy cập vị trí khi map view xuất hiện, và hiển thị bản đồ ngay khi người dùng cấp quyền. Nếu bạn trả về null và người dùng cấp quyền sau đó, họ vẫn thấy fallback. Việc thay đổi quyền không khiến SDK gọi lại resolver. Native view chỉ xuất hiện sau khi SDK gọi lại resolver, chẳng hạn khi người dùng quay lại màn hình.

Truyền resolver vào SDK

Bắt đầu với một resolver toàn ứng dụng. SDK sẽ gọi resolver này trong mọi flow không có resolver riêng. Người dùng thấy các view native của bạn trong các flow và A/B test mới mà không cần phát hành lại ứng dụng. Các view này vẫn hiển thị dữ liệu riêng của từng người dùng, chẳng hạn như chuỗi ngày liên tiếp, vì chúng đọc dữ liệu đó từ ứng dụng của bạn.

Đính kèm một resolver cho một flow khi flow đó cần dữ liệu mà ứng dụng của bạn chỉ có khi mở flow đó. Ví dụ: một paywall hiển thị cân nặng mà người dùng đã nhập trong một flow trước đó, hoặc xem trước tài liệu mà người dùng muốn xuất. Bạn cũng có thể đính kèm một resolver cho một flow để hiển thị giao diện khác cho một Type trong flow đó.

Hiển thị view trong mọi flow

Để sử dụng resolver trong mọi flow, hãy gọi AdaptyUI.setCustomElementsResolver một lần, chẳng hạn trong phương thức onCreate của class Application của bạn:

Tip

Để hiển thị cùng một view trong mọi custom element của một Type, hãy truyền một map gồm các Type và view vào AdaptyCustomElementsResolver.of. Dùng map sẽ cần ít code hơn so với resolver class, nhưng bạn không thể đặt điều kiện cho nội dung dự phòng.

val appWideViews = mapOf(
    "confetti" to AdaptyCustomElementContent.compose { LottieElement("confetti.json") },
)
AdaptyUI.setCustomElementsResolver(AdaptyCustomElementsResolver.of(appWideViews))

Hiển thị dữ liệu cho một flow, chẳng hạn như tài liệu cần xuất

Một resolver mà bạn truyền vào một flow view sẽ thay thế resolver toàn ứng dụng trong flow view đó.

Để giữ nguyên các view toàn ứng dụng trong flow này, hãy truyền resolver toàn ứng dụng vào resolver này và gọi resolver toàn ứng dụng cho các Type và ID khác. Resolver sau đây xem trước tài liệu mà người dùng muốn xuất, và gọi resolver toàn ứng dụng cho mọi phần tử tùy chỉnh khác:

Truyền resolver vào tham số customElementsResolver của AdaptyUI.getFlowView:

Nếu bạn tự tạo AdaptyFlowView, hãy truyền resolver vào phương thức showFlow của nó. Trong Java, showFlow nhận các tham số giống với getFlowView, ngoại trừ activity. Trong Jetpack Compose, truyền resolver vào AdaptyFlowScreen. Để xem ví dụ về từng cách gọi, hãy đọc Hiển thị flow & paywall.

Nếu bạn dùng AdaptyCustomElementsResolver.of thay vì các lớp resolver, hãy merge map view toàn ứng dụng với map view của flow này: AdaptyCustomElementsResolver.of(appWideViews + flowViews). Truyền kết quả vào flow view. Nếu cùng một Type xuất hiện trong cả hai map, đoạn code này sẽ ưu tiên giữ lại view của flow hiện tại.

Kiểm tra trên thiết bị

Flow & Paywall Builder không thể chạy code ứng dụng của bạn, vì vậy canvas chỉ hiển thị fallback. Lỗi trong native view có thể làm crash ứng dụng. Trước khi phát hành, hãy kiểm tra mọi màn hình có custom element trên thiết bị thực:

  1. Để xem phiên bản mới nhất đã xuất bản của mỗi flow thay vì phiên bản được lưu trong bộ nhớ đệm, hãy đăng ký thiết bị làm thiết bị kiểm tra.

  2. Để xem các cảnh báo của Adapty SDK trong Logcat, hãy đặt mức log thành AdaptyLogLevel.WARN hoặc mức chi tiết hơn. Với mức mặc định AdaptyLogLevel.NONE, SDK sẽ không ghi log gì cả.

  3. Trên thiết bị, chạy một bản build có chứa resolver. Mở từng màn hình có phần tử tùy chỉnh và xác minh rằng native view xuất hiện và vừa khớp với phần tử tùy chỉnh đó. Nếu view có thể cuộn hoặc phản hồi thao tác kéo, hãy kiểm tra các cử chỉ này.

  4. Nếu paywall dự phòng xuất hiện thay vì native view, hãy tìm cảnh báo này trong Logcat: custom element <type>:<id> is not served by a resolver. Sau đó xác minh rằng:

    • Type và ID trong cảnh báo khớp với những gì trong code của bạn, từng chữ cái một.
    • Ứng dụng của bạn có file, dữ liệu hoặc quyền mà view cần.
    • Ứng dụng của bạn đã thiết lập resolver toàn ứng dụng.
    • Một resolver cho flow này, nếu bạn truyền vào, trả về view cho Type và ID tương ứng.

    Nếu cảnh báo không xuất hiện, hãy kiểm tra xem ứng dụng có đang sử dụng Adapty Android SDK 4.4 trở lên không.

  5. Nếu phần tử tùy chỉnh vẫn trống, tìm một trong các cảnh báo sau trong Logcat:

    • custom element <type>:<id> is not served by a resolver: Phần tử tùy chỉnh không có nội dung dự phòng và không có resolver nào trả về view cho nó. Kiểm tra lại từng mục ở bước 4.
    • content does not report its size: Composable không có chiều cao riêng. Hãy đặt chiều cao Fixed (cố định) cho phần tử tùy chỉnh.

    The SDK chỉ ghi lại cảnh báo kích thước cho các composable. Nếu một Android View trống mà không có cảnh báo, hãy đặt chiều cao Fixed cho phần tử tùy chỉnh đó.

  6. Để xem trước paywall dự phòng, trả về null cho Type và mở lại màn hình.

Ví dụ

Mỗi công thức đều có hướng dẫn thiết lập trong builder và code cho ứng dụng của bạn: