Thiết lập gói cam kết 12 tháng

Để người dùng cam kết trọn một năm và thanh toán theo tháng, hãy thêm 12-month commitment plan vào sản phẩm hàng năm của bạn trong App Store Connect và trong Adapty.

Trước khi bắt đầu

Trước khi triển khai commitment plans, hãy đảm bảo rằng bạn:

• Nhắm đúng thị trường: Commitment plan không khả dụng ở Hoa Kỳ. Ở Đức, Israel, Nam Phi và Thổ Nhĩ Kỳ, người đăng ký có thể hủy ngay lập tức thông qua Apple Support.
• Nhắm đúng phiên bản hệ điều hành: Người đăng ký cần iOS 26.4 trở lên, hoặc phiên bản tương đương của iPadOS, macOS, tvOS, hoặc visionOS. Build ứng dụng của bạn bằng Xcode 26.5 trở lên.
• Nhắm đúng mức giá: Tổng giá trị 12 khoản thanh toán hàng tháng phải nằm trong khoảng từ 1x đến 1.5x giá trị của gói đăng ký hàng năm trả trước.
• Sử dụng phiên bản Adapty SDK được hỗ trợ: Flow cần Adapty SDK v4.3.1 trở lên trên iOS, v4.3 trở lên trên Android, và v4.3.0 trở lên trên React Native hoặc Flutter. Paywall tùy chỉnh cần Adapty SDK v4.3 trở lên trên iOS, React Native, hoặc Flutter: ở các phiên bản ứng dụng có SDK cũ hơn, người dùng chỉ có thể mua gói trả trước.
• Cập nhật code đọc product ID: Webhook, tích hợp, xuất dữ liệu và Server-side API báo cáo các giao dịch mua commitment plan dưới dạng <product_id>:monthly. Nếu code của bạn xử lý product ID, hãy cập nhật logic trước khi có giao dịch mua commitment plan đầu tiên.

Cấu hình App Store Connect

1. Mở một gói đăng ký hàng năm trong App Store Connect, hoặc tạo gói đăng ký mới với thời hạn 1 Year.
2. Trong phần Availability, thêm các quốc gia tương tự vào mục 1 Year Upfront và Monthly with 12-Month Commitment. Apple chỉ cung cấp hình thức thanh toán cam kết ở những nơi có hình thức thanh toán trả trước. Chiều ngược lại không bắt buộc: bạn có thể cung cấp gói trả trước ở các quốc gia không có gói cam kết.
3. Trong phần Subscription Prices, đặt giá trả trước cho vùng lãnh thổ cơ sở của bạn, nếu gói đăng ký chưa có. Apple yêu cầu giá trả trước ngay cả khi bạn chỉ hiển thị gói cam kết cho người dùng.
4. Đặt giá hàng tháng cho vùng lãnh thổ cơ sở của bạn. Giá hàng tháng phải bằng 1/12 đến 1/8 giá trả trước. Ví dụ: với giá trả trước €59.99, giá hàng tháng có thể là €5.00 đến €7.49.

App Store Connect tính giá cho các quốc gia khác dựa trên giá của lãnh thổ gốc của bạn.

Để biết hướng dẫn đầy đủ, hãy xem hướng dẫn của Apple về cách cung cấp gói đăng ký hàng tháng với cam kết 12 tháng.

2. Cấu hình Adapty

Để hiển thị commitment plan trong các flow hoặc custom paywall, hãy bật tính năng này cho sản phẩm theo năm trong Adapty. Nếu bạn không dùng flow hay custom paywall, có thể bỏ qua bước này.

1. Mở sản phẩm theo năm. Nếu sản phẩm chưa tồn tại, hãy tạo và kết nối gói đăng ký bạn đã thiết lập trong App Store Connect. Đừng tạo sản phẩm mới từ Adapty vì điều đó sẽ tạo ra một gói đăng ký riêng biệt không có commitment plan.

2. Mở tab App Store và chọn Offer monthly payments with a 12-month commitment.

   

