Hướng dẫn này sử dụng API của Adapty Kotlin Multiplatform SDK v4 (beta). Nếu bạn đang dùng v3, hãy xem hướng dẫn migration để biết tên các phương thức tương ứng.

Để kích hoạt in-app purchase, bạn cần nắm rõ ba khái niệm quan trọng:

• Sản phẩm – những gì người dùng có thể mua (gói đăng ký, consumable, quyền truy cập trọn đời)
• Flow & paywall – các màn hình giới thiệu sản phẩm đến người dùng, được xây dựng bằng Flow & Paywall Builder không cần code. SDK lấy chúng qua getFlow. Nếu bạn muốn tự xây dựng giao diện trong code của mình, xem Implement custom paywalls.
• Placement – nơi và thời điểm hiển thị flow & paywall trong ứng dụng (ví dụ: main, onboarding, settings). Bạn gắn chúng vào các placement trên dashboard, sau đó yêu cầu chúng theo placement ID trong code. Điều này giúp dễ dàng chạy A/B test và hiển thị các nội dung khác nhau cho từng nhóm người dùng.

Adapty cung cấp cho bạn ba cách để kích hoạt tính năng mua hàng trong ứng dụng. Hãy chọn một trong số đó tùy theo yêu cầu của ứng dụng:

Triển khai	Độ phức tạp	Khi nào dùng
Adapty Flow & Paywall Builder	✅ Dễ	Bạn tạo một flow hoặc paywall hoàn chỉnh, sẵn sàng mua hàng trong trình xây dựng no-code. Adapty tự động hiển thị và xử lý toàn bộ logic mua hàng phức tạp, xác thực biên lai và quản lý gói đăng ký.
Paywall tùy chỉnh	🟡 Trung bình	Bạn tự triển khai giao diện paywall trong code của ứng dụng, nhưng vẫn lấy đối tượng flow từ Adapty để duy trì sự linh hoạt trong danh sách sản phẩm. Xem hướng dẫn.
Chế độ Observer	🔴 Khó	Bạn đã có cơ sở hạ tầng xử lý mua hàng riêng và muốn tiếp tục sử dụng. Lưu ý rằng chế độ observer có một số hạn chế trong Adapty. Xem bài viết.

Để hiển thị một flow hoặc paywall được tạo trong Adapty Flow & Paywall Builder, trong code ứng dụng của bạn, bạn chỉ cần:

1. Lấy flow hoặc paywall: Lấy từ Adapty.
2. Hiển thị và để Adapty xử lý giao dịch mua cho bạn: Hiển thị view trong ứng dụng của bạn.
3. Xử lý các hành động nút: Liên kết tương tác của người dùng với phản hồi của ứng dụng. Ví dụ: mở liên kết hoặc đóng paywall khi người dùng nhấn nút.

Trước khi bắt đầu

Trước khi bắt đầu, hãy hoàn thành các bước sau:

1. Kết nối ứng dụng của bạn với App Store và/hoặc Google Play trong Adapty Dashboard.
2. Tạo sản phẩm trong Adapty.
3. Tạo một flow hoặc paywall và thêm sản phẩm vào đó.
4. Tạo một placement và thêm flow hoặc paywall vào đó.
5. Cài đặt và kích hoạt SDK trong mã ứng dụng của bạn.

1. Lấy flow hoặc paywall

Các flow và paywall của bạn được liên kết với các placement được cấu hình trong dashboard. Placement cho phép bạn chạy các flow hoặc paywall khác nhau cho các đối tượng khác nhau hoặc chạy A/B test.

Để lấy một flow hoặc paywall được tạo trong Adapty Flow & Paywall Builder, bạn cần:

1. Lấy đối tượng flow theo ID placement bằng phương thức getFlow.

2. Tạo flow view bằng phương thức createFlowView. View chứa các phần tử giao diện và kiểu dáng cần thiết để hiển thị. Nếu flow không có view nào được cấu hình, createFlowView sẽ trả về lỗi — hãy xử lý lỗi đó trong onError.

