Retention Messaging API: thông điệp trước khi hủy gói

Retention Messaging API là một dịch vụ server-to-server của Apple. Nó hiển thị thông điệp của bạn cho người đăng ký ngay lúc họ chạm Cancel Subscription. Thông điệp xuất hiện trên một trang xác nhận, trước khi việc hủy được xác nhận. Thông điệp có thể nhắc lại giá trị gói đăng ký của bạn, đề xuất một gói khác hoặc một ưu đãi khuyến mãi, nhưng nút hủy gói luôn vẫn ở đó. API đang ở dạng bản xem trước từ tháng 7/2025, phải xin quyền truy cập. Apple đã công bố một phiên bản đơn giản hơn trong App Store Connect cho mùa thu 2026.

Hướng dẫn này giải thích API hiển thị gì, có từ khi nào, ai dùng được, các điều kiện và cách cài đặt. Mọi thông tin đều lấy từ tài liệu của Apple và phiên WWDC26 dành riêng cho nó, mình đọc lại ngày 3/11/2026.

Mình bán gói đăng ký trong các app iOS của mình: Solys, một app chặn mạng xã hội, TradaZen, một app mô phỏng trading, Nolera, một app thử đồ bằng AI, và Vigie. Mình đã xin quyền truy cập API cho cả bốn app ngày 25/10/2026, và soạn sẵn thông điệp bằng tất cả ngôn ngữ của chúng. Đến ngày 28/10, Apple vẫn chưa chấp thuận: vì vậy hướng dẫn này mô tả quy định và phần chuẩn bị của mình, chưa phải kết quả.

Retention Messaging API làm gì

Theo tài liệu của Apple, API cho bạn chọn thông điệp mà hệ thống hiển thị khi khách hàng xem trang chi tiết của một gói đăng ký và có thể sắp hủy. Bạn soạn sẵn thông điệp, cho từng sản phẩm và từng ngôn ngữ.

Luồng luôn giống nhau:

1. Người đăng ký mở gói của họ, ví dụ trong Apple Account, Subscriptions, hoặc từ App Store.
2. Họ chạm Cancel Subscription.
3. Hệ thống hiển thị một trang xác nhận (Confirm Cancellation), kèm thông điệp của bạn.
4. Họ vẫn có thể hủy, giữ gói, hoặc nhận đề xuất trong thông điệp của bạn.

Thông điệp hiển thị trên iOS 15.1 và iPadOS 15.1 trở lên, trên visionOS 1 và trên macOS 14 trở lên.

Có từ khi nào, và dành cho ai

Ngày	Thay đổi, theo Apple
16/7/2025	Phiên bản 1.0: bản xem trước đầu tiên của API
9/12/2025	Bài kiểm tra hiệu năng server cho chế độ thời gian thực
31/3/2026	Gạch đầu dòng trong thông điệp, cấu hình địa chỉ thời gian thực qua API
27/4/2026	Hỗ trợ gói hằng tháng có cam kết 12 tháng
Tháng 6/2026	WWDC26: công bố một mô-đun trong App Store Connect

Các ngày lấy từ nhật ký phiên bản của API, trừ dòng cuối lấy từ phiên WWDC26. API vẫn là bản xem trước: tài liệu dẫn tới một biểu mẫu xin quyền truy cập, yêu cầu đăng nhập tài khoản developer của bạn.

Tại WWDC26, phiên Explore Retention Messaging in App Store Connect giới thiệu một mô-đun cấu hình không cần code, ngay trong App Store Connect. Apple nói nó "mở cho tất cả". Còn phiên bản thời gian thực thì vẫn phải xin quyền. Trang tính năng mới của App Store công bố mô-đun cho "mùa thu này". Tính đến 3/11/2026, phần trợ giúp của App Store Connect vẫn chưa có trang nào về nó, và mô-đun chưa xuất hiện trong tài khoản của mình ngày 28/10.

API dành cho các app bán gói đăng ký tự động gia hạn. Nó không chỉ dành cho nhà phát hành lớn: RevenueCat ghi nhận trong nghiên cứu trên 22 triệu thông điệp rằng app nhỏ cũng có thể xin quyền truy cập.

4 loại thông điệp

