Lấy flows & paywalls - Flutter

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

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

Trước khi bắt đầu hiển thị flow và paywall trong ứng dụng mobile 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 flow/paywall và thêm sản phẩm vào đó trong Adapty Dashboard.
3. Tạo placement và thêm flow/paywall vào đó trong Adapty Dashboard.
4. Cài đặt Adapty SDK vào ứng dụng mobile của bạn.

Lấy flow/paywall

Nếu bạn đã thiết kế một flow hoặc paywall bằng Flow Builder hoặc 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. Flow hoặc paywall đó đã bao gồm cả nội dung cần 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 hiển thị nó trong ứng dụng. Tải flow hoặc paywall và tạo view cho 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, lưu cache hình ảnh ở nền. Bạn gọi nó càng sớm thì hình ảnh càng có nhiều thời gian để tải xong. Đến lúc hiển thị flow hoặc paywall, cấu hình và hình ảnh của nó có thể đã được cache sẵn sàng hiển thị.

Để lấy flow hoặc paywall, 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
}

Các tham số:

Tham số	Bắt buộc	Mô tả
placementId	bắt buộc	Mã định danh của Placement mong muốn. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
fetchPolicy	mặc định: .reloadRevalidatingCacheData	Theo mặc định, SDK sẽ cố tải dữ liệu từ máy chủ và trả về dữ liệu đã cache nếu 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 người dùng của bạn thường xuyên gặp vấn đề về kết nối internet, hãy cân nhắc dùng .returnCacheDataElseLoad để trả về dữ liệu đã cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới tuyệt đối, nhưng thời gian tải sẽ nhanh hơn bất kể kết nối internet của họ như thế nào. 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. 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. Adapty SDK lưu trữ paywall cục bộ theo 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 máy chủ 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 mới nhất của paywall trong khi vẫn đảm bảo độ tin cậy ngay cả khi kết nối internet kém.
loadTimeout	mặ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 hết thời gian chờ, dữ liệu đã cache hoặc fallback cục bộ sẽ được trả về. 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 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ả
Flow	Mộ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

Nếu placement được thiết kế trong Flow Builder hoặc Paywall Builder, Adapty sẽ tự động render giao diệ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à một paywall tùy chỉnh không có giao diện Builder (hasViewConfiguration là false), hãy xử lý nó như một remote config paywall.

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ộc	Mô tả
flow	bắt buộc	Một đối tượng AdaptyFlow để lấy view cho flow/paywall mong muốn.
customTags	tùy chọn	Định nghĩa một map các custom tag và giá trị tương ứng. Custom tag đóng vai trò là placeholder trong nội dung, được thay thế động bằng các chuỗi cụ thể để cá nhân hóa nội dung trong flow/paywall. Xem thêm tại chủ đề Custom tags in paywall builder.
preloadProducts	tùy chọn	Bật tùy chọn này để tối ưu thời điểm hiển thị sản phẩm trên màn hình. Khi đặt là true, AdaptyUI sẽ tự động tải các sản phẩm cần thiết. Mặc định: false.
loadTimeout	tùy chọn	Một 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.

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.

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ộc	Mô tả
placementId	bắt buộc	Định danh của Placement. Đây là giá trị bạn đã chỉ định khi tạo placement trong Adapty Dashboard.
fetchPolicy	mặc định: .reloadRevalidatingCacheData	Theo mặc định, SDK sẽ cố tải dữ liệu từ server và trả về dữ liệu đã cache nế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 người dùng của bạn thường gặp tình trạng mạng không ổn định, hãy cân nhắc dùng .returnCacheDataElseLoad để trả về dữ liệu đã cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng sẽ tải nhanh hơn dù kết nối mạng chập chờn. 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 làm việc để tránh các request mạng không cần thiết. 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 xóa thủ công.

Tùy chỉnh asset

Để tùy chỉnh hình ảnh và video trong flow/paywall của bạn, hãy triển khai 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 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. Here’s an example of how you can provide custom assets via a simple dictionary:

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
}

Cài đặt timer tùy chỉnh do developer định nghĩa

