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