Hiển thị flows & paywalls - Kotlin Multiplatform

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 đó đã bao gồm cả nội dung cần hiển thị lẫn cách thức hiển thị.

Hướng dẫn này đề cập đến các flow và paywall Paywall Builder mới được render bởi Adapty. Quy trình sẽ khác đối với paywall Remote Config và Observer mode.

Để trình bày Remote Config paywalls, xem Render paywall designed by remote config.
Để trình bày flows trong Observer mode, xem Present flows in Observer mode.

Để lấy đối tượng flow sử dụng bên dưới, xem Get flows & paywalls.

Adapty Kotlin Multiplatform SDK cung cấp hai cách để trình bày flows và paywalls:

With Compose Multiplatform
Without Compose Multiplatform

Với Compose Multiplatform

Để hiển thị một flow hoặc paywall, hãy dùng phương thức view.present() trên view được tạo bởi phương thức createFlowView. Mỗi view chỉ có thể dùng một lần. Nếu cần hiển thị lại flow, hãy gọi createFlowView thêm một lần nữa để tạo một view mới.

Việc tái sử dụng cùng một view mà không tạo lại có thể dẫn đến lỗi.


viewModelScope.launch {
    AdaptyUI.createFlowView(flow = flow).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}

Hiển thị dialog

Dùng phương thức này thay cho các dialog cảnh báo gốc khi một flow hoặc paywall đang được hiển thị trên Android. Trên Android, các alert thông thường sẽ xuất hiện phía sau view của flow, khiến người dùng không nhìn thấy được. Phương thức này đảm bảo dialog được hiển thị đúng cách phía trên flow trên tất cả các nền tảng.


viewModelScope.launch {
    view.showDialog(
        title = "Close this screen?",
        content = "You will lose access to exclusive offers.",
        primaryActionTitle = "Stay",
        secondaryActionTitle = "Close"
    ).onSuccess { action ->
        if (action == AdaptyUIDialogActionType.SECONDARY) {
            // User confirmed - close the flow
            view.dismiss()
        }
        // If primary - do nothing, user stays
    }.onError { error ->
        // handle the error
    }
}

Cấu hình kiểu hiển thị trên iOS

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


viewModelScope.launch {
    val view = AdaptyUI.createFlowView(flow = flow).getOrNull()
    view?.present(iosPresentationStyle = AdaptyUIIOSPresentationStyle.PAGESHEET)
}

Không dùng Compose Multiplatform

createNativeFlowView là một phần của module io.adapty:adapty-kmp cốt lõi. Nếu dự án của bạn không sử dụng Compose Multiplatform, bạn không cần dependency io.adapty:adapty-kmp-ui.

Để nhúng một flow hoặc paywall mà không dùng Compose Multiplatform, hãy gọi createNativeFlowView. Hàm này trả về một AdaptyNativeFlowView mà bạn thêm vào layout của mình:


val nativeView = AdaptyUI.createNativeFlowView(
    context = context,
    viewModelStoreOwner = activity,
    flow = flow,
    observer = myFlowObserver,
)

// Embed in your Compose layout:
AndroidView(
    factory = { nativeView.view },
    modifier = Modifier.fillMaxSize()
)

Theo mặc định, embedded view không áp dụng safe-area paddings — layout của bạn cần tự xử lý insets. Nếu muốn view tự áp dụng chúng, hãy truyền androidEnableSafeArea = true vào createNativeFlowView. Tham số này chỉ dành cho Android.

Vì các phương thức mặc định của interface KMP trở thành @required trong Swift, bạn không thể triển khai AdaptyUIFlowsEventsObserver trực tiếp từ Swift. Hãy khai báo một base class open trong iosMain trước:

open class BaseFlowObserver : AdaptyUIFlowsEventsObserver

Sau đó, kế thừa nó trong Swift, chỉ override những gì bạn cần:

class MyFlowObserver: BaseFlowObserver {
    override func flowViewDidPerformAction(view: AdaptyUIFlowView, action: any AdaptyUIAction) {
        if action is AdaptyUIActionCloseAction {
            // remove nativeView from your view hierarchy
        }
    }
}