Loại	Người đăng ký thấy gì	Thông điệp mặc định	Thời gian thực
Văn bản	Một tiêu đề, một đoạn văn, tối đa năm gạch đầu dòng	Có	Có
Văn bản kèm ảnh	Giống trên, kèm một hình ảnh	Có	Có
Đổi gói	Một đoạn văn và một gói khác trong cùng nhóm	Không	Có
Ưu đãi khuyến mãi	Một đoạn văn và một ưu đãi để tiếp tục với giá giảm	Không	Có

Theo trang về chuẩn bị thông điệp, thông điệp mặc định chỉ có thể là văn bản, có hoặc không có ảnh. Với API, muốn đề xuất ưu đãi hay gói khác thì phải phản hồi theo thời gian thực. Còn mô-đun được công bố trong App Store Connect sẽ cho phép thông điệp kèm ưu đãi mà không cần server.

Ưu đãi khuyến mãi là ưu đãi bạn tạo trong App Store Connect. Theo trợ giúp về ưu đãi khuyến mãi, nó nhắm tới người đăng ký hiện tại và cũ. Trong thông điệp giữ chân, chính server của bạn ký ưu đãi này, theo trang về chuẩn bị thông điệp. Đổi gói thì đề xuất một gói trong cùng nhóm. Nếu bạn mới làm quen với các ưu đãi này, hãy đọc trước hướng dẫn của mình về mã ưu đãi và ưu đãi khuyến mãi.

Bạn được hiển thị gì: giới hạn chính xác

Thành phần	Giới hạn của Apple
Tiêu đề	Tối đa 66 ký tự
Văn bản	Tối đa 144 ký tự
Gạch đầu dòng	Tối đa 5
Ảnh toàn chiều rộng	PNG không trong suốt, rộng 3.840 px, cao từ 160 đến 2.160
Ảnh gạch đầu dòng	1.024 × 1.024 px
Số ảnh mỗi app	Tối đa 2.000

Độ dài lấy từ mô tả body của request gửi thông điệp, còn định dạng lấy từ trang về gửi ảnh. Apple cũng yêu cầu ảnh hiển thị tốt ở cả chế độ sáng lẫn tối.

Mỗi thông điệp và mỗi ảnh đều được Apple duyệt. Trạng thái chuyển từ PENDING sang APPROVED, và hệ thống chỉ hiển thị nội dung đã được duyệt. Trong sandbox, việc duyệt là tự động. Tài liệu đặt ra một quy tắc nội dung rõ ràng: không gửi gì gây hiểu lầm hay sai sự thật.

Các điều kiện cần đáp ứng

• Một thông điệp mặc định cho mỗi sản phẩm, ở mỗi ngôn ngữ. Không có nó, sẽ không có gì hiển thị ở ngôn ngữ đó. Đây cũng là phương án dự phòng nếu server của bạn không phản hồi.
• Thông điệp và ảnh đã được duyệt trước khi đưa lên production.
• Với thời gian thực, cần một server nhanh. Trang về cài đặt địa chỉ thời gian thực yêu cầu chứng chỉ SSL hợp lệ, TLS 1.2 và phản hồi dưới 700 ms ở production. Quá thời gian đó, request thất bại và thông điệp mặc định được hiển thị.
• Vượt qua bài kiểm tra hiệu năng trong sandbox, trước khi khai báo địa chỉ production.
• Kiểm tra app. Mỗi request của Apple chứa mã định danh app, appAppleId. Nếu nó không khớp với app của bạn, Apple yêu cầu không phản hồi.

Request thời gian thực cung cấp cho bạn mã giao dịch gốc, sản phẩm và ngôn ngữ của thiết bị. Việc chọn thông điệp là của bạn, theo quy tắc của bạn.

Cài đặt Retention Messaging: ba cách

Cách	Dành cho ai	Cần gì
Mô-đun App Store Connect	Tất cả mọi người, khi đã ra mắt	Không cần code; văn bản, ảnh hoặc ưu đãi
API, với server của bạn	Ai đã có back-end	Quyền của Apple, địa chỉ HTTPS, bài kiểm tra hiệu năng
API, qua RevenueCat	App đã dùng RevenueCat	Quyền của Apple, cấu hình trong dashboard

