Lấy flows & paywalls - Flutter

Nội dung mà getFlow trả về
✦
Flow Được tạo trong Flow & Paywall Builder — render nguyên bản trên thiết bị, không cần WebView
✦
Paywall của Paywall Builder cũ Toàn bộ nội dung được tạo trong Paywall Builder cũ

Sau khi thiết kế flow, bạn có thể hiển thị nó trong ứng dụng mobile. Bước đầu tiên là lấy flow hoặc paywall được liên kết với placement và cấu hình view của nó như mô tả bên dưới.

Lưu ý rằng chủ đề này đề cập đến các flow và paywall được thiết kế trong các builder của Adapty. Nếu bạn triển khai paywall tùy chỉnh, vui lòng tham khảo chủ đề Lấy paywall và sản phẩm cho paywall tùy chỉnh trong ứng dụng mobile.

Tip

Bạn 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, 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.

Trước khi bắt đầu

Bạn cần có:

Lấy flow/paywall

Nếu bạn đã thiết kế flow hoặc paywall trong builder, bạn không cần lo về việc render nó trong code ứng dụng để hiển thị cho người dùng. Flow hoặc paywall đó đã chứa cả nội dung hiển thị lẫn cách hiển thị. Tuy nhiên, bạn vẫn cần lấy ID của nó thông qua placement, cấu hình view, rồi mới có thể hiển thị trong ứng dụng.

Tải flow hoặc paywall và tạo view của nó càng sớm càng tốt — lý tưởng nhất là trước khi hiển thị. Phương thức createFlowView tải cấu hình view và bắt đầu tải xuống cũng như lưu cache các hình ảnh ở chế độ nền. Bạn gọi nó càng sớm thì các lượt tải xuống đó càng có nhiều thời gian để hoàn tất. Khi bạn hiển thị flow hoặc paywall, cấu hình và hình ảnh có thể đã được cache sẵn sàng để hiển thị.

Tip

Để làm ấm nhiều placement cùng lúc, hãy gọi preloadFlows (Flutter SDK 4.3.0+). Phương thức này chỉ cache JSON của placement, vì vậy createFlowView vẫn sẽ tải layout và hình ảnh.

Để lấy một flow hoặc paywall, sử dụng phương thức getFlow:

try {
  final flow = await Adapty().getFlow(placementId: 'YOUR_PLACEMENT_ID');
  // the requested flow/paywall
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
  // handle the error
}

Tham số:

Tham sốBắt buộcMô tả
placementIdbắt buộcĐịnh danh của Placement mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
fetchPolicymặc định: AdaptyFlowFetchPolicy.reloadRevalidatingCacheData

fetchPolicy xác định tầng nào SDK đọc trước, chứ không phải liệu SDK có thể dùng cache hay không. Theo mặc định, SDK sẽ ưu tiên gọi lên server và chỉ trả về dữ liệu từ cache nếu yêu cầu đó thất bại. Chúng tôi khuyến nghị dùng tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.

Tuy nhiên, nếu bạn cho rằng người dùng của mình thường xuyên gặp tình trạng mạng không ổn định, hãy cân nhắc dùng AdaptyFlowFetchPolicy.returnCacheDataElseLoad — tùy chọn này đảo ngược thứ tự: đọc cache trước, chỉ gọi server khi không có gì trong cache. Người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng thời gian tải sẽ nhanh hơn dù kết nối mạng có kém đến đâu. Cache được cập nhật thường xuyên, nên hoàn toàn an toàn khi sử dụng trong phiên để tránh các yêu cầu mạng không cần thiết.

Chính sách thứ ba, AdaptyFlowFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge), nằm giữa hai tùy chọn trên: đọc cache trước khi bản cache còn trẻ hơn Duration bạn truyền vào, và gọi server khi cache đã cũ hơn giá trị đó.

Lưu ý rằng cache vẫn được giữ nguyên sau khi khởi động lại ứng dụng và chỉ bị xóa khi cài đặt lại ứng dụng hoặc thực hiện dọn dẹp thủ công.

Adapty SDK lưu trữ paywall cục bộ ở hai tầng: cache được cập nhật thường xuyên như mô tả ở trên và paywall dự phòng. Chúng tôi cũng sử dụng CDN để tải paywall nhanh hơn và một server dự phòng độc lập trong trường hợp CDN không khả dụng. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản paywall mới nhất, đồng thời đảm bảo độ tin cậy ngay cả khi kết nối internet hạn chế.

