Hiển thị flows & paywalls - Android

Nếu bạn đã tạo một flow hoặc paywall, 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. Flow hoặc paywall đó đã chứa cả nội dung cần hiển thị lẫn cách thức hiển thị.

Hướng dẫn này dành cho các flow và paywall xây dựng bằng Paywall Builder mới được render bởi Adapty. Quy trình sẽ khác đối với paywall dùng Remote Config và Observer mode.

Để hiển thị paywall Remote Config, xem Hiển thị paywall được thiết kế bằng Remote Config.
Để hiển thị paywall ở chế độ Observer, xem Android - Hiển thị paywall Paywall Builder ở chế độ Observer

Để lấy đối tượng flowConfiguration dùng bên dưới, xem Lấy flows & paywalls.

Để hiển thị flow trực quan trên màn hình thiết bị, bạn phải cấu hình nó trước. Để làm điều này, hãy gọi phương thức AdaptyUI.getFlowView() hoặc tạo AdaptyFlowView trực tiếp:

   val flowView = AdaptyUI.getFlowView(
       activity,
       flowConfiguration,
       products,
       eventListener,
       insets,
       customAssets,
       tagResolver,
       timerResolver,
   )

   val flowView =
        AdaptyFlowView(activity) // or retrieve it from xml
   ...
   with(flowView) {
       showFlow(
           flowConfiguration,
           products,
					 eventListener,
           insets,
           customAssets,
           tagResolver,
           timerResolver,
       )
   }

AdaptyFlowView flowView = AdaptyUI.getFlowView(
        activity,
        flowConfiguration,
        products,
        eventListener,
        insets,
        customAssets,
        tagResolver,
        timerResolver
);

AdaptyFlowView flowView =
  new AdaptyFlowView(activity); //add to the view hierarchy if needed, or you receive it from xml
...
flowView.showFlow(flowConfiguration, products, eventListener, insets, customAssets, tagResolver, timerResolver);

<com.adapty.ui.AdaptyFlowView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Sau khi view được tạo thành công, bạn có thể thêm nó vào hệ thống phân cấp view và hiển thị lên màn hình thiết bị.

Nếu bạn lấy AdaptyFlowView không thông qua AdaptyUI.getFlowView(), bạn cũng cần gọi phương thức .showFlow().

Để hiển thị flow trực quan trên màn hình thiết bị, bạn cần cấu hình nó trước. Để làm điều này, hãy sử dụng composable function sau:

AdaptyFlowScreen(
    flowConfiguration,
    products,
    eventListener,
    insets,
    customAssets,
    tagResolver,
    timerResolver,
)

Các tham số yêu cầu:

Tham số	Bắt buộc	Mô tả
flowConfiguration	bắt buộc	Cung cấp một đối tượng `AdaptyUI.FlowConfiguration` chứa thông tin hiển thị của flow. Dùng phương thức `AdaptyUI.getFlowConfiguration(flow)` để tải nó. Xem thêm tại chủ đề Fetch the view configuration.
products	tùy chọn	Cung cấp một mảng `AdaptyPaywallProduct` để tối ưu thời điểm hiển thị sản phẩm trên màn hình. Nếu truyền `null`, AdaptyUI sẽ tự động lấy các sản phẩm cần thiết.
eventListener	tùy chọn	Cung cấp một `AdaptyFlowEventListener` để lắng nghe các sự kiện của flow. Nên dùng `AdaptyFlowDefaultEventListener` để tiện hơn. Xem thêm tại chủ đề Handle flow & paywall events.
insets	tùy chọn	Insets là khoảng trống xung quanh flow giúp các phần tử có thể nhấn không bị ẩn sau thanh hệ thống. Mặc định: `Unspecified` — Adapty sẽ tự động điều chỉnh insets, phù hợp với các flow hiển thị toàn màn hình (edge-to-edge). Nếu flow của bạn không phải edge-to-edge, bạn có thể muốn đặt insets tùy chỉnh. Xem hướng dẫn tại phần Change flow insets bên dưới.
customAssets	tùy chọn	Truyền một đối tượng `AdaptyCustomAssets` để thay thế hình ảnh và video trong flow hoặc paywall của bạn lúc runtime. Xem thêm tại Customize assets.
tagResolver	tùy chọn	Dùng `AdaptyUiTagResolver` để xử lý các thẻ tùy chỉnh trong văn bản của flow. Resolver này nhận một tham số tag và chuyển đổi nó thành chuỗi tương ứng. Xem thêm tại chủ đề Custom tags in Paywall Builder.
timerResolver	tùy chọn	Truyền resolver vào đây nếu bạn muốn dùng chức năng hẹn giờ tùy chỉnh.

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