Adapty.getFlow("YOUR_PLACEMENT_ID")
    .onSuccess { flow ->
        AdaptyUI.createFlowView(flow)
            .onSuccess { view ->
                view.present()
            }
            .onError { error ->
                // the flow has no view configured, or view creation failed
            }
    }
    .onError { error ->
        // handle the error
    }

2. Hiển thị flow hoặc paywall

Bây giờ, khi bạn đã có flow, chỉ cần thêm vài dòng code để hiển thị nó.

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

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

Sau khi view được tạo thành công, bạn có thể hiển thị nó lên màn hình thiết bị. Mỗi view chỉ có thể dùng một lần: sau khi gọi dismiss(), hãy gọi lại createFlowView để hiển thị flow thêm một lần nữa.

3. Xử lý các hành động nút

Khi người dùng nhấn các nút trong flow hoặc paywall, Kotlin Multiplatform SDK tự động xử lý việc mua hàng, khôi phục, đóng màn hình và mở liên kết.

Tuy nhiên, các nút khác có ID tùy chỉnh hoặc được định nghĩa sẵn và yêu cầu xử lý hành động trong code của bạn. Hoặc bạn có thể muốn ghi đè hành vi mặc định của chúng.

Ví dụ, đây là hành vi mặc định của nút đóng. Bạn không cần thêm nó vào code, nhưng ở đây bạn có thể thấy cách thực hiện nếu cần.

Lưu ý rằng theo mặc định, flow vẫn mở sau khi mua hàng thành công. Nếu bạn muốn đóng flow sau khi mua xong, hãy dismiss view trong callback flowViewDidFinishPurchase.

AdaptyUI.setFlowsEventsObserver(object : AdaptyUIFlowsEventsObserver {
    override fun flowViewDidPerformAction(view: AdaptyUIFlowView, action: AdaptyUIAction) {
        when (action) {
            is AdaptyUIAction.CloseAction -> mainUiScope.launch { view.dismiss() }
            else -> Unit
        }
    }

    override fun flowViewDidFinishPurchase(
        view: AdaptyUIFlowView,
        product: AdaptyPaywallProduct,
        purchaseResult: AdaptyPurchaseResult
    ) {
        if (purchaseResult !is AdaptyPurchaseResult.UserCanceled) {
            mainUiScope.launch { view.dismiss() }
        }
    }
})

Các bước tiếp theo

Flow hoặc paywall của bạn đã sẵn sàng để hiển thị trong ứng dụng. Hãy kiểm tra các giao dịch mua trong sandbox App Store hoặc trên Google Play Store để đảm bảo bạn có thể hoàn tất một giao dịch mua thử nghiệm từ flow.

Tiếp theo, bạn cần kiểm tra mức độ truy cập của người dùng để đảm bảo bạn hiển thị paywall hoặc cấp quyền truy cập tính năng trả phí cho đúng người dùng.

Ví dụ đầy đủ

Dưới đây là cách tích hợp tất cả các bước đó vào ứng dụng của bạn.

// Set up the observer for handling flow events
AdaptyUI.setFlowsEventsObserver(object : AdaptyUIFlowsEventsObserver {
    override fun flowViewDidPerformAction(view: AdaptyUIFlowView, action: AdaptyUIAction) {
        when (action) {
            is AdaptyUIAction.CloseAction -> mainUiScope.launch { view.dismiss() }
            else -> Unit
        }
    }

    override fun flowViewDidFinishPurchase(
        view: AdaptyUIFlowView,
        product: AdaptyPaywallProduct,
        purchaseResult: AdaptyPurchaseResult
    ) {
        if (purchaseResult !is AdaptyPurchaseResult.UserCanceled) {
            mainUiScope.launch { view.dismiss() }
        }
    }
})

// Get and display the flow
Adapty.getFlow("YOUR_PLACEMENT_ID")
    .onSuccess { flow ->
        AdaptyUI.createFlowView(flow)
            .onSuccess { view ->
                view.present()
            }
            .onError { error ->
                // the flow has no view configured — use custom logic
            }
    }
    .onError { error ->
        // handle the error
    }