loadTimeoutmặc định: 5 giây

Duration giới hạn thời gian chờ cho phương thức này. Nếu server Adapty không phản hồi kịp thời hoặc trả về lỗi, SDK sẽ trả về flow từ cache. Nếu không có gì trong cache và server hết thời gian chờ hoặc trả về lỗi server, SDK sẽ yêu cầu flow từ server dự phòng (bản sao CDN chỉ phục vụ đối tượng All Users của placement). Như là phương án cuối cùng, SDK sẽ trả về flow từ tệp dự phòng của bạn.

Lưu ý rằng trong một số trường hợp hiếm gặp, phương thức này có thể hết thời gian chờ muộn hơn một chút so với giá trị được chỉ định trong loadTimeout, vì thao tác này có thể bao gồm nhiều yêu cầu khác nhau ở bên dưới.

Tham số phản hồi

Tham sốMô tả
FlowMột đối tượng AdaptyFlow chứa các định danh của flow (instanceIdentity, variationId), tên, placement, các biến thể paywall (paywalls), và các Remote Config (remoteConfigs).

Lấy cấu hình view

Important

Hãy đảm bảo đăng công khai flow. Một flow có chỉnh sửa chưa được đăng sẽ có trạng thái Dirty, và placement của nó sẽ tiếp tục phục vụ phiên bản đã đăng gần nhất.

Nếu placement được thiết kế trong Flow & Paywall Builder hoặc old Paywall Builder, Adapty sẽ tự render giao diện cho bạn — thuộc tính hasViewConfiguration của flow được tải về sẽ là true. Tạo view bằng createFlowView, sau đó hiển thị flow hoặc paywall. Nếu placement là paywall tùy chỉnh không có giao diện Builder (hasViewConfiguration là false), hãy tự render thay thế.

Warning

Theo mặc định, khi đóng kết quả của phương thức createFlowView, nó sẽ được giải phóng, do đó bạn không thể hiển thị lại. Nếu cần hiển thị lại flow hoặc paywall, hãy gọi lại phương thức createFlowView, hoặc đóng mà không giải phóng trên SDK 4.1 trở lên.


