Hiểu CONSUMPTION_REQUEST là gì chỉ mất chừng một đoạn văn. Xây dựng một thứ xử lý nó một cách đáng tin cậy thì tốn nhiều hơn thế, và những phần khiến người ta vấp ngã không phải là những phần bạn nghĩ tới.
Xác minh chữ ký là một. Consent (sự đồng ý của khách hàng) là một phần khác, vì nó phải tồn tại từ trước khi thông báo đến. Và lịch thử lại (retry) tương tác với khung thời gian phản hồi theo cách khiến hầu hết các team bất ngờ khi lần đầu xem xét kỹ.
Bài viết này đi qua toàn bộ handler, từ thời điểm yêu cầu chạm tới endpoint của bạn cho đến bước cập nhật entitlement khép lại quy trình.
Những điểm chính
• CONSUMPTION_REQUEST yêu cầu thông tin trong quá trình xem xét hoàn tiền. Apple vẫn là bên đưa ra quyết định.
• Xác minh payload đã ký trước khi hành động dựa trên nó. Không bao giờ tin một thông báo chưa được xác minh.
• Consent phải đã tồn tại sẵn trong ứng dụng của bạn. Bạn không thể thu thập nó sau khi yêu cầu đến.
• Apple yêu cầu phản hồi trong vòng 12 giờ kể từ khi có thông báo.
• Apple thử gửi lại các lần gửi thất bại theo lịch cố định, và lần thử lại thứ hai rơi vào sau khi khung thời gian phản hồi đã đóng.
• Theo dõi kết quả và cập nhật entitlement sau đó. Phản hồi không phải là bước cuối cùng.
Thông báo CONSUMPTION_REQUEST của Apple là gì?
Thông báo CONSUMPTION_REQUEST của Apple là một App Store Server Notification cho server của bạn biết rằng một khách hàng đã yêu cầu hoàn tiền và Apple đang mời bạn gửi thông tin mức sử dụng (consumption) về giao dịch mua đó. Nó được gửi đến URL thông báo bạn đã cấu hình, mang theo giao dịch liên quan, và cho bạn một khoảng thời gian giới hạn để trả lời.
Đây không phải là một khoản hoàn tiền và cũng không phải là quyết định. Apple đang ở giữa quá trình xem xét và thu thập bối cảnh. Vai trò của bạn là cung cấp thông tin chính xác về những gì đã xảy ra với giao dịch mua; vai trò của Apple là quyết định.
Vì sao Apple gửi CONSUMPTION_REQUEST?
Vì Apple không thể nhìn thấy bên trong ứng dụng của bạn. Apple biết giao dịch, tài khoản và lịch sử mua hàng. Apple không biết nội dung đã được giao hay chưa, có hoạt động không, hay khách hàng đã dùng bao nhiêu.
Thông tin consumption lấp đầy khoảng trống đó. Đây là một trong nhiều yếu tố Apple cân nhắc, không phải yếu tố quyết định, và con số mức sử dụng cao không phải là công tắc từ chối. Hãy xem nó là bối cảnh bạn đóng góp chứ không phải một vụ việc bạn đang tranh luận.
Developer nên làm gì khi nhận được CONSUMPTION_REQUEST?
Xác thực thông báo, xác định giao dịch và khách hàng, xác nhận consent, tập hợp dữ liệu consumption chính xác, gửi trong khung thời gian của Apple, rồi ghi lại những gì đã xảy ra.
Mười bước trong thực tế:
1. Nhận thông báo tại endpoint server đã cấu hình và lưu lại ngay lập tức.
2. Xác minh payload đã ký trước khi coi bất kỳ trường nào là thật.
3. Đọc loại thông báo và định tuyến nó. Một yêu cầu consumption không phải là kết quả hoàn tiền.
4. Xác định giao dịch liên quan từ payload đã giải mã.
5. Ánh xạ giao dịch tới một tài khoản khách hàng trong hệ thống của riêng bạn.
6. Kiểm tra xem consent của khách hàng đó có cho phép phản hồi hay không.
7. Thu thập dữ liệu giao hàng và mức sử dụng từ hồ sơ của bạn, không phải từ ước tính.
8. Chuẩn bị phản hồi và đối chiếu với các quy tắc kiểm tra trường dữ liệu.
9. Gửi tới endpoint consumption của Apple và ghi nhận kết quả.
10. Theo dõi kết quả hoàn tiền tiếp theo, rồi cập nhật entitlement và hồ sơ.
Developer nên xác thực CONSUMPTION_REQUEST như thế nào?
Xác minh chữ ký trước khi tin vào nội dung. Thông báo đến dưới dạng payload JWS đã ký, được mô tả trong tài liệu Apple App Store Server Notifications, và handler của bạn nên kiểm tra chúng với chuỗi chứng chỉ của Apple và xác nhận bundle ID khớp với ứng dụng của bạn.
Lý do rất đơn giản. URL thông báo của bạn là một endpoint công khai. Một triển khai phân tích bất cứ thứ gì gửi đến và hành động theo nó là thứ mà bất kỳ ai tìm thấy URL đều có thể điều khiển.
Ba chi tiết của handler quan trọng không kém chữ ký:
Trả về đúng mã trạng thái. Apple coi HTTP 200 đến 206 là thành công. Mã 40x hoặc 50x báo cho App Store thử lại. Hãy trả về thành công khi bạn đã lưu thông báo, chứ không phải khi bạn đã xử lý xong — đó là hai thời điểm khác nhau, và gộp chúng lại có nghĩa là một tác vụ downstream chậm có thể kích hoạt những lần thử lại không cần thiết.
Xử lý trùng lặp. Thử lại đồng nghĩa với việc cùng một thông báo có thể đến nhiều lần, và mỗi thông báo mang một notification UUID mà bạn có thể dùng để khử trùng lặp. Hãy xác nhận các bản lặp thay vì trả lỗi; một phản hồi thất bại chỉ khởi động lại chu kỳ thử lại.
Nhớ rằng sandbox hoạt động khác. Thử lại chỉ áp dụng trong production. Trong sandbox, App Store chỉ thử gửi một lần, nên một handler trông ổn khi test vẫn có thể đang mất sự kiện trong production, và điều ngược lại cũng đúng.
Developer nên kiểm tra gì trước khi phản hồi?
Bốn điều, theo thứ tự này.
Consent trước tiên, vì đó là thứ có thể chặn đứng mọi thứ. Apple yêu cầu consent hợp lệ của khách hàng trước khi bạn chia sẻ dữ liệu của họ, việc thu thập consent là trách nhiệm của bạn chứ không phải của Apple, và bản thân thông báo không mang theo cờ consent nào. Apple cũng nói rõ rằng lời nhắc App Tracking Transparency không phải là cơ chế ở đây. Nếu không có consent, hướng dẫn là không phản hồi.
Thứ hai là danh tính giao dịch. Bạn cần biết đây là giao dịch mua nào và tài khoản nào đứng sau nó. Việc ánh xạ đó chính là nội dung của bài appAccountToken và phòng vệ hoàn tiền Apple — không có liên kết ổn định từ giao dịch tới tài khoản, bạn sẽ phải suy đoán dưới áp lực thời hạn.
Thứ ba là loại sản phẩm, vì nó ảnh hưởng tới những tùy chọn có sẵn cho bạn. Và cuối cùng, liệu bạn có thực sự nắm giữ dữ liệu dùng được hay không. Nếu hệ thống của bạn không thể nói nội dung đã được giao hay chưa, đó là điều đáng biết trước khi bắt tay vào soạn phản hồi.
Developer có thể gửi thông tin consumption nào cho Apple?
Phiên bản hiện hành của tài liệu Send Consumption Information của Apple định nghĩa năm trường. Ba trường bắt buộc và hai trường tùy chọn.
Trường | Bắt buộc | Nói đơn giản |
customerConsented | Có | Khách hàng có đồng ý không? Phải là true, nếu không yêu cầu sẽ bị từ chối. |
deliveryStatus | Có | Ứng dụng của bạn có thực sự giao một giao dịch mua hoạt động được không, và nếu không thì vì sao? |
sampleContentProvided | Có | Khách hàng có thể dùng thử trước khi mua không? |
consumptionPercentage | Không | Họ đã dùng bao nhiêu? Tính bằng milliunit — một nửa là 50000, không phải 50. |
refundPreference | Không | Bạn muốn gì: hoàn toàn bộ, từ chối, hay hoàn theo tỷ lệ. |
Hai quy tắc khiến nhiều người vấp. Nếu delivery status là bất cứ giá trị nào khác ngoài delivered, consumption percentage phải bằng không. Và refund preference là mong muốn, không phải chỉ thị; Apple có thể và thực tế vẫn quyết định khác.
Đáng kiểm tra xem bạn đang dùng endpoint nào. Apple cũng có tài liệu ConsumptionRequestV1 của Apple, phiên bản trước với body mười hai trường mà hầu hết các bài viết bên thứ ba vẫn mô tả. Ghi chú của Apple ở đó hướng các In-App Purchase tiêu chuẩn tới endpoint hiện hành và giới hạn V1 cho các giao dịch mua qua Advanced Commerce API. Nếu tích hợp của bạn có từ trước thay đổi này, đó là điều đầu tiên cần xem.
Developer có bao lâu để phản hồi CONSUMPTION_REQUEST?
Tài liệu hiện hành của Apple yêu cầu phản hồi trong vòng 12 giờ kể từ khi có thông báo.
Đây là phần đáng chú ý. Apple thử gửi lại các lần gửi thất bại năm lần, ở các mốc 1, 12, 24, 48 và 72 giờ sau lần thử trước. Đặt cạnh khung 12 giờ thì phép tính khá khó chịu: nếu endpoint của bạn bỏ lỡ lần gửi đầu tiên, lần thử lại đầu tiên đến một giờ sau và bạn vẫn ổn. Nếu bỏ lỡ cả lần đó, lần thử tiếp theo rơi vào khoảng mười ba giờ sau — khi khung thời gian đã đóng.
Vì vậy độ tin cậy của endpoint ở đây không phải là chuyện vệ sinh hệ thống chung chung. Riêng với các yêu cầu consumption, khoảng một giờ downtime là có thể cứu vãn còn nửa ngày thì không.
Apple không nói rằng bỏ lỡ khung thời gian đồng nghĩa với việc hoàn tiền được tự động chấp thuận, và khẳng định như vậy là sai. Điều đó chỉ đơn giản có nghĩa là Apple quyết định mà không có thông tin bạn lẽ ra có thể cung cấp.
Điều gì xảy ra sau khi developer phản hồi?
Apple đưa thông tin của bạn vào quá trình xem xét, cân nhắc cùng mọi thứ khác, và quyết định. Kết quả đến dưới dạng một thông báo riêng: được chấp thuận, bị từ chối, hoặc bị đảo ngược nếu sau đó Apple hủy một khoản hoàn tiền đã chấp thuận.
Có ba việc riêng biệt đang diễn ra ở đây và nên tách bạch chúng. Phản hồi của bạn là thông tin. Quyết định của Apple là quyết định. Cập nhật hệ thống của bạn là thay đổi trạng thái. Chỉ việc ở giữa thuộc về Apple, và việc thứ ba sẽ không xảy ra trừ khi bạn xây dựng nó.
Cách developer xử lý hoàn tiền Apple sau khi phản hồi
Khi kết quả đến, công việc quay trở lại phía bạn.
Ghi nhận kết quả vào giao dịch và khách hàng. Cập nhật trạng thái subscription, vì một kỳ đã hoàn tiền thường kết thúc subscription chứ không để nó tiếp tục chạy. Thu hồi entitlement khi hoàn tiền được chấp thuận, khôi phục khi bị đảo ngược, và xử lý trường hợp hoàn theo tỷ lệ khi chỉ một phần giao dịch bị thu hồi.
Sau đó đối soát số tiền vào đúng kỳ báo cáo và lưu khoản hoàn tiền trong một lịch sử có thể truy vấn. Lịch sử đó là thứ sau này cho bạn biết liệu một sản phẩm hay mức giá nào đó có đang chiếm tỷ lệ hoàn tiền bất thường hay không, và cũng là thứ bộ phận hỗ trợ cần khi khách hàng hỏi chuyện gì đã xảy ra với quyền truy cập của họ.
Những sai lầm phổ biến khi xử lý CONSUMPTION_REQUEST là gì?
Những lỗi lặp đi lặp lại:
• Coi thông báo là hoàn tiền và thu hồi quyền truy cập ngay lập tức. Chưa có gì được quyết định cả.
• Bỏ qua xác minh chữ ký vì payload trông ổn khi test.
• Phát hiện ra không có luồng consent đúng lúc phải gửi phản hồi.
• Gửi con số consumption ước tính thay vì số thật.
• Bắn yêu cầu đi và không bao giờ kiểm tra xem nó có thành công không. Một lần gửi thất bại sau đó trông y hệt một lần gửi thành công.
• Nhầm lẫn hủy đăng ký với hoàn tiền. Đó là hai sự kiện khác nhau với tác động khác nhau lên quyền truy cập.
• Xử lý kết quả chấp thuận và từ chối nhưng quên trường hợp đảo ngược, khiến khách hàng đang trả tiền bị khóa ngoài.
• Trông chờ ai đó để ý thấy thông báo một cách thủ công, trong khi đồng hồ 12 giờ đang chạy.
Có thể tự động hóa việc xử lý CONSUMPTION_REQUEST không?
Có, và gần như toàn bộ nên được tự động hóa, vì hầu hết mọi bước đều mang tính xác định.
Tự động hóa bao gồm giám sát và xác thực thông báo, tra cứu giao dịch, kiểm tra consent, chuẩn bị dữ liệu consumption, gửi đi, ghi log phản hồi, theo dõi kết quả, cảnh báo nội bộ và báo cáo. Không việc nào trong số đó đòi hỏi phán đoán tại thời điểm xử lý.
Phần vẫn cần con người nằm ở phía trước: thiết kế luồng consent trong ứng dụng của bạn, và quyết định chính sách refund preference của bạn nên là gì. Và tự động hóa không có ảnh hưởng gì đến quyết định của Apple, bất kể một số công cụ ngụ ý điều gì.
RefundSensor giúp developer xử lý quy trình hoàn tiền Apple như thế nào
Quản lý hoàn tiền App Store là hạng mục, và RefundSensor đảm nhận phía developer của nó: giám sát các quy trình hoàn tiền Apple, xử lý đường phản hồi được hỗ trợ cho các yêu cầu consumption, theo dõi các sự kiện và kết quả hoàn tiền, và gỡ những phần lặp đi lặp lại khỏi tay con người.
Trong thực tế, phản hồi được gửi đi trong khung thời gian mà không cần ai canh dashboard lúc 3 giờ sáng, và hồ sơ hoàn tiền vẫn chính xác khi khối lượng tăng lên. Nó không ngăn được hoàn tiền và không thể ảnh hưởng tới quyết định của Apple. Nó loại bỏ việc giám sát thủ công và những bước bị bỏ sót.
Các quy tắc này được ghi ở đâu
Send Consumption Information — endpoint hiện hành. Yêu cầu consent, khung 12 giờ và năm trường của yêu cầu. Hãy xây dựng theo tài liệu này cho các In-App Purchase tiêu chuẩn.
Send Consumption Information V1 — endpoint trước với body mười hai trường. Hữu ích để xác định tích hợp của bạn đang gọi phiên bản nào, và cho các giao dịch mua qua Advanced Commerce API.
App Store Server Notifications — cách gửi thông báo, định dạng payload đã ký, các mã phản hồi mong đợi và lịch thử lại.
Nếu việc này vẫn đang được làm thủ công
Khung 12 giờ, lịch thử lại có thể kéo dài quá khung đó, và thông báo đến giữa đêm khiến giám sát thủ công trở thành lựa chọn tồi. RefundSensor đảm nhận phía developer của các quy trình này — xác thực thông báo, chuẩn bị và gửi phản hồi trong khung thời gian, và theo dõi kết quả cho tới hồ sơ entitlement của bạn.
Câu hỏi thường gặp
Là một App Store Server Notification cho server của bạn biết rằng một khách hàng đã yêu cầu hoàn tiền và Apple đang mời bạn gửi thông tin mức sử dụng (consumption) về giao dịch mua đó. Đây không phải là thông báo hoàn tiền hay quyết định. Apple quyết định riêng, coi phản hồi của bạn là một yếu tố trong số nhiều yếu tố khác.
Vì Apple không thể thấy những gì diễn ra bên trong ứng dụng của bạn. Apple biết giao dịch và lịch sử tài khoản, nhưng không biết nội dung đã được giao hay chưa, có hoạt động không, hay khách hàng đã dùng bao nhiêu. Bối cảnh đó nằm trong hệ thống của bạn, nên Apple hỏi bạn trong quá trình xem xét.
Xác minh thông báo đã ký, xác định giao dịch và khách hàng đứng sau nó, xác nhận consent đã tồn tại, thu thập dữ liệu giao hàng và mức sử dụng thật từ hồ sơ của bạn, rồi gửi tới endpoint consumption của Apple trong khung thời gian. Ghi nhận kết quả phản hồi thay vì mặc định rằng lệnh gọi đã thành công.
Năm trường trên endpoint hiện hành. Ba trường bắt buộc: consent của khách hàng, trạng thái giao hàng, và có cung cấp nội dung dùng thử hay không. Hai trường tùy chọn: phần trăm mức sử dụng và mong muốn hoàn tiền của bạn. Endpoint V1 trước đây yêu cầu mười hai trường, đó là lý do các hướng dẫn cũ mô tả một danh sách dài hơn.
Tài liệu hiện hành của Apple mô tả thông báo này gắn với các yêu cầu hoàn tiền trên mọi loại sản phẩm, rộng hơn so với tài liệu cũ. Apple không công bố cam kết cho mọi trường hợp, nên hãy xây dựng một handler phản hồi khi yêu cầu đến thay vì logic mặc định rằng lúc nào cũng sẽ có yêu cầu.
Apple yêu cầu phản hồi trong vòng 12 giờ kể từ khi có thông báo. Đáng lưu ý là lịch thử lại của Apple cho các lần gửi thất bại chạy ở các mốc 1, 12, 24, 48 và 72 giờ, nên một endpoint ngừng hoạt động quá lần thử lại đầu tiên có thể chỉ nhận được thông báo sau khi khung thời gian đã đóng.
Apple cân nhắc nó cùng các yếu tố khác và quyết định. Kết quả đến dưới dạng một thông báo riêng cho biết hoàn tiền được chấp thuận, bị từ chối, hoặc sau đó bị đảo ngược. Từ đó, việc của bạn là cập nhật entitlement, trạng thái subscription và hồ sơ doanh thu cho khớp với trạng thái giao dịch mới.
Có. Xác thực, tra cứu giao dịch, kiểm tra consent, chuẩn bị dữ liệu, gửi đi, ghi log và theo dõi kết quả đều mang tính xác định. Phần vẫn cần con người là thiết kế luồng consent và đặt ra chính sách refund preference của bạn. Tự động hóa không ảnh hưởng gì đến quyết định hoàn tiền của Apple.