3. Trong cửa sổ bật lên, từ danh sách Monthly price, USD, chọn mức giá trả góp khớp với App Store Connect. Danh sách chỉ chứa các mức giá App Store trong phạm vi cho phép. Giá này là giá trị tham chiếu: Adapty không gửi nó đến App Store Connect.

   

3. Thiết lập ưu đãi

Trong App Store Connect, mỗi gói thanh toán có các ưu đãi giới thiệu, ưu đãi, ưu đãi thu hút khách hàng cũ, và mã ưu đãi riêng. Ưu đãi cho gói trả trước không áp dụng cho gói cam kết.

• Dùng thử miễn phí và các ưu đãi giới thiệu khác: Trong App Store Connect, thiết lập ưu đãi cho gói cam kết. Adapty tự động áp dụng ưu đãi giới thiệu. Khi ưu đãi giới thiệu kết thúc, cam kết 12 tháng của người đăng ký bắt đầu.
• Ưu đãi và ưu đãi thu hút khách hàng cũ: Thiết lập ưu đãi hoặc ưu đãi thu hút khách hàng cũ cho gói cam kết trong App Store Connect. Sau đó thêm các ưu đãi vào Adapty và đặt App Store plan thành Monthly with 12-month commitment. Một flow hoặc sản phẩm paywall chỉ liệt kê các ưu đãi cho gói thanh toán của chính nó. Nếu bạn không sử dụng flow cũng như paywall tùy chỉnh, bạn không cần thêm các ưu đãi vào Adapty.
• Mã ưu đãi: Thiết lập mã ưu đãi cho gói cam kết trong App Store Connect.

4. Thêm vào flow hoặc paywall tùy chỉnh

Flow

1. Trong flow builder, mở panel Products và thêm sản phẩm hàng năm được gắn tag Monthly vào màn hình. Để bán thêm gói thanh toán một lần trên cùng màn hình, hãy thêm sản phẩm được gắn tag Upfront.
   • Để cung cấp ưu đãi trả trước cho những người dùng mua gói Upfront thay thế — trên phiên bản SDK cũ hơn, hoặc khi gói cam kết không áp dụng — hãy chọn gói đó trong mục Fallback offer.
2. Gán sản phẩm Monthly vào một product card hoặc một hành động Purchase.
3. Để hiển thị giá từng kỳ, chèn các biến prod_billing_price và prod_billing_period. Để hiển thị tổng giá theo năm, chèn prod_price. Các biến thanh toán theo kỳ yêu cầu Adapty SDK v4.3.1 trở lên trên iOS, hoặc v4.3.0 trở lên trên React Native hoặc Flutter.
4. Để xem trước màn hình dành cho người dùng không thể mua gói cam kết, trong panel Products, mở menu của sản phẩm Monthly và chọn Offer > Monthly plan unavailable.

Paywall tùy chỉnh

1. Trong paywall tùy chỉnh, thêm sản phẩm hàng năm và đặt Billing plan thành Monthly. Để bán thêm gói thanh toán trước trên cùng paywall đó, hãy thêm lại sản phẩm hàng năm với Billing plan là Upfront.
   • Để cung cấp ưu đãi trả trước cho người dùng mua gói Upfront thay thế — trên phiên bản SDK cũ hơn, hoặc khi gói cam kết không áp dụng — hãy chọn ưu đãi đó trong Fallback offer.