try {
  final view = await AdaptyUI().createFlowView(flow: flow);
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Tham số:

Tham sốBắt buộcMô tả
flowbắt buộcĐối tượng AdaptyFlow để lấy view cho flow/paywall mong muốn.
localetùy chọnMã định danh của bản địa hóa flow dùng để render view — ví dụ: en hoặc pt-br. Nếu bỏ qua, view sẽ render bằng en, hoặc bằng bản địa hóa mặc định của flow nếu flow không có en. Xem Localizations and locale codes.
customLayoutId

tùy chọn

mặc định: null

SDK 4.1+

ID tùy chỉnh của một layout trong cấu hình layout của flow. Truyền vào để render layout đó thay vì layout mà SDK tự động chọn dựa trên loại thiết bị và kích thước màn hình. Nếu không có layout nào khớp với ID, lệnh gọi sẽ thất bại với AdaptyError. Flow & Paywall Builder chưa hỗ trợ gán ID layout tùy chỉnh, vì vậy hãy để trống tham số này.
customTagstùy chọnCác giá trị của ứng dụng cho custom tags của flow, trong một map với key là tên đầy đủ của từng tag. Xem chi tiết tại Pass data to flows.
customTimerstùy chọnNgày kết thúc của các timer Developer defined trong flow, trong một map từ Timer ID đến giá trị DateTime. Xem chi tiết tại Set up developer-defined timers.
preloadProductstùy chọnBật để tối ưu hóa thời gian hiển thị sản phẩm trên màn hình. Khi là true, AdaptyUI sẽ tự động tải các sản phẩm cần thiết. Mặc định: false.
loadTimeouttùy chọnGiá trị Duration giới hạn thời gian tải cấu hình view. Nếu hết thời gian chờ, dữ liệu đã cache hoặc fallback cục bộ sẽ được sử dụng.
Note

Nếu bạn đang sử dụng nhiều ngôn ngữ, hãy tìm hiểu cách thêm bản địa hóa flow và cách sử dụng mã locale đúng cách tại đây.

Sau khi có view, hãy hiển thị flow/paywall.

Lấy flow hoặc paywall cho đối tượng mặc định để tải nhanh hơn

Thông thường, flow và paywall được tải gần như ngay lập tức, nên bạn không cần lo lắng về việc tăng tốc quá trình này. Tuy nhiên, trong trường hợp bạn có nhiều đối tượng và placement, và người dùng có kết nối internet yếu, việc tải flow hoặc paywall có thể mất nhiều thời gian hơn mong muốn. Trong những tình huống như vậy, bạn có thể muốn hiển thị flow hoặc paywall mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị gì cả.

Để giải quyết vấn đề này, bạn có thể sử dụng phương thức getFlowForDefaultAudience, phương thức này sẽ lấy flow hoặc paywall của placement được chỉ định cho đối tượng All Users. Tuy nhiên, điều quan trọng cần hiểu là cách tiếp cận được khuyến nghị là lấy flow hoặc paywall bằng phương thức getFlow, như được mô tả chi tiết trong phần Lấy flow/paywall ở trên.

Warning

Lý do chúng tôi khuyến nghị sử dụng getFlow

Phương thức getFlowForDefaultAudience có một số hạn chế đáng kể:

  • Các vấn đề tương thích ngược tiềm ẩn: Nếu bạn cần hiển thị các paywall khác nhau cho các phiên bản ứng dụng khác nhau (phiên bản hiện tại và tương lai), bạn có thể gặp khó khăn. Bạn sẽ phải thiết kế các paywall hỗ trợ phiên bản hiện tại (legacy) hoặc chấp nhận rằng người dùng có phiên bản hiện tại (legacy) có thể gặp sự cố với các paywall không được hiển thị.
  • Mất khả năng nhắm mục tiêu: Tất cả người dùng sẽ thấy cùng một paywall được thiết kế cho đối tượng All Users, nghĩa là bạn mất đi khả năng nhắm mục tiêu cá nhân hóa (bao gồm theo quốc gia, attribution marketing hoặc các thuộc tính tùy chỉnh của riêng bạn).

Nếu bạn chấp nhận những hạn chế này để đổi lấy tốc độ tải flow hoặc paywall nhanh hơn, hãy sử dụng phương thức getFlowForDefaultAudience như sau. Nếu không, hãy tiếp tục dùng getFlow được mô tả ở trên.

try {
  final flow = await Adapty().getFlowForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
  // the requested flow/paywall
} on AdaptyError catch (adaptyError) {
  // handle error
} catch (e) {
  // handle unknown error
}
Tham sốBắt buộcMô tả
placementIdbắt buộcMã định danh của Placement. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
fetchPolicymặc định: AdaptyFlowFetchPolicy.reloadRevalidatingCacheData

fetchPolicy xác định SDK đọc từ lớp nào trước tiên, không phải là liệu nó có thể sử dụng cache hay không. Theo mặc định, SDK sẽ gọi lên server trước và trả về dữ liệu từ cache nếu yêu cầu đó thất bại. Chúng tôi khuyến nghị tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.

Tuy nhiên, nếu bạn cho rằng người dùng của mình thường xuyên gặp tình trạng mạng không ổn định, hãy cân nhắc dùng AdaptyFlowFetchPolicy.returnCacheDataElseLoad — thứ tự này sẽ đảo ngược lại: đọc cache trước và chỉ gọi lên server khi không có gì trong cache. Người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng sẽ có trải nghiệm tải nhanh hơn dù kết nối mạng có kém đến đâu. Cache được cập nhật thường xuyên nên hoàn toàn có thể dùng trong phiên làm việc để tránh các yêu cầu mạng.

Chính sách thứ ba, AdaptyFlowFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge), nằm giữa hai chính sách trên: đọc cache trước khi bản cache còn mới hơn Duration bạn truyền vào, và gọi lên server khi nó đã cũ hơn.

Lưu ý rằng cache vẫn được giữ nguyên sau khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt ứng dụng hoặc thực hiện xóa thủ công.

Tùy chỉnh assets

Để tùy chỉnh hình ảnh và video trong flow/paywall của bạn, hãy triển khai các custom asset.

Hero image và video có ID được định sẵn: hero_image và hero_video. Trong một custom asset bundle, bạn nhắm đến các phần tử này theo ID của chúng và tùy chỉnh hành vi của chúng.