Thay đổi inset của flow

Inset là khoảng cách xung quanh flow, giúp các phần tử có thể nhấn không bị che khuất bởi thanh hệ thống. Mặc định, Adapty sẽ tự động điều chỉnh inset, phù hợp với các flow hiển thị toàn màn hình (edge-to-edge).

Nếu flow của bạn không phải edge-to-edge, bạn có thể muốn đặt inset tùy chỉnh:

Nếu cả thanh trạng thái lẫn thanh điều hướng đều không chồng lên AdaptyFlowView, hãy dùng AdaptyFlowInsets.None.
Với các trường hợp phức tạp hơn, ví dụ như flow chồng lên thanh trạng thái phía trên nhưng không chồng lên phần dưới, bạn có thể chỉ đặt bottomInset về 0 như ví dụ dưới đây:


//create extension function
fun View.onReceiveSystemBarsInsets(action: (insets: Insets) -> Unit) {
    ViewCompat.setOnApplyWindowInsetsListener(this) { _, insets ->
        val systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars())
        ViewCompat.setOnApplyWindowInsetsListener(this, null)
        action(systemBarInsets)
        insets
    }
}
//and then use it with the view
flowView.onReceiveSystemBarsInsets { insets ->
    val flowInsets = AdaptyFlowInsets.vertical(insets.top, 0)
    flowView.showFlow(
           flowConfiguration,
           products,
					 eventListener,
           flowInsets,
           customAssets,
           tagResolver,
           timerResolver,
       )
}


...

ViewCompat.setOnApplyWindowInsetsListener(flowView, (view, insets) -> {
    Insets systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars());
    ViewCompat.setOnApplyWindowInsetsListener(flowView, null);

    AdaptyFlowInsets flowInsets =
                AdaptyFlowInsets.vertical(systemBarInsets.top, 0);
    flowView.showFlow(flowConfiguration, products, eventListener, flowInsets);

    return insets;
});

Sử dụng timer do nhà phát triển định nghĩa

Để sử dụng timer do nhà phát triển định nghĩa trong ứng dụng mobile của bạn, hãy tạo một đối tượng timerResolver—một dictionary hoặc map liên kết các timer tùy chỉnh với các giá trị chuỗi sẽ thay thế chúng khi flow được render. Đây là ví dụ:


...

val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to Calendar.getInstance(TimeZone.getDefault()).apply { set(2025, 0, 1) }.time, // New Year 2025
)
val timerResolver = AdaptyUiTimerResolver { timerId ->
    customTimers.getOrElse(timerId, { Date(System.currentTimeMillis() + 3600 * 1000L) /* in 1 hour */ } )
}


...

Map<String, Date> customTimers = new HashMap<>();
customTimers.put(
        "CUSTOM_TIMER_NY",
        new Calendar.Builder().setTimeZone(TimeZone.getDefault()).setDate(2025, 0, 1).build().getTime()
);
AdaptyUiTimerResolver timerResolver = new AdaptyUiTimerResolver() {
    @NonNull
    @Override
    public Date timerEndAtDate(@NonNull String timerId) {
        Date date = customTimers.get(timerId);
        return date != null ? date : new Date(System.currentTimeMillis() + 3600 * 1000L); /* in 1 hour */
    }
};