2. Trong ứng dụng, hiển thị giá từ product.subscriptionPricingTerms. Với người dùng có thể mua gói cam kết, Adapty SDK trả về thông tin giá của gói đó. Với những người dùng còn lại, SDK trả về thông tin giá của gói Upfront:
   • Để biết SDK đã trả về gói nào, kiểm tra product.subscriptionPricingTerms?.billingPlan. Giá trị là .monthly cho gói cam kết và .upFront cho gói Upfront.
   • Để hiển thị giá theo kỳ, dùng subscriptionPricingTerms.localizedBillingPrice và subscriptionPricingTerms.billingPeriod.
   • Để hiển thị tổng giá theo năm, dùng subscriptionPricingTerms.commitmentInfo.localizedPrice và subscriptionPricingTerms.commitmentInfo.period. Với gói cam kết, product.localizedPrice và product.subscriptionPeriod cũng trả về các giá trị theo năm tương tự.
   • Trong React Native, đọc thông tin giá từ product.subscription?.ios?.pricingTerms. Giá trị billingPlan là 'monthly' cho gói cam kết và 'up_front' cho gói Upfront. Để hiển thị giá theo kỳ, dùng billingPrice.localizedString và billingPeriod. Để hiển thị tổng theo năm, dùng commitmentInfo.price.localizedString và commitmentInfo.period.
   • Trong Flutter, đọc thông tin giá từ product.subscription?.pricingTerms. Giá trị billingPlan là AdaptySubscriptionBillingPlan.monthly cho gói cam kết và AdaptySubscriptionBillingPlan.upFront cho gói Upfront. Để hiển thị giá theo kỳ, dùng billingPrice.localizedString và billingPeriod. Để hiển thị tổng theo năm, dùng commitmentInfo.price.localizedString và commitmentInfo.period.

Người dùng không thể mua gói cam kết trong các trường hợp sau:

• Phiên bản hệ điều hành hoặc quốc gia không được hỗ trợ: Thiết bị Apple của người dùng chạy phiên bản hệ thống thấp hơn 26.4, hoặc gói không khả dụng tại quốc gia App Store của họ. Adapty SDK sẽ trả về giá của gói trả trước thay thế.
• Đã có gói đăng ký trả trước: StoreKit báo cáo rằng người dùng đã đăng ký. Để chuyển gói, người đăng ký sử dụng cài đặt gói đăng ký Apple của họ.
• In-app purchase được quảng bá: Người dùng chọn sản phẩm trong App Store, sau đó Adapty SDK bắt đầu quá trình mua trong ứng dụng của bạn. Đối với các giao dịch mua này, SDK chỉ hỗ trợ gói trả trước.

Để ngừng cung cấp gói cam kết, trong các flow của bạn, hãy thay thế hoặc xóa sản phẩm Monthly. Trong các paywall tùy chỉnh, đặt Billing plan của sản phẩm yearly thành Upfront, hoặc xóa hàng Monthly. Bạn không thể bỏ chọn hộp kiểm Offer monthly payments with a 12-month commitment trong Adapty. Những người đăng ký hiện tại vẫn sẽ gia hạn sang một cam kết mới mỗi năm, trừ khi bạn nhấp vào Remove Monthly Billing cho gói đăng ký yearly trong App Store Connect. Những người đăng ký đã cam kết sẽ tiếp tục thanh toán cho đến khi cam kết của họ kết thúc.

5. Kiểm tra kế hoạch trong sandbox

Làm theo hướng dẫn kiểm tra sandbox với hai tài khoản sandbox:

• Một tài khoản từ quốc gia có cung cấp gói thanh toán theo kỳ: Paywall sẽ hiển thị gói thanh toán theo kỳ với giá hàng tháng cùng tổng giá. Sau khi mua, hồ sơ người dùng sandbox sẽ có mức độ truy cập của sản phẩm theo năm.
• Một tài khoản Mỹ: Paywall chỉ hiển thị gói thanh toán trả trước.

Nếu code của bạn xử lý product ID từ webhook hoặc Server-side API, hãy xác minh rằng nó nhận các giao dịch mua commitment-plan dưới dạng <product_id>:monthly.

Để kiểm tra logic mua hàng cục bộ, hãy sử dụng StoreKit Testing trong Xcode 26.5 hoặc mới hơn. Các giao dịch mua trong StoreKit Testing không được gửi tới Adapty.

Hiển thị tiến trình cam kết trong ứng dụng