Để sử dụng timer tùy chỉnh trong ứng dụng di động của bạn, 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ị 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().createFlowView(
    flow: flow,
    customTimers: {
      'CUSTOM_TIMER_6H': DateTime.now().add(const Duration(seconds: 3600 * 6)),
      'CUSTOM_TIMER_NY': DateTime(2027, 1, 1), // New Year 2027
    },
  );
} 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à Timer ID của các timer do developer định nghĩa mà bạn đã thiết lập 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ở flow.

Sau khi bạn đã thiết kế phần giao diện cho paywall của mình bằng Paywall Builder mới 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 được liên kết với placement và cấu hình view của nó như mô tả bên dưới.

Trước khi bắt đầu hiển thị paywall trong ứng dụng của bạn, hãy 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 đang triển khai paywall thủ công, hãy tham khảo chủ đề Lấy paywall và sản phẩm cho paywall Remote Config trong ứng dụng mobile.

Trước khi bắt đầu hiển thị paywall trong ứng dụng mobile 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ộc	Mô tả
placementId	bắ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 được kỳ vọng là mã ngôn ngữ bao gồm một hoặc hai thẻ phụ được phân tách bằng ký tự dấu trừ (-). Thẻ phụ đầu tiên là ngôn ngữ, thẻ phụ thứ hai là khu vực. Ví dụ: en nghĩa là tiếng Anh, pt-br đại diện cho 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 chúng.
fetchPolicy	mặc định: .reloadRevalidatingCacheData	Theo mặc định, SDK sẽ cố tải dữ liệu từ máy chủ và trả về dữ liệu đã lưu trong cache nế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 của bạn 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 sử dụng .returnCacheDataElseLoad để trả về dữ liệu cache nếu có. Trong trường hợp này, người dùng có thể không nhận được dữ liệu mới nhất tuyệt đối, nhưng họ sẽ có thời gian tải nhanh hơn, bất kể kết nối internet của họ có chập chờn đến đâu. Cache được cập nhật thường xuyên, vì vậy việc sử dụng trong phiên làm việc để tránh các yêu cầu mạng là hoàn toàn an toàn. Lưu ý rằng cache vẫn còn 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 dọn dẹp thủ công. Adapty SDK lưu trữ paywall cục bộ theo 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 máy chủ 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 mới nhất của paywall trong khi vẫn đảm bảo độ tin cậy ngay cả khi kết nối internet yếu.
loadTimeout	mặc định: 5 giây	Giá trị này giới hạn thời gian chờ của phương thức này. Nếu hết thời gian chờ, dữ liệu cache hoặc fallback cục bộ sẽ được trả về. 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 có thể bao gồm nhiều yêu cầu khác nhau bên dưới. Đối với Android: Bạn có thể tạo TimeInterval bằng các hàm mở rộng (như 5.seconds, trong đó .seconds là từ import com.adapty.utils.seconds), hoặc TimeInterval.seconds(5). Để không giới hạn, sử dụng TimeInterval.INFINITE.

Tham số phản hồi

Tham số	Mô tả
Paywall	Một đố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 hiển thị của paywall được thiết kế bằng Paywall Builder

Sau khi tải paywall về, hãy kiểm tra xem nó có chứa ViewConfiguration hay không — đây là dấu hiệu cho biết 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ý nó như paywall Paywall Builder; nếu không, xử lý nó như paywall Remote Config.

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.

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

Tham số	Bắt buộc	Mô tả
placementId	bắt buộc	Đị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	Đị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 thẻ con được phân tách bằng ký tự gạch nối (-). 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ã locale để biết thêm thông tin về mã locale và cách chúng tôi khuyến nghị sử dụng chúng.
fetchPolicy	mặc định: .reloadRevalidatingCacheData	Theo mặc định, SDK sẽ cố tải dữ liệu từ máy chủ và trả về dữ liệu đã cache nế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 .returnCacheDataElseLoad để trả về dữ liệu đã cache nếu có. Trong trường hợp này, 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 bất kể kết nối internet của họ kém đến đâu. Cache được cập nhật thường xuyên, vì vậy có thể dùng an toàn trong suốt phiên làm việc để tránh các yêu cầu mạng không cần thiết. Lưu ý rằng cache vẫn được giữ nguyên 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 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.

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
}

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.