Trong ví dụ này, CUSTOM_TIMER_NY là Timer ID của timer do lập trình viên tự định nghĩa, được thiết lập trong Adapty dashboard. timerResolver đảm bảo ứng dụng của bạn cập nhật timer động với giá trị chính xác—chẳng hạn như 13d 09h 03m 34s (được tính bằng thời điểm kết thúc của timer, ví dụ như Ngày đầu năm mới, trừ đi thời điểm hiện tại).

Sử dụng custom tag

Để sử dụng custom tag trong ứng dụng mobile, hãy tạo một đối tượng tagResolver—một dictionary hoặc map liên kết các custom tag với giá trị chuỗi sẽ thay thế chúng khi flow được render. Ví dụ:

val customTags = mapOf("USERNAME" to "John")
val tagResolver = AdaptyUiTagResolver { tag -> customTags[tag] }

Map<String, String> customTags = new HashMap<>();
customTags.put("USERNAME", "John");
AdaptyUiTagResolver tagResolver = customTags::get;

Trong ví dụ này, USERNAME là custom tag bạn đã nhập trong Adapty dashboard dưới dạng <USERNAME/>. tagResolver đảm bảo rằng ứng dụng của bạn tự động thay thế custom tag này bằng giá trị được chỉ định—ví dụ như John.

Chúng tôi khuyến nghị tạo và điền dữ liệu vào tagResolver ngay trước khi hiển thị flow của bạn. Sau khi sẵn sàng, hãy truyền nó vào phương thức AdaptyUI mà bạn dùng để hiển thị flow.

Thay đổi màu chỉ báo tải của flow

Bạn có thể ghi đè màu mặc định của chỉ báo tải theo cách sau:


<style name="AppTheme" parent="android:Theme.Material.Light.NoActionBar">

    <item name="adapty_progressIndicatorColor">@color/yourColor</item>
</style>

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 code ứng dụng để hiển thị cho người dùng. Paywall đó đã bao gồm cả nội dung hiển thị lẫn cách thức hiển thị.

Hướng dẫn này chỉ dành cho paywall dùng Paywall Builder mới yêu cầu SDK v3.0. Quy trình hiển thị paywall sẽ khác nhau tùy theo phiên bản Paywall Builder được dùng để thiết kế, paywall dùng Remote Config, và chế độ Observer.

Để hiển thị paywall dùng Remote Config, xem Render paywall được thiết kế bằng Remote Config.
Để hiển thị paywall ở chế độ Observer, xem Android - Hiển thị paywall Paywall Builder trong chế độ Observer

Để lấy đối tượng viewConfiguration được dùng bên dưới, xem Tải paywall Paywall Builder và cấu hình của chúng.

Để hiển thị paywall trực quan trên màn hình thiết bị, trước tiên bạn cần cấu hình nó. Để làm điều này, hãy gọi phương thức AdaptyUI.getPaywallView() hoặc tạo AdaptyPaywallView trực tiếp:

   val paywallView = AdaptyUI.getPaywallView(
       activity,
       viewConfiguration,
       products,
       eventListener,
       insets,
       personalizedOfferResolver,
       tagResolver,
       timerResolver,
   )

   val paywallView =
        AdaptyPaywallView(activity) // or retrieve it from xml
   ...
   with(paywallView) {
       showPaywall(
           viewConfiguration,
           products,
					 eventListener,
           insets,
           personalizedOfferResolver,
           tagResolver,
           timerResolver,
       )
   }

AdaptyPaywallView paywallView = AdaptyUI.getPaywallView(
        activity,
        viewConfiguration,
        products,
        eventListener,
        insets,
        personalizedOfferResolver,
        tagResolver,
        timerResolver
);

AdaptyPaywallView paywallView =
  new AdaptyPaywallView(activity); //add to the view hierarchy if needed, or you receive it from xml
...
paywallView.showPaywall(viewConfiguration, products, eventListener, insets, personalizedOfferResolver, tagResolver, timerResolver);

