شرح Apple CONSUMPTION_REQUEST: دليل خطوة بخطوة لسير عمل الاسترداد لمطوري التطبيقات

تخيل هذا السيناريو. يشتري عميل خطتك السنوية، ويستخدمها لمدة أسبوع، ثم يطلب من Apple استرداد أمواله. تعرف بالأمر عندما تصل أرباحك أقل من المتوقع. لم يسألك أحد عن أي شيء. أو هكذا يبدو الأمر.

في الواقع، تسأل Apple غالبًا. فهي ترسل إلى خادمك رسالة تُسمى CONSUMPTION_REQUEST، وتريد معرفة كيف استخدم العميل بالفعل ما اشتراه. وإذا كان خادمك لا يستمع إلى هذه الرسائل، تتخذ Apple القرار من دونك. يشرح هذا الدليل عملية استرداد App Store للمطورين خطوة بخطوة، ويوضح النقاط التي يتعثر فيها الكثيرون. وللحصول على نظرة أوسع على الدفاع عن طلبات الاسترداد في iOS، صفحة الدفاع عن استرداد App Store من RefundSensor تتناول هذا الموضوع أيضًا.

إجابة سريعة

إشعار CONSUMPTION_REQUEST هو طريقة Apple لطلب تفاصيل الاستخدام عندما يطلب العميل استردادًا. إذا وافق العميل على مشاركة البيانات، يجب أن يستدعي خادمك واجهة Send Consumption Information Axz`PI في غضون 12 ساعة، ويُبلغ عن التسليم والاستخدام. تزن Apple هذه المعلومات وتتخذ القرار النهائي. لا يمكنك الموافقة على استرداد أو ضمان النتيجة.

ما هو Apple CONSUMPTION_REQUEST؟

CONSUMPTION_REQUEST هو نوع من الإشعارات في App Store Server Notifications V2. ترسله Apple كل مرة يبدأ فيها عميل طلب استرداد، ويشمل جميع أنواع المنتجات: الاستهلاكية، وغير الاستهلاكية، والاشتراكات غير المتجددة، والاشتراكات المتجددة تلقائيًا.

فكّر فيه كسؤال، لا كأمر. لا تطلب منك Apple استرداد أموال أي شخص. بل تسألك عما تعرفه. وتظل Apple هي التي تتخذ القرار النهائي، وإجابتك ليست إلا عاملاً واحدًا من بين ما تنظر فيه.

كيف يعمل سير عمل استرداد Apple

يحدث هنا أمران، وكثيرًا ما يخلط الناس بينهما. استلام الإشعار يحدث تلقائيًا. أما إرسال معلومات الاستخدام في الرد، فلا يحدث إلا إذا قام خادمك بذلك.

1. يطلب العميل من Apple استرداد أمواله.

2. ترسل Apple إشعار CONSUMPTION_REQUEST إلى عنوان URL الخاص بإشعارات V2 لديك.

3. يتحقق خادمك مما إذا كان العميل قد وافق على مشاركة بيانات الاستخدام.

4. إذا وافق، يرسل خادمك تفاصيل الاستخدام في غضون 12 ساعة.

5. تتخذ Apple قرارها. وإذا منحت الاسترداد، يتبع ذلك إشعار REFUND.

دليل التنفيذ خطوة بخطوة

إليك الإعداد من البداية إلى النهاية.

1. أضف عنوان URL لإشعاراتك. في App Store Connect، أدخل عنوان HTTPS الخاص بخادمك واختر الإصدار 2.

2. رد بسرعة. أرسل ردًا برمز حالة بين 200 و206. فأي رمز من فئة 40x أو 50x يجعل Apple تعيد المحاولة.

3. تحقق من التوقيع. تأتي حمولات V2 موقّعة. تحقّق منها قبل قراءة أي محتوى بداخلها.

4. اعثر على العميل. طابق المعاملة مع مستخدم في قاعدة بياناتك الخاصة.

5. تحقق من الموافقة. لا موافقة، لا رد.

6. استدعِ واجهة API. أرسل البيانات عبر طلب App Store Server API، مع المصادقة باستخدام مفتاح In-App Purchase من App Store Connect.

7. سجّل ذلك. احتفظ بسجل لما أرسلته ومتى.

كيف ترد على طلب استرداد من Apple بصفتك مطورًا

ابدأ دائمًا بالموافقة. بعد ذلك، أخبر Apple بما حدث بالفعل. القيمة هنا تأتي من بيانات دقيقة وصادقة، فلا تضخّمها.

لنأخذ حالتين.

• لاعب يشتري حزمة عملات ويستهلك معظمها في يوم واحد. أبلغ عن هذا الاستخدام المكثف. وطلب رفض الاسترداد من Apple يُعد تفضيلًا معقولاً.

• مشترك يدفع لمدة عام، لكن خادمك كان معطلاً ولم يتم تحميل المحتوى أبدًا. أبلغ بأن المحتوى لم يُسلَّم. وهنا، قد يكون منح الاسترداد هو الإجابة الصادقة.

تفضيلك بشأن الاسترداد هو مجرد اقتراح. ولا يتعين على Apple الالتزام به.

شرح واجهة Apple Send Consumption Information API

تُعد نقطة النهاية Send Consumption Information طلب PUT مرتبطًا بمعرّف معاملة (/inApps/v2/transactions/consumption/{transactionId}). تستدعيها بعد وصول CONSUMPTION_REQUEST، وتريد Apple الرد في غضون 12 ساعة.

النص الأساسي هو كائن ConsumptionRequest يتضمن خمسة حقول:

• customerConsented: هل وافق العميل على مشاركة البيانات؟ يجب أن تكون القيمة true. وإلا ترفض Apple الطلب بخطأ HTTP 400.

• deliveryStatus: هل سلّم تطبيقك عملية شراء تعمل بشكل صحيح؟

• sampleContentProvided: هل قدّمت عينة مجانية أو نسخة تجريبية مسبقًا؟

• consumptionPercentage: مقدار ما تم استخدامه، بوحدة المليجزء (milliunits).

• refundPreference: النتيجة التي تفضلها.

هناك بعض القواعد التي يتعثر فيها الناس. إذا لم تكن قيمة deliveryStatus مساوية لـ DELIVERED، فاضبط consumptionPercentage على 0، وإلا سيفشل الطلب. وفي حالة اشتراك متجدد تلقائيًا مع GRANT_PRORATED، اترك consumptionPercentage دون تحديد، لأن Apple تحسبها بنفسها. كما أن الموافقة تقع على عاتقك أنت. وتشير Apple أيضًا إلى عدم استخدام نافذة App Tracking Transparency لهذا الغرض.

تكامل App Store Server Notifications V2

App Store Server Notifications V2 هي الطريقة التي تتواصل بها Apple مع خادمك. ستحتاج إلى عنوان HTTPS آمن يدعم TLS 1.2 أو إصدار أحدث.

CONSUMPTION_REQUEST ليس إلا نوعًا واحدًا من بين أنواع عديدة. وأنواع أخرى، مثل REFUND وREFUND_REVERSED، تخبرك بكيفية انتهاء الحالة. اجعل لكل نوع معالجه الخاص حتى لا يتشابك كود الاسترداد مع كود التجديد. هل تريد أن ترى الجانب الخاص بـ App Store Connect عمليًا؟ يتناول دليل إعداد Apple من Refund Sensor المفاتيح وعنوان URL للإشعارات.

أخطاء شائعة يجب تجنبها

• التوقف عند الإشعار. لا يُحقق CONSUMPTION_REQUEST شيئًا حتى يرسل خادمك البيانات في الرد.

• تجاهل الموافقة. عدم موافقة العميل يعني عدم الرد.

• تفويت فترة الـ12 ساعة. تصل هذه الإشعارات أحيانًا ليلاً وفي عطلات نهاية الأسبوع. استخدم قائمة انتظار (queue) وفعّل التنبيهات.

• إرسال توليفات غير صحيحة. نسبة استخدام على عملية شراء لم تُسلَّم ستؤدي إلى فشل الطلب.

• تخطي فحص التوقيع. تحقّق أولاً، وثق ثانيًا.

• الرد ببطء. أعد رمز نجاح بسرعة، وقم بالعمل الثقيل في الخلفية، وإلا ستستمر Apple في إعادة المحاولة.

• عدم وجود طريقة للعثور على المستخدم. إذا لم تستطع ربط المعاملة بعميل، فلن يكون لديك ما تبلّغ عنه فعلاً.

كيف تؤتمت سير عمل استرداد App Store

لا يريد أحد متابعة عداد الـ12 ساعة يدويًا. إذا كنت تريد أتمتة سير عمل استرداد App Store، فقسّم المهمة إلى خطوات صغيرة:

1. استقبل الإشعار وأعد رمز نجاح فورًا.

2. ضع الحدث في قائمة انتظار (queue).

3. تتحقق عملية معالجة (worker) منه، وتعثر على المستخدم، وتفحص الموافقة.

4. تبني عملية المعالجة الطلب من بيانات الاستخدام المخزنة وتستدعي واجهة API.

5. سجّل النتيجة، ونبّه شخصًا ما إذا فشل الأمر.

تحصل بذلك على إجابات متسقة، وسجل تدقيق واضح، ولا يضطر أحد للبقاء مستيقظًا في الساعة 3 صباحًا. يمكنك بناء هذا بنفسك، أو تسليم خط الأتمتة إلى خدمة مثل RefundSensor.

أفضل الممارسات للمطورين

• خزّن بيانات استخدام حقيقية: الجلسات، والأرصدة المستهلكة، والمحتوى المفتوح. لا يمكنك الإبلاغ عن أرقام لم تحتفظ بها من الأساس.

• أضف خطوة موافقة واضحة إلى شروطك أو عملية التهيئة الأولى، وسجّل وقت إعطائها.

• اكتب قواعد الاسترداد الخاصة بك مرة واحدة وضمّنها في الكود، بدلاً من اتخاذ القرار في كل حالة على حدة.

• اختبر باستخدام إشعارات بيئة sandbox قبل الإطلاق الفعلي.

• أرفق رمز حساب (account token) بكل عملية شراء حتى تتمكن من تحديد المشتري لاحقًا. يشرح دليل appAccountToken كيفية ذلك.

• راجع نتائج الاسترداد مرة واحدة شهريًا. فالارتفاعات غير المعتادة قد تشير إلى ميزة معطلة أو جدار دفع (paywall) مربك.

الخلاصة

يتلخص سير عمل استرداد Apple في نصفين. ترسل Apple إشعار CONSUMPTION_REQUEST، وتختار أنت ما إذا كنت سترد. إذا وافق العميل، أرسل بيانات صادقة عبر Send Consumption Information API في غضون 12 ساعة. وتظل Apple هي من تتخذ القرار.

خطوة أولى جيدة: تأكد من أن عنوان URL لإشعارات V2 لديك فعّال، وأن خادمك قادر على مطابقة المعاملة بالمستخدم. هذان الفحصان يوفران عليك كثيرًا من المتاعب لاحقًا.