Để hiển thị cho người đăng ký biết họ đã đi được bao xa trong cam kết của mình, hãy đọc mức độ truy cập từ hồ sơ người dùng. Các thuộc tính billingPlan và commitmentInfo của nó yêu cầu Adapty SDK v4.3 trở lên trên iOS, hoặc v4.3.0 trở lên trên React Native hoặc Flutter.

• Để xác định liệu người dùng có đang trong gói cam kết hay không, hãy so sánh billingPlan với giá trị monthly. Không cần kiểm tra xem thuộc tính có được đặt hay không: nó cũng có thể chứa giá trị upfront.
• Để hiển thị tiến trình, sử dụng commitmentInfo.billingPeriodNumber cho lần thanh toán hiện tại và commitmentInfo.totalBillingPeriods cho tổng số lần thanh toán.
• Để hiển thị thời điểm cam kết kết thúc, sử dụng commitmentInfo.expiresAt, không phải thuộc tính expiresAt của mức độ truy cập.

let profile = try await Adapty.getProfile()

if let premium = profile.accessLevels["premium"],
   premium.billingPlan == .monthly,
   let commitment = premium.commitmentInfo {
    // e.g. "Payment 3 of 12, commitment ends on <commitment.expiresAt>"
}

const profile = await adapty.getProfile();
const premium = profile.accessLevels?.['premium'];

if (premium?.billingPlan === SubscriptionBillingPlan.Monthly && premium.commitmentInfo) {
  const { billingPeriodNumber, totalBillingPeriods, expiresAt } = premium.commitmentInfo;
  // e.g. "Payment 3 of 12, commitment ends on <expiresAt>"
}

final profile = await Adapty().getProfile();
final premium = profile.accessLevels['premium'];
final commitment = premium?.commitmentInfo;

if (premium?.billingPlan == AdaptySubscriptionBillingPlan.monthly && commitment != null) {
  // e.g. "Payment ${commitment.billingPeriodNumber} of ${commitment.totalBillingPeriods},
  // commitment ends on ${commitment.expiresAt}"
}

Khắc phục sự cố

• Hộp kiểm cho thanh toán hàng tháng bị thiếu: Hộp kiểm Offer monthly payments with a 12-month commitment chỉ xuất hiện trên sản phẩm Annual có App Store product ID. Nó sẽ không hoạt động cho đến khi sản phẩm có Price (USD).
• Người dùng không thấy dùng thử miễn phí hoặc ưu đãi khác cho gói cam kết: Trong App Store Connect, mỗi ưu đãi thuộc về một gói thanh toán. Thiết lập ưu đãi cho gói cam kết. Với ưu đãi hoặc ưu đãi thu hút khách hàng cũ, hãy đặt App Store plan của ưu đãi trong Adapty thành Monthly with 12-month commitment.
• Mọi người dùng đều thấy giá trả trước: Kiểm tra cả hai điều sau:
  • Ứng dụng được build bằng Xcode 26.5 trở lên. Với phiên bản Xcode cũ hơn, Adapty SDK luôn trả về giá của gói trả trước.
  • Trong flow, màn hình sử dụng sản phẩm hàng năm được gắn thẻ Monthly. Trong custom paywall, Billing plan của sản phẩm hàng năm là Monthly.
• Một số người dùng thấy giá trả trước: Những người dùng đó không thể mua gói cam kết.
• Paywall hiển thị tổng giá theo năm thay vì giá trả góp:
  • Trong flow, prod_price trả về tổng giá theo năm. Để hiển thị giá trả góp, hãy dùng prod_billing_price. Trên Adapty iOS SDK v4.3.0, prod_billing_price cũng hiển thị tổng giá theo năm: hãy cập nhật SDK lên v4.3.1 trở lên.
  • Trong custom paywall, product.localizedPrice trả về tổng giá theo năm. Để hiển thị giá trả góp, hãy dùng subscriptionPricingTerms.localizedBillingPrice. Trong React Native, dùng product.subscription?.ios?.pricingTerms?.billingPrice.localizedString. Trong Flutter, dùng product.subscription?.pricingTerms?.billingPrice.localizedString.