<com.adapty.ui.AdaptyPaywallView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Sau khi view được tạo thành công, bạn có thể thêm nó vào view hierarchy và hiển thị lên màn hình thiết bị.

Nếu bạn nhận được AdaptyPaywallView không thông qua việc gọi AdaptyUI.getPaywallView(), bạn cũng cần gọi thêm phương thức .showPaywall().

Để hiển thị paywall trực quan lên màn hình thiết bị, trước tiên bạn cần cấu hình nó. Sử dụng composable function sau:

AdaptyPaywallScreen(
    viewConfiguration,
    products,
    eventListener,
    insets,
    personalizedOfferResolver,
    tagResolver,
    timerResolver,
)

Tham số yêu cầu:

Tham số	Bắt buộc	Mô tả
viewConfiguration	bắt buộc	Cung cấp đối tượng `AdaptyUI.LocalizedViewConfiguration` chứa thông tin hiển thị của paywall. Sử dụng phương thức `Adapty.getViewConfiguration(paywall)` để tải nó. Xem thêm tại chủ đề Lấy cấu hình hiển thị của paywall.
products	tùy chọn	Cung cấp một mảng `AdaptyPaywallProduct` để tối ưu thời điểm hiển thị sản phẩm trên màn hình. Nếu truyền `null`, AdaptyUI sẽ tự động tải các sản phẩm cần thiết.
eventListener	tùy chọn	Cung cấp `AdaptyUiEventListener` để lắng nghe các sự kiện của paywall. Nên kế thừa `AdaptyUiDefaultEventListener` để dễ sử dụng hơn. Xem thêm tại chủ đề Xử lý sự kiện paywall.
insets	tùy chọn	Insets là khoảng trống xung quanh paywall giúp các phần tử có thể nhấn không bị ẩn sau thanh hệ thống. Mặc định: `UNSPECIFIED` — Adapty sẽ tự động điều chỉnh insets, phù hợp với các paywall hiển thị toàn màn hình (edge-to-edge). Nếu paywall của bạn không phải edge-to-edge, bạn có thể muốn đặt insets tùy chỉnh. Cách thực hiện xem tại phần Thay đổi insets của paywall bên dưới.
personalizedOfferResolver	tùy chọn	Để chỉ định giá cá nhân hóa (đọc thêm), hãy implement `AdaptyUiPersonalizedOfferResolver` và truyền logic của bạn để ánh xạ `AdaptyPaywallProduct` thành `true` nếu giá sản phẩm được cá nhân hóa, ngược lại là `false`.
tagResolver	tùy chọn	Sử dụng `AdaptyUiTagResolver` để xử lý các thẻ tùy chỉnh trong văn bản của paywall. Resolver này nhận tham số là một thẻ và chuyển đổi nó thành chuỗi tương ứng. Xem thêm tại chủ đề Custom tags in Paywall Builder.
timerResolver	tùy chọn	Truyền resolver vào đây nếu bạn muốn sử dụng chức năng hẹn giờ tùy chỉnh.

Thay đổi insets của paywall

Insets là khoảng trống xung quanh paywall, giúp các phần tử có thể nhấn không bị ẩn sau thanh hệ thống. Theo mặc định, Adapty sẽ tự động điều chỉnh insets, phù hợp với các paywall hiển thị toàn màn hình (edge-to-edge).

Nếu paywall của bạn không hiển thị toàn màn hình, bạn có thể muốn đặt insets tùy chỉnh:

Nếu cả thanh trạng thái lẫn thanh điều hướng đều không chồng lên AdaptyPaywallView, hãy dùng AdaptyPaywallInsets.NONE.
Với các thiết lập tùy chỉnh hơn, chẳng hạn khi paywall chồng lên thanh trạng thái phía trên nhưng không chồng lên phần dưới, bạn có thể chỉ đặt bottomInset thành 0 như ví dụ dưới đây:


//create extension function
fun View.onReceiveSystemBarsInsets(action: (insets: Insets) -> Unit) {
    ViewCompat.setOnApplyWindowInsetsListener(this) { _, insets ->
        val systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars())
        ViewCompat.setOnApplyWindowInsetsListener(this, null)
        action(systemBarInsets)
        insets
    }
}
//and then use it with the view
paywallView.onReceiveSystemBarsInsets { insets ->
    val paywallInsets = AdaptyPaywallInsets.vertical(insets.top, 0)
    paywallView.showPaywall(
           viewConfiguration,
           products,
					 eventListener,
           paywallInsets,
           personalizedOfferResolver,
           tagResolver,
           timerResolver,
       )
}


...

ViewCompat.setOnApplyWindowInsetsListener(paywallView, (view, insets) -> {
    Insets systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars());
    ViewCompat.setOnApplyWindowInsetsListener(paywallView, null);

    AdaptyPaywallInsets paywallInsets =
                AdaptyPaywallInsets.of(systemBarInsets.top, 0);
    paywallView.showPaywall(paywall, products, viewConfiguration, paywallInsets, productTitleResolver);

    return insets;
});

Sử dụng timer do nhà phát triển định nghĩa

Để sử dụng timer do nhà phát triển định nghĩa trong ứng dụng của bạn, hãy tạo một đối tượng timerResolver—một dictionary hoặc map ánh xạ các timer tùy chỉnh với các giá trị chuỗi sẽ thay thế chúng khi paywall được render. Đây là một ví dụ:


...

val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to Calendar.getInstance(TimeZone.getDefault()).apply { set(2025, 0, 1) }.time, // New Year 2025
)
val timerResolver = AdaptyUiTimerResolver { timerId ->
    customTimers.getOrElse(timerId, { Date(System.currentTimeMillis() + 3600 * 1000L) /* in 1 hour */ } )
}


...

Map<String, Date> customTimers = new HashMap<>();
customTimers.put(
        "CUSTOM_TIMER_NY",
        new Calendar.Builder().setTimeZone(TimeZone.getDefault()).setDate(2025, 0, 1).build().getTime()
);
AdaptyUiTimerResolver timerResolver = new AdaptyUiTimerResolver() {
    @NonNull
    @Override
    public Date timerEndAtDate(@NonNull String timerId) {
        Date date = customTimers.get(timerId);
        return date != null ? date : new Date(System.currentTimeMillis() + 3600 * 1000L); /* in 1 hour */
    }
};

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

Sử dụng custom tag

Để sử dụng custom tag trong ứng dụng di động, hãy tạo một đối tượng tagResolver—một dictionary hoặc map ánh xạ các custom tag với giá trị chuỗi sẽ thay thế chúng khi paywall được hiển thị. Dưới đây là ví dụ:

val customTags = mapOf("USERNAME" to "John")
val tagResolver = AdaptyUiTagResolver { tag -> customTags[tag] }

Map<String, String> customTags = new HashMap<>();
customTags.put("USERNAME", "John");
AdaptyUiTagResolver tagResolver = customTags::get;

Trong ví dụ này, USERNAME là custom tag bạn đã nhập trong Adapty dashboard dưới dạng <USERNAME/>. tagResolver đảm bảo rằng ứng dụng của bạn sẽ tự động thay thế custom tag này bằng giá trị được chỉ định—ví dụ như John.

Chúng tôi khuyến nghị bạn tạo và điền dữ liệu vào tagResolver ngay trước khi hiển thị paywall. Sau khi đã sẵn sàng, hãy truyền nó vào phương thức AdaptyUI mà bạn sử dụng để hiển thị paywall.

Thay đổi màu của loading indicator trên paywall

Bạn có thể ghi đè màu mặc định của loading indicator theo cách sau:


<style name="AppTheme" parent="android:Theme.Material.Light.NoActionBar">

    <item name="adapty_progressIndicatorColor">@color/yourColor</item>
</style>