let nativeView = AdaptyUI.shared.createNativeFlowView(
    flow: flow,
    observer: MyFlowObserver()
)
// nativeView.viewController is a UIViewController.
// Add it to your SwiftUI view or UIKit hierarchy.

Giải phóng view

Gọi dispose() khi xóa view khỏi layout. Thao tác này sẽ hủy đăng ký trình lắng nghe sự kiện và giải phóng tài nguyên nội bộ.

nativeView.dispose()

Thẻ tùy chỉnh

Thẻ tùy chỉnh giúp bạn không cần tạo nhiều flow hay paywall riêng biệt cho từng tình huống khác nhau. Hãy tưởng tượng một flow duy nhất có thể thay đổi linh hoạt dựa trên dữ liệu người dùng. Ví dụ, thay vì một câu chào chung chung “Xin chào!”, bạn có thể chào đích danh từng người với “Xin chào, John!” hoặc “Xin chào, Ann!”

Dưới đây là một số cách sử dụng thẻ tùy chỉnh:

Hiển thị tên hoặc email của người dùng trên flow hoặc paywall.
Hiển thị ngày trong tuần để thúc đẩy doanh số (ví dụ: “Chào Thứ Năm vui vẻ”).
Thêm thông tin cá nhân hóa về các sản phẩm bạn đang bán (chẳng hạn như tên của một chương trình thể dục hoặc số điện thoại trong ứng dụng VoIP).

Các thẻ tùy chỉnh giúp bạn tạo ra một flow linh hoạt, thích ứng với nhiều tình huống khác nhau, giúp giao diện ứng dụng trở nên cá nhân hóa và hấp dẫn hơn.

Trong một số trường hợp, ứng dụng của bạn có thể không biết phải thay thế thẻ tùy chỉnh bằng nội dung gì—đặc biệt khi người dùng đang dùng phiên bản cũ hơn của AdaptyUI SDK. Để tránh điều này, hãy luôn thêm văn bản dự phòng để thay thế các dòng chứa thẻ không xác định. Nếu không, người dùng có thể thấy các thẻ được hiển thị dưới dạng code (<USERNAME/>).

Để sử dụng thẻ tùy chỉnh trong flow hoặc paywall của bạn, hãy truyền chúng khi tạo flow view:


viewModelScope.launch {
    val customTags = mapOf(
        "USERNAME" to "John",
        "DAY_OF_WEEK" to "Thursday"
    )

    AdaptyUI.createFlowView(
        flow = flow,
        customTags = customTags
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}


val customTags = mapOf(
    "USERNAME" to "John",
    "DAY_OF_WEEK" to "Thursday"
)

val nativeView = AdaptyUI.createNativeFlowView(
    context = context,
    viewModelStoreOwner = activity,
    flow = flow,
    observer = myFlowObserver,
    customTags = customTags,
)


val customTags = mapOf(
    "USERNAME" to "John",
    "DAY_OF_WEEK" to "Thursday"
)

val nativeView = AdaptyUI.createNativeFlowView(
    flow = flow,
    observer = myFlowObserver,
    customTags = customTags,
)

Bộ đếm thời gian tùy chỉnh

Bộ đếm thời gian là công cụ tuyệt vời để quảng bá các ưu đãi đặc biệt và theo mùa có giới hạn thời gian. Tuy nhiên, cần lưu ý rằng bộ đếm này không kết nối với thời hạn hiệu lực của ưu đãi hay thời gian chạy của chiến dịch. Đây đơn giản chỉ là một đồng hồ đếm ngược độc lập, bắt đầu từ giá trị bạn đặt và giảm dần về không. Khi bộ đếm về không, không có gì xảy ra—nó chỉ dừng lại ở không.

Bạn có thể tùy chỉnh văn bản trước và sau bộ đếm để tạo thông điệp mong muốn, ví dụ: “Ưu đãi kết thúc sau: 10:00 giây.”

Để sử dụng bộ đếm thời gian tùy chỉnh trong flow hoặc paywall của bạn, hãy truyền chúng khi tạo flow view:


viewModelScope.launch {
    val customTimers = mapOf(
        "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
        "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
    )

    AdaptyUI.createFlowView(
        flow = flow,
        customTimers = customTimers
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}


val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
    "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
)

val nativeView = AdaptyUI.createNativeFlowView(
    context = context,
    viewModelStoreOwner = activity,
    flow = flow,
    observer = myFlowObserver,
    customTimers = customTimers,
)


val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
    "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
)