Khi nhiều cấu hình cùng tồn tại, Apple giải thích trong phiên WWDC26 thứ tự áp dụng: phản hồi thời gian thực trước. Nếu thiếu hoặc sai định dạng, dùng cấu hình trong App Store Connect. Nếu không có, dùng thông điệp mặc định cấu hình qua API.

Với server của riêng bạn

1. Xin quyền truy cập bằng biểu mẫu của Apple.
2. Gửi ảnh, rồi gửi thông điệp, mỗi thông điệp có một tiêu đề và một đoạn văn.
3. Chờ duyệt, rồi khai báo một thông điệp mặc định cho mỗi gói và mỗi ngôn ngữ.
4. Với thời gian thực, tạo địa chỉ Get Retention Message trên server và khai báo nó trong sandbox.
5. Chạy bài kiểm tra hiệu năng trong sandbox, với một giao dịch thử.
6. Khi bài kiểm tra đạt, khai báo địa chỉ production.

Với RevenueCat

Đây là cách mình chọn: không phải viết server, và các app của mình vốn đã dùng RevenueCat, như mình giải thích trong RevenueCat và gói đăng ký in-app iOS. Theo tài liệu của RevenueCat:

1. Trong biểu mẫu của Apple, địa chỉ cần điền là địa chỉ RevenueCat hiển thị trong phần cấu hình app App Store của bạn.
2. Sau khi được chấp thuận, mở Lifecycle, rồi Retention, và kết nối địa chỉ sandbox.
3. Chạy bài kiểm tra hiệu năng với một gói sandbox hoặc TestFlight đang hoạt động. Nó có thể kéo dài tới một giờ.
4. Tạo thông điệp mặc định trước, từng ngôn ngữ một.
5. Sau đó thêm thông điệp thời gian thực, kèm quy tắc. Một trong số đó, "Is in free trial", nhắm tới người đang dùng thử miễn phí.
6. Chuyển sang production: cấu hình sandbox không được giữ lại, phải tạo lại thông điệp.

Viết thông điệp giữ chân mà không gài bẫy

Văn bản là cố định và được Apple duyệt trước khi hiển thị. Vì vậy nó không thể nói về người đang đọc, hay về ngày họ đọc. Đây là thông điệp mặc định mình soạn cho TradaZen, bằng tiếng Pháp:

Tiêu đề (57 ký tự):
Tu voulais apprendre à trader, et tu repars à l'aveugle ?

Văn bản (127 ký tự):
Sans entraînement, ton vrai argent paie chaque erreur. Ici, elles ne coûtent rien. Ta série, ta ligue et tes leçons s'arrêtent.

Các quy tắc mình tự đặt cho bốn app:

• Tiêu đề đưa người đọc về lại mục tiêu của họ, dưới dạng câu hỏi. Nó không làm họ xấu hổ.
• Văn bản nói chính xác cái gì sẽ dừng lại. Mình viết quyền truy cập "bị khóa" khi dữ liệu vẫn còn, không bao giờ nói dữ liệu sẽ "bị xóa".
• Không dùng từ chỉ thời gian như "ngày mai" hay "hôm nay": cùng một văn bản hiển thị vào bất kỳ thời điểm nào trong kỳ.
• Không hứa hẹn lợi nhuận, không tạo cảm giác gấp gáp giả. Một tiêu đề đầu tiên hứa thay đổi cuộc đời nhờ trading đã bị loại trước khi gửi. Guideline 5.6 cấm mọi hành vi thao túng, và paywall của TradaZen từng bị từ chối vì lý do này, như mình kể trong guideline 5.6 và paywall.
• Mỗi ngôn ngữ có văn bản riêng, dùng từ vựng của bản app đã dịch, và đếm chính xác từng ký tự.

Với TradaZen, mình cũng định làm một thông điệp thời gian thực cho người đang dùng thử gói năm. Nó sẽ đề xuất một gói năm rẻ hơn trong cùng nhóm, vì số liệu của mình cho thấy những người này dùng app nhiều không kém người trả tiền: thứ họ từ chối là giá. Cấu hình này đang chờ Apple chấp thuận.

Có thể kỳ vọng gì

