فهم ما هو CONSUMPTION_REQUEST لا يستغرق أكثر من فقرة واحدة. أما بناء شيء يتعامل معه بشكل موثوق فيستغرق أكثر من ذلك بكثير، والأجزاء التي توقع الناس في الخطأ ليست الأجزاء التي تتوقعها.
التحقق من التوقيع أحدها. والموافقة أخرى، لأنها يجب أن تكون موجودة قبل وصول الإشعار. كما أن جدول إعادة المحاولة يتداخل مع نافذة الرد بطريقة تفاجئ معظم الفرق عند النظر إليها عن قرب للمرة الأولى.
يستعرض هذا المقال المعالج (handler) من لحظة وصول الطلب إلى نقطة النهاية الخاصة بك وحتى تحديث الاستحقاق الذي يغلق العملية.
أبرز النقاط
• يطلب CONSUMPTION_REQUEST معلومات أثناء مراجعة طلب استرداد. ولا يزال القرار بيد Apple.
• تحقّق من الحمولة الموقّعة قبل التصرف بناءً عليها. لا تثق أبدًا بإشعار لم يتم التحقق منه.
• يجب أن تكون الموافقة موجودة مسبقًا في تطبيقك. لا يمكنك جمعها بعد وصول الطلب.
• تطلب Apple ردًا خلال 12 ساعة من الإشعار.
• تعيد Apple محاولة التسليم الفاشل وفق جدول ثابت، وتصل إعادة المحاولة الثانية بعد انتهاء نافذة الرد.
• تتبّع النتيجة وحدّث الاستحقاق بعد ذلك. الرد ليس الخطوة الأخيرة.
ما هو إشعار CONSUMPTION_REQUEST من Apple؟
إشعار CONSUMPTION_REQUEST من Apple هو أحد إشعارات App Store Server Notifications يخبر خادمك بأن أحد العملاء طلب استرداد أمواله وأن Apple تدعوك لإرسال معلومات الاستهلاك الخاصة بعملية الشراء تلك. يصل إلى عنوان URL للإشعارات الذي قمت بتكوينه، ويحمل المعاملة ذات الصلة، ويمنحك وقتًا محدودًا للرد.
إنه ليس استردادًا وليس قرارًا. فـ Apple في منتصف المراجعة وتجمع السياق. دورك هو تقديم معلومات دقيقة عمّا حدث مع عملية الشراء؛ ودور Apple هو اتخاذ القرار.
لماذا ترسل Apple إشعار CONSUMPTION_REQUEST؟
لأن Apple لا تستطيع رؤية ما يجري داخل تطبيقك. فهي تعرف المعاملة والحساب وسجل الشراء. لكنها لا تعرف ما إذا كان المحتوى قد سُلِّم، أو ما إذا كان يعمل، أو مقدار ما استخدمه العميل منه.
معلومات الاستهلاك تسد هذه الفجوة. وهي أحد عدة عوامل تزنها Apple، وليست العامل الحاسم، ورقم الاستهلاك المرتفع ليس مفتاحًا للرفض. تعامل معها كسياق تساهم به لا كقضية تدافع عنها.
ماذا يجب على المطوّرين فعله عند تلقي CONSUMPTION_REQUEST؟
تحقّق من صحة الإشعار، وحدّد المعاملة والعميل، وتأكد من وجود الموافقة، وجمّع بيانات استهلاك دقيقة، وأرسلها ضمن نافذة Apple الزمنية، ثم سجّل ما حدث.
عشر خطوات عمليًا:
1. استقبل الإشعار على نقطة نهاية الخادم التي كوّنتها واحفظه فورًا.
2. تحقّق من الحمولة الموقّعة قبل التعامل مع أي حقل على أنه حقيقي.
3. اقرأ نوع الإشعار ووجّهه. طلب الاستهلاك ليس نتيجة استرداد.
4. حدّد المعاملة ذات الصلة من الحمولة بعد فك تشفيرها.
5. اربط المعاملة بحساب عميل في نظامك الخاص.
6. تحقّق مما إذا كانت موافقة ذلك العميل تسمح بالرد.
7. اجمع بيانات التسليم والاستخدام من سجلاتك، لا من التقديرات.
8. جهّز الرد وراجعه مقابل قواعد التحقق من الحقول.
9. أرسله إلى نقطة نهاية الاستهلاك لدى Apple وسجّل النتيجة.
10. تتبّع نتيجة الاسترداد التي تلي ذلك، ثم حدّث الاستحقاق والسجلات.
كيف يجب على المطوّرين التحقق من صحة CONSUMPTION_REQUEST؟
تحقّق من التوقيع قبل أن تثق بالمحتوى. تصل الإشعارات كحمولات JWS موقّعة، وهي موثّقة في وثائق Apple App Store Server Notifications، ويجب أن يتحقق المعالج لديك منها مقابل سلسلة شهادات Apple ويتأكد من أن معرّف الحزمة (bundle ID) يطابق تطبيقك.
السبب بسيط. عنوان URL للإشعارات الخاص بك نقطة نهاية عامة. والتنفيذ الذي يحلّل كل ما يصل ويتصرف بناءً عليه هو تنفيذ يمكن لأي شخص يعثر على العنوان أن يتحكم فيه.
ثلاثة تفاصيل في المعالج لا تقل أهمية عن التوقيع:
أرجع رمز الحالة الصحيح. تعتبر Apple رموز HTTP من 200 إلى 206 نجاحًا. أما 40x أو 50x فيخبر App Store بإعادة المحاولة. أرجع النجاح بمجرد تخزين الإشعار، لا بعد الانتهاء من معالجته — فهاتان لحظتان مختلفتان، وربطهما معًا يعني أن مهمة لاحقة بطيئة قد تتسبب في إعادة محاولات لا داعي لها.
تعامل مع التكرارات. تعني إعادة المحاولات أن الإشعار نفسه قد يصل أكثر من مرة، ويحمل كل منها UUID للإشعار يمكنك استخدامه لإزالة التكرار. أقرّ باستلام التكرارات بدلًا من إرجاع خطأ عليها؛ فرد الفشل لا يفعل سوى إعادة تشغيل دورة إعادة المحاولة.
تذكّر أن بيئة sandbox تتصرف بشكل مختلف. تنطبق إعادة المحاولات في بيئة الإنتاج. أما في sandbox فيحاول App Store التسليم مرة واحدة فقط، لذا قد يبدو المعالج سليمًا في الاختبار بينما لا يزال يفقد أحداثًا في الإنتاج، والعكس صحيح أيضًا.
ماذا يجب على المطوّرين التحقق منه قبل الرد؟
أربعة أمور، بهذا الترتيب.
الموافقة أولًا، لأنها الأمر الوحيد الذي يمكن أن يوقف كل شيء. تشترط Apple موافقة صالحة من العميل قبل مشاركة بياناته، والحصول عليها مسؤوليتك أنت لا مسؤولية Apple، والإشعار نفسه لا يحمل أي علامة للموافقة. وتوضح Apple صراحةً أن مطالبة App Tracking Transparency ليست الآلية المطلوبة هنا. وإذا لم تكن الموافقة موجودة، فالتوجيه هو عدم الرد.
هوية المعاملة ثانيًا. تحتاج إلى معرفة أي عملية شراء هذه وأي حساب يقف خلفها. هذا الربط هو ما يدور حوله موضوع appAccountToken والدفاع في طلبات استرداد Apple فبدون رابط ثابت من المعاملة إلى الحساب، أنت تستنتج تحت ضغط مهلة زمنية.
نوع المنتج ثالثًا، لأنه يؤثر في الخيارات المتاحة لك. وأخيرًا، ما إذا كنت تملك فعلًا بيانات قابلة للاستخدام. إذا كانت أنظمتك لا تستطيع تحديد ما إذا كان المحتوى قد سُلِّم، فمن الأفضل معرفة ذلك قبل البدء في تجهيز الرد.
ما معلومات الاستهلاك التي يمكن للمطوّرين إرسالها إلى Apple؟
تحدد وثائق Send Consumption Information الحالية من Apple خمسة حقول. ثلاثة منها مطلوبة واثنان اختياريان.
الحقل | مطلوب | بعبارة بسيطة |
customerConsented | نعم | هل وافق العميل على ذلك؟ يجب أن تكون القيمة true، وإلا رُفض الطلب. |
deliveryStatus | نعم | هل سلّم تطبيقك فعلًا عملية شراء تعمل، وإن لم يكن كذلك فلماذا؟ |
sampleContentProvided | نعم | هل كان بإمكان العميل تجربته قبل الشراء؟ |
consumptionPercentage | لا | ما مقدار ما استخدمه؟ بوحدات الملّي — النصف هو 50000 وليس 50. |
refundPreference | لا | ما الذي تفضّله: منح الاسترداد كاملًا، أو رفضه، أو احتسابه نسبيًا. |
قاعدتان توقعان الناس في الخطأ. إذا كانت حالة التسليم أي شيء غير "تم التسليم"، فيجب أن تكون نسبة الاستهلاك صفرًا. وتفضيل الاسترداد هو تفضيل لا تعليمات؛ فبإمكان Apple أن تقرر خلاف ذلك، وهي تفعل ذلك بالفعل.
من المفيد التحقق من نقطة النهاية التي تستخدمها. توثّق Apple أيضًا وثائق ConsumptionRequestV1 من Apple، وهي النسخة الأقدم ذات نص الطلب المكوّن من اثني عشر حقلًا والتي لا تزال معظم المقالات الخارجية تصفها. وتوجّه ملاحظة Apple هناك عمليات الشراء داخل التطبيق القياسية إلى نقطة النهاية الحالية وتقصر V1 على عمليات شراء Advanced Commerce API. إذا كان تكاملك سابقًا لهذا التغيير، فهذا أول ما يجب النظر إليه.
كم من الوقت لدى المطوّرين للرد على CONSUMPTION_REQUEST؟
تطلب وثائق Apple الحالية ردًا خلال 12 ساعة من الإشعار.
وهنا الجزء الذي يستحق الانتباه. تعيد Apple محاولة التسليم الفاشل خمس مرات، بعد 1 و12 و24 و48 و72 ساعة من المحاولة السابقة. قارن ذلك بنافذة 12 ساعة وستجد أن الحساب غير مريح: إذا فاتت نقطة النهاية لديك التسليم الأول، تصل إعادة المحاولة الأولى بعد ساعة ولا مشكلة. وإذا فاتتها تلك أيضًا، تصل المحاولة التالية بعد نحو ثلاث عشرة ساعة أي بعد أن تكون النافذة قد أُغلقت بالفعل.
لذا فإن موثوقية نقطة النهاية ليست هنا مجرد مسألة انضباط تقني عام. ففي طلبات الاستهلاك تحديدًا، يمكن تدارك نحو ساعة واحدة من التوقف، أما نصف يوم فلا.
لا تذكر Apple أن تفويت النافذة يعني الموافقة التلقائية على الاسترداد، ومن الخطأ الادعاء بذلك. ما يعنيه الأمر ببساطة هو أن Apple تقرر دون معلومات كان بإمكانك تقديمها.
ماذا يحدث بعد رد المطوّر؟
تأخذ Apple معلوماتك في مراجعتها، وتزنها مع كل شيء آخر، وتقرر. تصل النتيجة كإشعار منفصل: منح، أو رفض، أو عكس إذا تراجعت Apple لاحقًا عن استرداد وافقت عليه.
ثلاثة أمور مختلفة تحدث هنا ومن المفيد الفصل بينها. ردك معلومات. وقرار Apple قرار. وتحديث نظامك تغيير في الحالة. الثاني فقط يخص Apple، والثالث لا يحدث ما لم تبنِه أنت.
كيف يتعامل المطوّرون مع عمليات استرداد Apple بعد الرد
بمجرد وصول النتيجة، يعود العمل إليك.
سجّل النتيجة مقابل المعاملة والعميل. حدّث حالة الاشتراك، لأن الفترة المستردة تنهي الاشتراك عادةً بدلًا من تركه قائمًا. ألغِ الاستحقاق عند منح الاسترداد، وأعده عند العكس، وتعامل مع الحالة النسبية التي يُلغى فيها جزء فقط من المعاملة.
ثم سوِّ المبلغ ضمن فترة التقارير الصحيحة واحتفظ بالاسترداد في سجل قابل للاستعلام. هذا السجل هو ما يخبرك لاحقًا ما إذا كان منتج أو سعر معين ينتج حصة غير متناسبة، وهو أيضًا ما يحتاجه فريق الدعم عندما يسأل عميل عمّا حدث لصلاحية وصوله.
ما الأخطاء الشائعة عند التعامل مع CONSUMPTION_REQUEST؟
الأخطاء التي تتكرر باستمرار:
• التعامل مع الإشعار على أنه استرداد وإلغاء الوصول فورًا. لم يُتخذ أي قرار بعد.
• تخطي التحقق من التوقيع لأن الحمولة تبدو سليمة في الاختبار.
• اكتشاف عدم وجود تدفق للموافقة في اللحظة التي يحين فيها موعد الرد.
• إرسال أرقام استهلاك تقديرية بدلًا من الحقيقية.
• إطلاق الطلب دون التحقق أبدًا مما إذا كان قد نجح. الإرسال الفاشل يبدو لاحقًا مطابقًا تمامًا للناجح.
• الخلط بين الإلغاء والاسترداد. إنهما حدثان مختلفان بتأثيرات مختلفة على الوصول.
• التعامل مع نتيجتي المنح والرفض ونسيان حالة العكس، ما يحرم عملاء يدفعون من الوصول.
• الاعتماد على أن يلاحظ أحدهم الإشعار يدويًا، في مواجهة عدّاد 12 ساعة.
هل يمكن أتمتة التعامل مع CONSUMPTION_REQUEST؟
نعم، وينبغي أتمتة كل شيء تقريبًا، لأن كل خطوة تقريبًا حتمية.
تغطي الأتمتة مراقبة الإشعارات والتحقق منها، والبحث عن المعاملات، وفحص الموافقة، وتجهيز بيانات الاستهلاك، والإرسال، وتسجيل الردود، وتتبع النتائج، والتنبيهات الداخلية، والتقارير. لا يتطلب أي من ذلك حكمًا بشريًا في اللحظة.
ما يبقى بشريًا يقع في مرحلة أسبق: تصميم تدفق الموافقة في تطبيقك، وتحديد ما ينبغي أن تكون عليه سياسة تفضيل الاسترداد لديك. والأتمتة لا تؤثر في قرار Apple، مهما أوحت بعض الأدوات بخلاف ذلك.
كيف يساعد RefundSensor المطوّرين في التعامل مع سير عمل استرداد Apple
إدارة عمليات استرداد App Store هي الفئة، ويغطي RefundSensor جانب المطوّر منها: مراقبة سير عمل استرداد Apple، والتعامل مع مسار الرد المدعوم لطلبات الاستهلاك، وتتبع أحداث الاسترداد ونتائجه، وإزاحة الأجزاء المتكررة عن كاهل الأشخاص.
عمليًا، تخرج الردود ضمن النافذة الزمنية دون أن يراقب أحد الـ dashboard في الثالثة فجرًا، وتبقى سجلات الاسترداد دقيقة مع نمو الحجم. لا يمنع عمليات الاسترداد ولا يمكنه التأثير فيما تقرره Apple. إنه يزيل المراقبة اليدوية والخطوات المنسية.
أين توثَّق هذه القواعد
Send Consumption Information — نقطة النهاية الحالية. شرط الموافقة، ونافذة 12 ساعة، وحقول الطلب الخمسة. ابنِ تكاملك على هذه لعمليات الشراء داخل التطبيق القياسية.
Send Consumption Information V1 — نقطة النهاية الأقدم ذات نص الطلب المكوّن من اثني عشر حقلًا. مفيدة لتحديد الإصدار الذي يستدعيه تكاملك، ولعمليات شراء Advanced Commerce API.
App Store Server Notifications — تسليم الإشعارات، وتنسيق الحمولة الموقّعة، ورموز الاستجابة المتوقعة، وجدول إعادة المحاولة.
إذا كان هذا لا يزال يُدار يدويًا
نافذة 12 ساعة، وجدول إعادة محاولة قد يتجاوزها، وإشعارات تصل أثناء الليل، كلها تجعل المراقبة اليدوية خيارًا غير مناسب. RefundSensor يتولى جانب المطوّر من هذه العمليات التحقق من الإشعارات، وتجهيز الردود وإرسالها ضمن النافذة، وتتبع النتائج وصولًا إلى سجلات الاستحقاق لديك.
الأسئلة الشائعة
هو أحد إشعارات App Store Server Notifications يخبر خادمك بأن أحد العملاء طلب استرداد أمواله وأن Apple تدعوك لإرسال معلومات الاستهلاك الخاصة بعملية الشراء. إنه ليس إشعار استرداد ولا قرارًا. فـ Apple تقرر بشكل منفصل، وتتعامل مع ردك كمدخل واحد ضمن عدة عوامل.
لأن Apple لا تستطيع رؤية ما حدث داخل تطبيقك. فهي تعرف المعاملة وسجل الحساب، لكنها لا تعرف ما إذا كان المحتوى قد سُلِّم، أو ما إذا كان يعمل، أو مقدار ما استخدمه العميل. هذا السياق موجود في أنظمتك، لذا تطلبه Apple أثناء المراجعة.
تحقّق من الإشعار الموقّع، وحدّد المعاملة والعميل الذي يقف خلفها، وتأكد من وجود الموافقة، واجمع بيانات التسليم والاستخدام الحقيقية من سجلاتك، ثم أرسلها إلى نقطة نهاية الاستهلاك لدى Apple ضمن النافذة الزمنية. سجّل نتيجة الاستجابة بدلًا من افتراض أن الاستدعاء قد نجح.
خمسة حقول في نقطة النهاية الحالية. ثلاثة مطلوبة: موافقة العميل، وحالة التسليم، وما إذا كان قد تم توفير محتوى تجريبي. واثنان اختياريان: نسبة الاستهلاك وتفضيلك بشأن الاسترداد. أما نقطة النهاية الأقدم V1 فكانت تطلب اثني عشر حقلًا، ولهذا تصف الإرشادات القديمة قائمة أطول.
تصف وثائق Apple الحالية الإشعار في سياق طلبات الاسترداد عبر جميع أنواع المنتجات، وهو نطاق أوسع مما أشارت إليه الوثائق القديمة. لا تنشر Apple ضمانًا لكل حالة، لذا ابنِ معالجًا يرد عند وصول الطلب بدلًا من منطق يفترض أنه سيصل دائمًا.
تطلب Apple ردًا خلال 12 ساعة من الإشعار. ومن الجدير بالذكر أن جدول إعادة المحاولة لدى Apple للتسليمات الفاشلة يعمل عند 1 و12 و24 و48 و72 ساعة، لذا فإن نقطة النهاية التي تظل متوقفة بعد إعادة المحاولة الأولى قد لا تتلقى الإشعار إلا بعد إغلاق النافذة.
تزنها Apple مع عوامل أخرى وتقرر. تصل النتيجة كإشعار منفصل يشير إلى أن الاسترداد قد مُنح أو رُفض أو عُكس لاحقًا. ومن هناك تقع عليك مهمة تحديث الاستحقاق وحالة الاشتراك وسجلات الإيرادات لتتوافق مع حالة المعاملة الجديدة.
نعم. فالتحقق، والبحث عن المعاملات، وفحص الموافقة، وتجهيز البيانات، والإرسال، والتسجيل، وتتبع النتائج كلها عمليات حتمية. وما يبقى بشريًا هو تصميم تدفق الموافقة وتحديد سياسة تفضيل الاسترداد لديك. الأتمتة لا تؤثر في قرار Apple بشأن الاسترداد.