Đối với các hình ảnh và video khác, bạn cần đặt custom ID trong Adapty dashboard.

Ví dụ, bạn có thể:

  • Hiển thị hình ảnh hoặc video khác nhau cho một số người dùng.
  • Hiển thị ảnh xem trước cục bộ trong khi hình ảnh chính từ xa đang tải.
  • Hiển thị ảnh xem trước trước khi phát video.
  • Hiển thị media được đóng gói sẵn trong ứng dụng để màn hình đầu tiên hiển thị mà không cần tải xuống. Xem Hiển thị media màn hình đầu tiên từ bundle ứng dụng.

Dưới đây là ví dụ về cách bạn có thể cung cấp custom asset thông qua một dictionary đơn giản:


final customAssets = {
    // Show a local image using a custom ID
    'custom_image': AdaptyCustomAsset.localImageAsset(
        assetId: 'assets/images/image_name.png',
    ),

    // Show a local video with a preview image
    'hero_video': AdaptyCustomAsset.localVideoAsset(
        assetId: 'assets/videos/custom_video.mp4',
    ),
};

try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customAssets: customAssets,
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}
Note

Nếu không tìm thấy tài nguyên, flow/paywall sẽ trở về giao diện mặc định của nó.

Thiết lập timer do nhà phát triển định nghĩa

Sử dụng phần này cho timer có hành vi Developer defined trong Flow & Paywall Builder. Trong builder, mỗi timer như vậy có một Timer ID (xem Để app của bạn đặt ngày kết thúc), và app của bạn sẽ đặt ngày kết thúc cho nó. Hãy sử dụng đúng Timer ID trong code giống với trong builder, từng ký tự một, bao gồm cả chữ hoa chữ thường và dấu cách. Nếu các ID khác nhau, timer sẽ không nhận được ngày kết thúc từ app của bạn.

Để đặt ngày kết thúc, hãy truyền một map customTimers vào phương thức createFlowView. Mỗi key trong map là một Timer ID, và giá trị của nó là một đối tượng DateTime xác định thời điểm hết hạn của timer. Dưới đây là ví dụ:


try {
  final view = await AdaptyUI().createFlowView(
    flow: flow,
    customTimers: {
      'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(hours: 6)),
      'CUSTOM_TIMER_NY': DateTime(DateTime.now().year + 1), // next New Year's Day
    },
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Đối với flow được nhúng bằng AdaptyUIFlowPlatformView, hãy truyền map tương tự vào tham số customTimers của nó.

Trong ví dụ này, CUSTOM_TIMER_NY và CUSTOM_TIMER_6H là Timer ID của hai bộ đếm thời gian Developer defined trong builder:

  • CUSTOM_TIMER_NY: Thời gian còn lại cho đến Năm Mới tiếp theo.
  • CUSTOM_TIMER_6H: Thời gian còn lại trong khoảng thời gian 6 giờ bắt đầu khi ứng dụng của bạn tạo view.

SDK đọc customTimers một lần duy nhất khi tạo view, do đó một ngày được tính toán như CUSTOM_TIMER_6H sẽ bắt đầu đếm từ thời điểm đó, kể cả khi người dùng mở lại màn hình. Nếu ngày đã qua, bộ đếm hiển thị ngay về không và trigger On timer end sẽ chạy. Nếu customTimers không có key nào tương ứng với Timer ID, bộ đếm sẽ đếm ngược một giờ kể từ khi mở màn hình.

Sau khi bạn đã thiết kế phần giao diện cho paywall của mình bằng Paywall Builder cũ trong Adapty Dashboard, bạn có thể hiển thị nó trong ứng dụng di động. Bước đầu tiên trong quá trình này là lấy paywall liên kết với placement và cấu hình giao diện của nó như mô tả bên dưới.

Warning

Các paywall được xây dựng trong Paywall Builder của SDK 3.x yêu cầu Flutter SDK phiên bản 3.3.0 trở lên.

Vui lòng lưu ý rằng chủ đề này đề cập đến các paywall được tùy chỉnh bằng Paywall Builder. Nếu bạn triển khai paywall tùy chỉnh, hãy tham khảo chủ đề Lấy paywalls và sản phẩm cho paywall tùy chỉnh trong ứng dụng di động của bạn.

Tip

Bạn 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, 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.

Trước khi bắt đầu hiển thị paywall trong ứng dụng di động của bạn (nhấn để mở rộng)
  1. Tạo sản phẩm của bạn trong Adapty Dashboard.
  2. Tạo paywall và tích hợp các sản phẩm vào đó trong Adapty Dashboard.
  3. Tạo placement và tích hợp paywall vào đó trong Adapty Dashboard.
  4. Cài đặt Adapty SDK vào ứng dụng di động của bạn.

Lấy paywall được thiết kế bằng Paywall Builder

Nếu bạn đã thiết kế 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 như vậy đã bao gồm cả nội dung hiển thị lẫn cách hiển thị. Tuy nhiên, bạn vẫn cần lấy ID của nó qua placement, cấu hình view, rồi mới hiển thị trong ứng dụng.

Để đảm bảo hiệu suất tối ưu, điều quan trọng là phải lấy paywall và cấu hình view của nó càng sớm càng tốt, cho phép đủ thời gian để tải hình ảnh trước khi hiển thị cho người dùng.

Để lấy paywall, sử dụng phương thức getPaywall:

try {
  final paywall = await Adapty().getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en");
  // the requested paywall
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
}

Tham số:

Tham sốBắt buộcMô tả
placementIdbắt buộcĐịnh danh của Placement mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
locale

tùy chọn

mặc định: en

Định danh của bản địa hóa paywall. Tham số này phải là mã ngôn ngữ gồm một hoặc hai thẻ con phân cách bằng dấu trừ (-). Thẻ con đầu tiên là ngôn ngữ, thẻ con thứ hai là khu vực.

Ví dụ: en là tiếng Anh, pt-br là tiếng Bồ Đào Nha của Brazil.

Xem Bản địa hóa và mã ngôn ngữ để biết thêm thông tin về mã ngôn ngữ và cách chúng tôi khuyến nghị sử dụng chúng.

fetchPolicymặc định: AdaptyPaywallFetchPolicy.reloadRevalidatingCacheData

fetchPolicy xác định SDK đọc từ lớp nào trước, chứ không phải có được phép dùng cache hay không. Theo mặc định, SDK ưu tiên gọi lên server và chỉ trả về dữ liệu cache khi request đó thất bại. Chúng tôi khuyến nghị cách này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.

Tuy nhiên, nếu bạn cho rằng người dùng thường xuyên gặp tình trạng mạng không ổn định, hãy cân nhắc dùng AdaptyPaywallFetchPolicy.returnCacheDataElseLoad — cách này đảo ngược thứ tự ưu tiên: đọc cache trước và chỉ gọi server khi không có gì trong cache. Người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng thời gian tải sẽ nhanh hơn dù kết nối mạng có kém đến đâu. Cache được cập nhật thường xuyên nên hoàn toàn an toàn khi dùng trong phiên để tránh các network request không cần thiết.

Chính sách thứ ba, AdaptyPaywallFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge), nằm ở giữa hai cách trên: đọc cache trước khi bản cache còn trẻ hơn Duration bạn truyền vào, và gọi server khi cache đã cũ hơn thời gian đó.

Lưu ý rằng cache vẫn được giữ nguyên sau khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt hoặc thực hiện dọn dẹp thủ công.

Adapty SDK lưu trữ paywall cục bộ trên hai lớp: cache được cập nhật thường xuyên như mô tả ở trên và paywall dự phòng. Chúng tôi cũng sử dụng CDN để tải paywall nhanh hơn và một server dự phòng độc lập trong trường hợp CDN không thể truy cập. Hệ thống này được thiết kế để đảm bảo bạn luôn nhận được phiên bản paywall mới nhất đồng thời đảm bảo độ tin cậy ngay cả khi kết nối mạng kém.

loadTimeoutmặc định: 5 giây

Một Duration giới hạn thời gian chờ cho phương thức này. Nếu server Adapty không phản hồi kịp thời hoặc trả về lỗi, SDK sẽ trả về paywall từ server dự phòng (bản sao CDN chỉ phục vụ đối tượng All Users của placement), từ cache, hoặc từ file dự phòng của bạn.

Lưu ý rằng trong một số trường hợp hiếm gặp, phương thức này có thể timeout muộn hơn một chút so với giá trị đã chỉ định trong loadTimeout, do hoạt động có thể bao gồm nhiều request khác nhau bên dưới.

Tham số phản hồi

Tham sốMô tả
PaywallĐối tượng AdaptyPaywall chứa danh sách ID sản phẩm, mã định danh paywall, Remote Config và một số thuộc tính khác.

Lấy cấu hình view của paywall được thiết kế bằng Paywall Builder

Important

Hãy đảm bảo đã bật toggle Show on device trong paywall builder. Nếu tùy chọn này chưa được bật, cấu hình view sẽ không thể lấy được.

Sau khi fetch paywall, hãy kiểm tra xem paywall đó có chứa ViewConfiguration không — đây là dấu hiệu cho thấy paywall được tạo bằng Paywall Builder. Điều này sẽ giúp bạn xác định cách hiển thị paywall. Nếu ViewConfiguration có mặt, hãy xử lý như paywall của Paywall Builder; nếu không, xử lý như paywall tùy chỉnh.


try {
  final view = await AdaptyUI().createPaywallView(
        paywall: paywall,
      );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Sau khi có view, hãy hiển thị paywall.

Lấy paywall cho đối tượng mặc định để tải nhanh hơn

Thông thường, paywall được tải về gần như ngay lập tức, vì vậy bạn không cần lo lắng về việc tăng tốc quá trình này. Tuy nhiên, trong trường hợp bạn có nhiều đối tượng và paywall, và người dùng của bạn có kết nối internet yếu, việc tải paywall có thể mất nhiều thời gian hơn mong muốn. Trong những tình huống như vậy, bạn có thể muốn hiển thị một paywall mặc định để đảm bảo trải nghiệm người dùng mượt mà thay vì không hiển thị paywall nào cả.

Để giải quyết vấn đề này, bạn có thể dùng phương thức getPaywallForDefaultAudience, phương thức này sẽ lấy paywall của placement được chỉ định dành cho đối tượng All Users. Tuy nhiên, điều quan trọng cần hiểu là cách tiếp cận được khuyến nghị vẫn là lấy paywall bằng phương thức getPaywall, như đã trình bày trong phần Lấy thông tin paywall ở trên.

Warning

Tại sao chúng tôi khuyến nghị dùng getPaywall

Phương thức getPaywallForDefaultAudience có một số hạn chế đáng kể:

  • Các vấn đề tương thích ngược tiềm ẩn: Nếu bạn cần hiển thị các paywall khác nhau cho các phiên bản ứng dụng khác nhau (hiện tại và tương lai), bạn có thể gặp khó khăn. Bạn sẽ phải thiết kế các paywall hỗ trợ phiên bản hiện tại (cũ) hoặc chấp nhận rằng người dùng có phiên bản hiện tại (cũ) có thể gặp sự cố với các paywall không hiển thị được.
  • Mất khả năng nhắm mục tiêu: Tất cả người dùng sẽ thấy cùng một paywall được thiết kế cho đối tượng All Users, nghĩa là bạn mất đi khả năng cá nhân hóa nhắm mục tiêu (bao gồm theo quốc gia, attribution marketing hoặc các thuộc tính tùy chỉnh của riêng bạn).

Nếu bạn chấp nhận những hạn chế này để đổi lấy tốc độ tải paywall nhanh hơn, hãy sử dụng phương thức getPaywallForDefaultAudience như sau. Nếu không, hãy tiếp tục dùng getPaywall như đã mô tả ở trên.

try {
    final paywall = await Adapty().getPaywallForDefaultAudience(placementId: 'YOUR_PLACEMENT_ID');
} on AdaptyError catch (adaptyError) {
    // handle error
} catch (e) {
    // handle unknown error
}
Note

Phương thức getPaywallForDefaultAudience khả dụng từ Flutter SDK phiên bản 3.2.0 trở lên.

Tham sốBắt buộcMô tả
placementIdbắt buộcMã định danh của Placement. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
locale

tùy chọn

mặc định: en

Mã định danh của bản địa hóa paywall. Tham số này là mã ngôn ngữ gồm một hoặc nhiều subtag phân cách bằng dấu trừ (-). Subtag đầu tiên là ngôn ngữ, subtag thứ hai là khu vực.

Ví dụ: en là tiếng Anh, pt-br là tiếng Bồ Đào Nha (Brazil).

Xem Bản địa hóa và mã locale để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng.

fetchPolicymặc định: AdaptyPaywallFetchPolicy.reloadRevalidatingCacheData

fetchPolicy xác định SDK đọc từ lớp nào trước, chứ không phải liệu SDK có thể dùng cache hay không. Mặc định, SDK sẽ gọi lên server trước và trả về dữ liệu đã cache nếu yêu cầu đó thất bại. Chúng tôi khuyến nghị tùy chọn này vì nó đảm bảo người dùng luôn nhận được dữ liệu mới nhất.

Tuy nhiên, nếu bạn cho rằng người dùng của mình thường xuyên gặp kết nối internet không ổn định, hãy cân nhắc dùng AdaptyPaywallFetchPolicy.returnCacheDataElseLoad — tùy chọn này đảo ngược thứ tự đó: đọc cache trước và chỉ gọi server khi không có gì trong cache. Người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng thời gian tải sẽ nhanh hơn dù kết nối có kém đến đâu. Cache được cập nhật thường xuyên nên hoàn toàn an toàn khi dùng trong phiên để tránh các request mạng không cần thiết.

Chính sách thứ ba, AdaptyPaywallFetchPolicy.returnCacheDataIfNotExpiredElseLoad(maxAge), nằm giữa hai tùy chọn trên: đọc cache trước nếu bản cache còn mới hơn giá trị Duration bạn truyền vào, và gọi server khi cache đã cũ hơn.

Lưu ý rằng cache vẫn được giữ nguyên sau khi khởi động lại ứng dụng và chỉ bị xóa khi gỡ cài đặt ứng dụng hoặc dọn dẹp thủ công.

Tùy chỉnh assets

Để tùy chỉnh hình ảnh và video trong paywall của bạn, hãy triển khai custom assets.

Hero image và video có ID được định nghĩa sẵn: hero_image và hero_video. Trong một custom asset bundle, bạn nhắm đến các phần tử này bằng ID của chúng và tùy chỉnh hành vi của chúng.

Đối với các hình ảnh và video khác, bạn cần đặt custom ID trong Adapty dashboard.

Ví dụ, bạn có thể:

  • Hiển thị hình ảnh hoặc video khác cho một số người dùng.
  • Hiển thị hình ảnh xem trước cục bộ trong khi hình ảnh chính từ xa đang tải.
  • Hiển thị hình ảnh xem trước trước khi phát video.
Important

Để sử dụng tính năng này, hãy cập nhật Adapty Flutter SDK lên phiên bản 3.8.0 trở lên.

Dưới đây là ví dụ về cách bạn có thể cung cấp custom assets thông qua một dictionary đơn giản:


final customAssets = {
    // Show a local image using a custom ID
    'custom_image': AdaptyCustomAsset.localImageAsset(
        assetId: 'assets/images/image_name.png',
    ),

    // Show a local video with a preview image
    'hero_video': AdaptyCustomAsset.localVideoAsset(
        assetId: 'assets/videos/custom_video.mp4',
    ),
};

try {
  final view = await AdaptyUI().createPaywallView(
    paywall: paywall,
    customAssets: customAssets,
  );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}
Note

Nếu không tìm thấy asset, paywall sẽ trở về giao diện mặc định.

Thiết lập timer do nhà phát triển định nghĩa

Để sử dụng custom timer trong ứng dụng di động, hãy truyền một map customTimers vào phương thức createPaywallView. Mỗi key trong map là một timer ID, và giá trị tương ứng là một đối tượng DateTime xác định thời điểm timer kết thúc. Dưới đây là ví dụ:


try {
  final view = await AdaptyUI().createPaywallView(
        paywall: paywall,
        customTimers: {
          'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(seconds: 3600 * 6)),
          'CUSTOM_TIMER_NY': DateTime(2025, 1, 1), // New Year 2025
        },
      );
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Trong ví dụ này, CUSTOM_TIMER_NY và CUSTOM_TIMER_6H là các Timer ID của timer do developer định nghĩa, được cài đặt trong Adapty Dashboard. Map customTimers đảm bảo ứng dụng của bạn cập nhật động từng timer với giá trị chính xác. Ví dụ:

  • CUSTOM_TIMER_NY: Thời gian còn lại cho đến khi timer kết thúc, chẳng hạn như Ngày Năm Mới.
  • CUSTOM_TIMER_6H: Thời gian còn lại trong khoảng thời gian 6 giờ bắt đầu khi người dùng mở paywall.