val nativeView = AdaptyUI.createNativeFlowView(
    flow = flow,
    observer = myFlowObserver,
    customTimers = customTimers,
)

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 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ị lẫn cách hiển thị nó.

Hướng dẫn này chỉ dành cho paywall Paywall Builder mới. Quy trình hiển thị paywall khác nhau đối với paywall được thiết kế bằng remote config và Observer mode.

Để hiển thị paywall Remote config, xem Render paywall được thiết kế bằng remote config.

SDK Kotlin Multiplatform của Adapty cung cấp hai cách để hiển thị paywall:

Với Compose Multiplatform
Không có Compose Multiplatform

Với Compose Multiplatform

Để hiển thị một paywall, 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 sử 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 view instance mới.

Việc tái sử dụng cùng một view mà không tạo lại có thể dẫn đến lỗi.


viewModelScope.launch {
    AdaptyUI.createPaywallView(paywall = paywall).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}

Hiển thị hộp thoại

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


viewModelScope.launch {
    view.showDialog(
        title = "Close paywall?",
        content = "You will lose access to exclusive offers.",
        primaryActionTitle = "Stay",
        secondaryActionTitle = "Close"
    ).onSuccess { action ->
        if (action == AdaptyUIDialogActionType.SECONDARY) {
            // User confirmed - close the paywall
            view.dismiss()
        }
        // If primary - do nothing, user stays
    }.onError { error ->
        // handle the error
    }
}

Cấu hình kiểu hiển thị trên iOS

Cấu hình cách paywall 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ị AdaptyUIIOSPresentationStyle.FULLSCREEN (mặc định) hoặc AdaptyUIIOSPresentationStyle.PAGESHEET.


viewModelScope.launch {
    val view = AdaptyUI.createPaywallView(paywall = paywall).getOrNull()
    view?.present(iosPresentationStyle = AdaptyUIIOSPresentationStyle.PAGESHEET)
}

Không dùng Compose Multiplatform

createNativePaywallView là một phần của module core io.adapty:adapty-kmp. Nếu dự án của bạn không dùng Compose Multiplatform, bạn không cần dependency io.adapty:adapty-kmp-ui.

Để nhúng paywall mà không dùng Compose Multiplatform, hãy gọi createNativePaywallView. Hàm này trả về một AdaptyNativePaywallView mà bạn thêm vào layout của mình:


val nativeView = AdaptyUI.createNativePaywallView(
    context = context,
    viewModelStoreOwner = activity,
    paywall = paywall,
    observer = myPaywallObserver,
)

// Embed in your Compose layout:
AndroidView(
    factory = { nativeView.view },
    modifier = Modifier.fillMaxSize()
)

Vì các phương thức mặc định của interface KMP trở thành @required trong Swift, bạn không thể implement AdaptyUIPaywallsEventsObserver trực tiếp từ Swift. Hãy khai báo một open base class trong iosMain trước:

open class BasePaywallObserver : AdaptyUIPaywallsEventsObserver

Sau đó kế thừa nó trong Swift, chỉ override những gì bạn cần:

class MyPaywallObserver: BasePaywallObserver {
    override func paywallViewDidPerformAction(view: AdaptyUIPaywallView, action: any AdaptyUIAction) {
        if action is AdaptyUIActionCloseAction {
            // remove nativeView from your view hierarchy
        }
    }
}

let nativeView = AdaptyUI.shared.createNativePaywallView(
    paywall: paywall,
    observer: MyPaywallObserver()
)
// nativeView.viewController is a UIViewController.
// Add it to your SwiftUI view or UIKit hierarchy.

Hủy view

Gọi dispose() khi xóa view khỏi layout. Thao tác này hủy đăng ký event listener và giải phóng tài nguyên nội bộ.

nativeView.dispose()

Thẻ tùy chỉnh