Đừng trông chờ phép màu. Apple gọi tỷ lệ cứu vãn là tỷ lệ người đăng ký giữ lại gói sau khi đã tới trang xác nhận. Trong phiên WWDC26, Apple cho biết các gói đã áp dụng Retention Messaging tăng trung bình 1,4 điểm tỷ lệ này. Thông điệp kèm ưu đãi khuyến mãi đạt mức tăng cao nhất được ghi nhận, 5,5 điểm, và kết quả khác nhau tùy developer. Về phía mình, nghiên cứu của RevenueCat ghi nhận người đăng ký chỉ chấp nhận khoảng 1,1% ưu đãi khuyến mãi và 0,6% đề xuất đổi gói.

Nên thông điệp không thay thế được công việc từ trước. Một bản dùng thử bị hủy ngay trong phút đầu được quyết định ở paywall và những phiên dùng đầu tiên: nguyên nhân và đòn bẩy có trong hướng dẫn của mình về dùng thử miễn phí bị hủy, còn cách tạo bản dùng thử nằm trong bài ưu đãi giới thiệu.

Chuẩn bị gói đăng ký trước khi viết thông điệp

iOS & Android Kit xuất phát từ code khởi đầu của các app của mình: onboarding, paywall và gói đăng ký đã được code sẵn, và lộ trình bốn bước đưa bạn tới tận App Store, theo nhịp của bạn. Toàn bộ chuỗi, từ sản phẩm trong App Store Connect đến paywall, được mô tả ở trang gói đăng ký in-app iOS.

Nếu bạn đang chuẩn bị ra mắt lần đầu, làm bài chẩn đoán miễn phí: nó cho bạn biết điều gì thực sự đang chặn dự án và gửi bạn checklist chống bị Apple từ chối của mình.

Câu hỏi thường gặp

Retention Messaging API của Apple là gì?

Đó là một dịch vụ server-to-server chọn thông điệp hiển thị cho người đăng ký khi họ chạm Cancel Subscription. Thông điệp xuất hiện trên một trang xác nhận, trước khi hủy. Nó có thể nhắc lại giá trị của gói, đề xuất một gói khác hoặc một ưu đãi khuyến mãi.

Retention Messaging có dành cho mọi developer không?

API là bản xem trước, phải xin quyền truy cập từ Apple. Tại WWDC26, Apple công bố một mô-đun trong App Store Connect, mở cho tất cả, dự kiến vào mùa thu 2026. Tính đến 3/11/2026, phần trợ giúp của App Store Connect vẫn chưa mô tả nó.

Thông điệp hiển thị trên những phiên bản iOS nào?

Trên iOS 15.1 và iPadOS 15.1 trở lên, trên visionOS 1 và trên macOS 14 trở lên. Trên thiết bị cũ hơn, việc hủy diễn ra mà không có thông điệp.

Thông điệp có ngăn người đăng ký hủy gói không?

Không. Trang xác nhận vẫn giữ nút hủy. Người đăng ký cũng có thể giữ gói, hoặc nhận ưu đãi hay gói được đề xuất.

Có thể đề xuất giảm giá lúc người dùng hủy không?

Có. Với API, đó là thông điệp ưu đãi khuyến mãi, chỉ ở chế độ thời gian thực: ưu đãi được tạo trong App Store Connect và được server của bạn ký. Mô-đun được công bố trong App Store Connect cũng cho phép thông điệp kèm ưu đãi. Còn đổi gói thì đề xuất một gói khác trong cùng nhóm.

Thông điệp giữ chân được bao nhiêu ký tự?

Tiêu đề tối đa 66 ký tự, văn bản tối đa 144. Bạn có thể thêm tối đa năm gạch đầu dòng và một ảnh PNG không trong suốt. Mỗi ngôn ngữ cần thông điệp mặc định riêng.

Có cần server để dùng Retention Messaging không?

Với thông điệp mặc định thì không cần host địa chỉ nào: chỉ cần gọi API để gửi và khai báo chúng. Với RevenueCat, chính RevenueCat đóng vai server. Chế độ thời gian thực cần một địa chỉ HTTPS phản hồi dưới 700 ms. Mô-đun được công bố trong App Store Connect thì cấu hình không cần code.