Thẻ tùy chỉnh giúp bạn tránh phải tạo nhiều paywall riêng lẻ cho từng tình huống khác nhau. Hãy tưởng tượng một paywall duy nhất có thể tự động thích nghi dựa trên dữ liệu người dùng. Ví dụ, thay vì hiển thị “Hello!” chung chung, bạn có thể chào người dùng cá nhân hóa như “Hello, John!” hay “Hello, Ann!”

Dưới đây là một số cách bạn có thể sử dụng thẻ tùy chỉnh:

Hiển thị tên hoặc email của người dùng trên paywall.
Hiển thị ngày trong tuần để thúc đẩy doanh số (ví dụ: “Happy Thursday”).
Thêm thông tin cá nhân hóa về sản phẩm bạn đang bán (chẳng hạn tên chương trình tập luyện hoặc số điện thoại trong ứng dụng VoIP).

Các custom tag giúp bạn tạo paywall linh hoạt, thích ứng với nhiều tình huống khác nhau, giúp giao diện ứng dụng trở nên cá nhân hóa và hấp dẫn hơn.

Trong một số trường hợp, ứng dụng của bạn có thể không biết cần thay thế custom tag bằng gì—đặc biệt khi người dùng đang dùng phiên bản cũ của AdaptyUI SDK. Để tránh điều này, hãy luôn thêm văn bản dự phòng để thay thế các dòng chứa custom tag không xác định. Nếu không, người dùng có thể thấy các tag hiển thị dưới dạng code (<USERNAME/>).

Để sử dụng custom tag trong paywall, hãy truyền chúng khi tạo paywall view:


viewModelScope.launch {
    val customTags = mapOf(
        "USERNAME" to "John",
        "DAY_OF_WEEK" to "Thursday"
    )

    AdaptyUI.createPaywallView(
        paywall = paywall,
        customTags = customTags
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}


val customTags = mapOf(
    "USERNAME" to "John",
    "DAY_OF_WEEK" to "Thursday"
)

val nativeView = AdaptyUI.createNativePaywallView(
    context = context,
    viewModelStoreOwner = activity,
    paywall = paywall,
    observer = myPaywallObserver,
    customTags = customTags,
)


val customTags = mapOf(
    "USERNAME" to "John",
    "DAY_OF_WEEK" to "Thursday"
)

val nativeView = AdaptyUI.createNativePaywallView(
    paywall = paywall,
    observer = myPaywallObserver,
    customTags = customTags,
)

Bộ đếm ngược tùy chỉnh

Bộ đếm ngược trên paywall là công cụ tuyệt vời để quảng bá các ưu đãi đặc biệt và theo mùa có giới hạn thời gian. Tuy nhiên, cần lưu ý rằng bộ đếm này không liên kết với thời hạn hiệu lực của ưu đãi hay thời gian chạy chiến dịch. Đây đơn giản chỉ là một bộ đếm ngược độc lập, bắt đầu từ giá trị bạn đặt và giảm dần về không. Khi bộ đếm về không, không có gì xảy ra—nó chỉ dừng lại ở không.

Bạn có thể tùy chỉnh văn bản trước và sau bộ đếm để tạo thông điệp mong muốn, ví dụ: “Ưu đãi kết thúc sau: 10:00 giây.”

Để sử dụng bộ đếm ngược tùy chỉnh trong paywall, hãy truyền chúng khi tạo paywall view:


viewModelScope.launch {
    val customTimers = mapOf(
        "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
        "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
    )

    AdaptyUI.createPaywallView(
        paywall = paywall,
        customTimers = customTimers
    ).onSuccess { view ->
        view.present()
    }.onError { error ->
        // handle the error
    }
}


val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
    "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
)

val nativeView = AdaptyUI.createNativePaywallView(
    context = context,
    viewModelStoreOwner = activity,
    paywall = paywall,
    observer = myPaywallObserver,
    customTimers = customTimers,
)


val customTimers = mapOf(
    "CUSTOM_TIMER_NY" to LocalDateTime(2025, 1, 1, 0, 0, 0),
    "CUSTOM_TIMER_SALE" to LocalDateTime(2024, 12, 31, 23, 59, 59)
)

val nativeView = AdaptyUI.createNativePaywallView(
    paywall = paywall,
    observer = myPaywallObserver,
    customTimers = customTimers,
)