تساعدك عروض الاحتفاظ بالمشتركين في تقليل حالات إلغاء الاشتراك الطوعي من خلال عرض خصم للمشتركين في اللحظة التي يحاولون فيها إلغاء اشتراكهم في Google Play.
عندما يبدأ مشترك مؤهَّل في إلغاء اشتراكه، يعرض له Google Play عرضًا ترويجيًا للاحتفاظ به كنت قد أعددته، مثل "احتفِظ باشتراكك واحصل على خصم %50 للشهرَين التاليَين". إذا قَبِل المشترك العرض، لن يتم إلغاء اشتراكه. يبدأ تطبيق السعر المخفَّض في تاريخ الفوترة التالي.
توضّح هذه الصفحة طريقة عمل عروض الحفاظ على المشتركين، وكيفية ضبطها، وكيفية التعامل مع الأحداث الناتجة في الخلفية، وكيفية اختبارها.
قبل البدء
قبل إعداد عروض الاحتفاظ بالمشتركين، تأكَّد من تنفيذ ما يلي:
- أنشأت اشتراكًا يتضمّن خطة أساسية واحدة على الأقل تتجدّد تلقائيًا. لا يمكن إضافة عروض الاحتفاظ بالمشتركين إلا إلى الخطط الأساسية التي يتم تجديدها تلقائيًا.
- إعداد الإشعارات في الوقت الفعلي الخاصة بالمطوّرين (RTDN) وإعداد الخلفية لاستدعاء طريقة
purchases.subscriptionsv2.getوتستخدم الواجهة الخلفية هذه الأحداث لرصد قبول المشترك لعرض الاحتفاظ به.
بما أنّ Google Play يعرض عروض الاحتفاظ بالمشتركين خارج تطبيقك، لن تحتاج إلى تغيير تطبيقك أو تعديل عملية دمج Google Play Billing Library لاستخدامها. تتم جميع عمليات الدمج في Google Play Console والخلفية.
طريقة عمل عروض الاحتفاظ بالمشتركين
لا تظهر عروض الاحتفاظ بالمشتركين إلا في إدارة الاشتراكات في Google Play: تطبيق "متجر Google Play" وGoogle Play على الويب. ولا تظهر داخل تطبيقك.
لا تعرض واجهة Google Play Billing Library عروض الاحتفاظ بالمشتركين في نتائج queryProductDetailsAsync()، لذا لا يتم تضمينها في ProductDetails.getSubscriptionOfferDetails()، ولا يمكنك بيعها من خلال launchBillingFlow(). إذا كان تطبيقك يستخدم روابط لصفحات في التطبيق لإرسال المشتركين إلى مركز الاشتراكات في Google Play أو إلى اشتراك معيّن ليتمكّنوا من إدارته أو إلغائه، يمكن لهؤلاء المشتركين الاطّلاع على عرض الحفاظ على المشتركين عندما يبدأون في إلغاء الاشتراك من هناك.
توضِّح الخطوات التالية ما يحدث عندما يحاول المشترك إلغاء الاشتراك:
- يفتح المشترك اشتراكه في Google Play ويبدأ في إلغائه.
يتحقّق Google Play من أهلية المشترك للاستفادة من أحد عروضك الترويجية للاحتفاظ بالمشتركين، وذلك استنادًا إلى قواعد الأهلية التي حدّدتها للعرض الترويجي أو إلى ما إذا كنت قد وجّهت العرض الترويجي إلى هذا المشترك.
إذا كان المشترك مؤهَّلاً، قد يعرض Google Play عرض الاحتفاظ بالمشتركين كبديل للإلغاء. لا يضمن استيفاء معايير الأهلية ظهور العرض، لأنّ Google Play يُجري أيضًا عمليات تحقّق إضافية على مستوى المنصة، مثل متطلبات الامتثال الإقليمية. إذا عرض Google Play العرض الترويجي، يمكن للمشترك تنفيذ أحد الإجراءات التالية:
- قبول العرض: يقبل المشترك العرض بنقرة واحدة. يظل الاشتراك نشطًا ويتم تجديده تلقائيًا. لا يتم تحصيل الرسوم من المشترك على الفور، بل يتم تطبيق السعر المخفَّض بدءًا من مدة الفوترة التالية.
- مواصلة الإلغاء: يرفض المشترك العرض ويكمل عملية الإلغاء العادية. ستتلقّى إشعار
SUBSCRIPTION_CANCELEDالمعتاد. لمعرفة التفاصيل، يُرجى الاطّلاع على عمليات الإلغاء.
إذا غادر المشترك مسار الإلغاء بدون قبول العرض أو إلغاء الاشتراك، لن يتغيّر اشتراكه. ينطبق ذلك على كل من تطبيق "متجر Google Play" وGoogle Play على الويب. لا يتم احتساب الاطّلاع على عرض ترويجيّ للاحتفاظ بالمشتركين بدون قبوله ضمن الحدّ الأقصى لعدد مرات الاستفادة من العرض، ولا يؤدي إلى بدء فترة الانتظار بين العروض الترويجية. يتحقّق Google Play من الحدّ الأقصى لعدد المطالبات عند عرض العرض الترويجي ومرة أخرى عندما يقبله المشترك. يتم احتساب العرض المقبول ضمن الحد الأقصى لعدد المطالبات عندما يتم تجديد الاشتراك بالسعر المخفَّض. تبدأ فترة الانتظار بين العروض عند انتهاء فترة الخصم لعرض الاحتفاظ السابق على الخطة الأساسية نفسها. وقد يظهر العرض للمشترك مرة أخرى في المرة التالية التي يحاول فيها إلغاء الاشتراك، شرط أن يكون مؤهلاً للاستفادة منه.
الانتقال المجدوَل إلى خطة أخرى
عندما يقبل المشترك عرضًا ترويجيًا للاحتفاظ بالمشتركين، يضع Google Play نموذجًا له على أنّه
انتقال مجدوَل للخطة في عملية الشراء الحالية للمشترك. ويختلف هذا عن الاستبدال المؤجَّل الذي يتطلّب مسار شراء جديدًا وينشئ رمزًا مميّزًا جديدًا للشراء. من خلال عرض الاحتفاظ بالمشتركين، يحتفظ المشترك بنفس
purchaseToken، وتتغيّر فقط بنود الفوترة المستقبلية.
عندما يقبل المشترك العرض، ينفّذ Google Play ما يلي:
- يتم إرسال إشعار في الوقت الفعلي خاص بالمطوّرين (RTDN) من النوع
SUBSCRIPTION_PLAN_TRANSITION_UPDATED(21) إلى الخلفية. - تضيف هذه السمة كائن
planTransitionDetailsإلى الحقلautoRenewingPlanالخاص بالبند الإعلاني المتأثر في الموردSubscriptionPurchaseV2.
لمعرفة تفاصيل حول التعامل مع هذه الأحداث، يُرجى الاطّلاع على مقالة التعامل مع أحداث عروض الحفاظ على المشتركين في الخلفية.
متطلبات الأهلية
يمكن أن يتلقّى الاشتراك عرضًا ترويجيًا للاحتفاظ بالمشتركين في أي وقت قبل تجديده التالي، طالما أنّ جميع الشروط التالية مستوفاة:
- الاشتراك نشط ويتم تجديده تلقائيًا. لا يمكن أن تتلقّى الاشتراكات في فترة السماح أو المعلّقة أو المتوقفة مؤقتًا عروض الاحتفاظ بالمشتركين.
- الاشتراك هو اشتراك واحد. لا تتوفّر عروض الحفاظ على المشتركين للاشتراكات التي تتضمّن ميزات إضافية.
- لا يستخدم الاشتراك خطة أساسية بنظام التقسيط. الخطط الأساسية بنظام التقسيط غير مؤهَّلة لعروض الاحتفاظ بالمشتركين.
- وتكون الدفعة التالية بالسعر العادي المتكرّر للخطة الأساسية. إذا كان المشترك في فترة تجريبية مجانية أو في مرحلة السعر التمهيدي، لا يتوفّر العرض إلا خلال مدة الفوترة النهائية لتلك المرحلة، عندما يكون التجديد القادم بالسعر العادي.
- ألا يكون المشترك في مدة فوترة مخفَّضة لعرض ترويجي للاحتفاظ بالمشتركين تم قبوله سابقًا. لا يمكن للمشترك الذي يستفيد من مرحلة الخصم في عرض ترويجي للاحتفاظ بالمشتركين الاستفادة من عرض ترويجي آخر للاحتفاظ بالمشتركين إلى أن يتم تجديد الاشتراك بسعر الخطة الأساسية العادي.
- لا يتضمّن الاشتراك أي عملية انتقال مُجدوَلة في انتظار المراجعة. يمكن أن يتضمّن الاشتراك عملية انتقال واحدة كحد أقصى إلى خطة مجدوَلة في انتظار المراجعة، وهي عنصر
planTransitionDetailsفي الحالةIN_PROGRESS. على سبيل المثال، لا يمكن للمشترك الذي قَبِل عرضًا للاحتفاظ به لم يدخل حيز التنفيذ بعد أن يتلقّى عرضًا آخر. - لا يتضمّن الاشتراك أي تغيير في السعر لم يتم تأكيده.
- أن يكون السعر المخفَّض لعرض الاحتفاظ بالمشتركين أقل من أو يساوي سعر تجديد الخطة الأساسية التالي للمشترك
- يستوفي المشترك قواعد الأهلية التي تم ضبطها للعرض. بالنسبة إلى عرض الحفاظ على المستخدمين لكل مستخدم، لقد فعّلت الاستهداف للاشتراك باستخدام طريقة
activateOfferTargeting.
ضبط عروض الاحتفاظ بالمشتركين
يمكنك إنشاء عروض ترويجية للاحتفاظ بالمشتركين في Google Play Console أو باستخدام Google Play Developer API. يستخدم كل عرض ترويجي للاحتفاظ بالمشتركين أحد أوضاع الاستهداف التالية:
- الاستهداف المستند إلى القواعد: يحدّد Google Play المشتركين المؤهَّلين بناءً على قواعد الأهلية التي تضعها، مثل الحدّ الأدنى لمدة الاشتراك المدفوع.
- الاستهداف لكل مستخدم: يحدّد الخلفية المشتركين الذين يمكنهم رؤية العرض من خلال استهدافه لاشتراكات معيّنة.
يمكن أن تتضمّن الخطة الأساسية أكثر من عرض ترويجي نشط واحد للاحتفاظ بالمشتركين في البلد أو المنطقة نفسها. عندما يكون المشترك مؤهَّلاً لأكثر من عرض واحد، يعرض Google Play عرضًا واحدًا على الأكثر للاحتفاظ بالمشتركين في مسار الإلغاء. يختار Google Play العرض بالترتيب التالي:
- وضع الاستهداف: يكون للعرض الترويجي المستهدَف لكل مستخدم (
retentionPerUserRule) الأولوية دائمًا على العرض الترويجي المستنِد إلى قاعدة (retentionRule)، حتى إذا كان العرض الترويجي المستنِد إلى قاعدة يتضمّن نسبة خصم أعلى. - نسبة الخصم: من بين العروض المؤهَّلة التي تستخدم وضع الاستهداف نفسه، يعرض Google Play العرض الذي يتضمّن أعلى نسبة خصم معروضة.
- السعر المخفَّض: إذا كانت العروض تتضمّن نسبة الخصم نفسها، يعرض Google Play العرض الذي يتضمّن أقل سعر مخفَّض.
- معرّف العرض الترويجي: إذا ظلّت العروض الترويجية متساوية، يعرض Google Play العرض الترويجي الذي يأتي
offerIdفي آخر الترتيب الأبجدي.
إنشاء عرض ترويجي للاحتفاظ بالمشتركين في Play Console
لإنشاء عرض ترويجي للاحتفاظ بالمشتركين في Google Play Console، اتّبِع الخطوات التالية:
- انتقِل إلى تحقيق الربح مع Google Play > المنتجات > الاشتراكات.
- اختَر اشتراكًا، ثم اختَر الخطة الأساسية التي تريد إضافة العرض الترويجي إليها.
- أضِف عرضًا ترويجيًا للمشتركين الحاليين الذين يحاولون إلغاء الاشتراك.
- اختَر عرض للاحتفاظ بالعملاء على مستوى المجموعة النموذجية أو عرض الحفاظ على المستخدمين على المستوى الفردي.
إنشاء عرض ترويجي للاحتفاظ بالمشتركين باستخدام واجهة Google Play Developer API
يمكنك أيضًا إنشاء عروض الاحتفاظ بالمشتركين وتعديلها آليًا. لإنشاء عرض ترويجي، يمكنك استدعاء الطريقة monetization.subscriptions.basePlans.offers.create. لتعديل العروض الحالية، يمكنك استدعاء الطريقة
monetization.subscriptions.basePlans.offers.patch أو
monetization.subscriptions.basePlans.offers.batchUpdate. تتيح الطرق الثلاث استخدام الحقول retentionRule وretentionPerUserRule وstartTime وendTime. في العنصر SubscriptionOffer، اضبط الحقول التالية:
-
offerId: معرّف العرض الترويجي الفريد للاحتفاظ بالمشتركين -
targeting: اضبط السمةretentionRuleعلى عنصرRetentionTargetingRuleيحدّد المستخدمين المؤهّلين للاستفادة من العرض. للاطّلاع على الحقول المتاحة، يُرجى مراجعة ضبط قواعد الأهلية للاحتفاظ بالبيانات. لاختيار المشتركين المؤهَّلين من الخلفية بدلاً من ذلك، اضبطretentionPerUserRule. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة استهداف مشتركين محدّدين بعروض ترويجية للحفاظ على اشتراكهم. -
phases[]: لا يتيح عرض الحفاظ على المشتركين سوى مرحلة أسعار واحدة. في هذه المرحلة، اضبط الحقول التالية:recurrenceCount: عدد المدد الزمنية للفوترة التي يستمر فيها الخصم، من 1 إلى 52. إذا كانت قيمةrecurrenceCountأكبر من 1، يجب أن تكون المرحلةdurationمساوية لمدة الفوترة في الخطة الأساسية.-
regionalConfigs[]: اضبط السمةrelativeDiscountعلى الخصم ككسر أكبر من 0 وأقل من 1. على سبيل المثال، استخدِم0.5لخصم %50. تتيح عروض الاحتفاظ بالعملاء استخدامrelativeDiscountفقط. لا تتوفّر مراحل السعر الثابت (price) ومبلغ الخصم الدقيق (absoluteDiscount) والمرحلة المجانية (free).
-
startTime: سمة اختيارية. الوقت الذي يصبح فيه عرض الاحتفاظ بالمشتركين متاحًا للمشتركين المؤهَّلين، كطابع زمني بتنسيق RFC 3339 لا يؤدي ضبط هذا الحقل إلى تفعيل العرض. في حال عدم ضبط هذا الحقل، يصبح العرض متاحًا استنادًا إلى حالته. -
endTime: سمة اختيارية. يشير هذا الحقل إلى الوقت الذي يتوقف فيه عرض الاحتفاظ بالمشتركين عن أن يكون متاحًا، وذلك كطابع زمني بتنسيق RFC 3339، بغض النظر عن حالة العرض. إذا لم يتم ضبط هذا الحقل، لن يكون للعرض تاريخ انتهاء. إذا ضبطت هذا الحقل، يجب أن يكون في المستقبل وبعدstartTime.
تنشئ طريقة monetization.subscriptions.basePlans.offers.create دائمًا العرض في الحالة DRAFT، حتى إذا ضبطت startTime. لتفعيل العرض، استدعِ الأسلوب monetization.subscriptions.basePlans.offers.activate.
ضبط قواعد أهلية الاحتفاظ بالبيانات
يحتوي عنصر RetentionTargetingRule على الحقول التالية:
-
scope: سمة مطلوبة الاشتراكات التي تأخذها القاعدة في الاعتبار بالنسبة إلى عروض الاحتفاظ بالمشتركين، القيمة الوحيدة المسموح بها هيthisSubscription، أي الاشتراك الذي يتم تحديد العرض فيه. اضبط هذا الحقل على{"thisSubscription": {}}. -
minDuration: سمة مطلوبة الحد الأدنى للمدة التي يجب أن يكون فيها المستخدم مشتركًا يدفع الرسوم ليكون مؤهلاً، كمدة ISO 8601 بالأيام، منP0DإلىP1826D. على سبيل المثال، استخدِمP90Dلمدة 90 يومًا. لعدم طلب حدّ أدنى لمدة الاشتراك المدفوع، اضبط هذا الحقل علىP0D. -
allowMultipleClaims: سمة اختيارية. ما إذا كان بإمكان المشترك الاستفادة من العرض أكثر من مرة إذا تم اختيارfalse، لن يكون المشترك الذي سبق له الاستفادة من هذا العرض مؤهلاً للاستفادة منه مرة أخرى. إذا كانت القيمة هيtrue، يمكن أن يصبح المشترك مؤهلاً مرة أخرى بعد مرور الوقت المحدّد فيminOfferCooldownDurationمنذ نهاية فترة الخصم في عرض الحفاظ على المشتركين السابق. القيمة التلقائية هيfalse. -
minOfferCooldownDuration: مطلوبة إذا كانت قيمةallowMultipleClaimsهيtrue. الحد الأدنى للوقت الذي يجب أن يمر بعد انتهاء فترة الخصم في عرض الاحتفاظ السابق قبل أن يصبح المشترك مؤهلاً مرة أخرى، كمدة ISO 8601 بالأيام، منP1DإلىP1826D. على سبيل المثال، استخدِمP180Dلمدة 180 يومًا. لا تضبط هذا الحقل إذا كانت قيمةallowMultipleClaimsهيfalseأو لم يتم ضبطها.
يوضّح المثال التالي الحقول startTime وendTime وtargeting
لكائن SubscriptionOffer لعرض الاحتفاظ بالمشتركين المتاح
للمشتركين الذين دفعوا لمدة 90 يومًا على الأقل، ويمكنهم المطالبة به مرة أخرى
بعد 180 يومًا من انتهاء خصم الاحتفاظ السابق:
{
"offerId": "retention-50off-2m",
"startTime": "2026-12-01T00:00:00Z",
"endTime": "2027-03-01T00:00:00Z",
"targeting": {
"retentionRule": {
"scope": {
"thisSubscription": {}
},
"minDuration": "P90D",
"allowMultipleClaims": true,
"minOfferCooldownDuration": "P180D"
}
}
}
استهداف مشتركين محدّدين بعروض الحفاظ على المشتركين
بدلاً من السماح لـ Google Play بتحديد الأهلية باستخدام
RetentionTargetingRule، يمكنك إتاحة عرض للاحتفاظ بالمشتركين فقط
الذين يختارهم نظامك الخلفي. على سبيل المثال، يمكنك استهداف المشتركين الذين يشير نموذج توقّع الإيقاف إلى أنّهم معرّضون لخطر الإيقاف، أو المشتركين الذين يبدأون عملية إلغاء الاشتراك في تطبيقك.
يظهر للمشتركين عرض مخصّص لكل مستخدم للحفاظ على المستخدمين، وذلك ضمن مسار إلغاء الاشتراك نفسه على Google Play مثل أي عرض ترويجي آخر، ويمكنك التعامل مع قبول العرض بالطريقة نفسها. لمعرفة التفاصيل، يُرجى الاطّلاع على التعامل مع أحداث عروض الحفاظ على المشتركين في الخلفية.
لاستهداف مشتركين محدّدين بعروض الاحتفاظ بالمشتركين، اتّبِع الخطوات التالية:
إنشاء عرض ترويجي للحفاظ على المستخدمين لكل مستخدم: عند استدعاء الإجراء
monetization.subscriptions.basePlans.offers.createأوmonetization.subscriptions.basePlans.offers.patchأوmonetization.subscriptions.basePlans.offers.batchUpdate، اضبط السمةtargetingعلى عنصرretentionPerUserRuleبدلاً من عنصرretentionRule. لا يحتوي عنصرRetentionPerUserTargetingRuleعلى أي حقول. يمكن أن يستخدم العرض إماretentionRuleأوretentionPerUserRule، ولكن ليس كليهما.{ "offerId": "retention-peruser-30off", "targeting": { "retentionPerUserRule": {} } }فعِّل العرض قبل استهداف المشتركين به. إذا طلبت طريقة
activateOfferTargetingلعرض لم يتم تفعيله من قبل، سيتعذّر الطلب وسيظهر رمز حالة HTTP400 Bad Requestوحالة الخطأINVALID_ARGUMENT. لمعرفة التفاصيل، يُرجى الاطّلاع على التعامل مع أخطاء الاستهداف. وحتى عندما يكون العرض نشطًا، لا يعرضه Google Play إلا للمشتركين الذين تستهدف اشتراكاتهم في الخطوة التالية.استهداف العرض الترويجي لاشتراك معيّن استدعِ الطريقة
purchases.subscriptionsv2.activateOfferTargetingباستخدام اسم حزمة تطبيقك وpurchaseTokenالاشتراك وofferIdعرض الحفاظ على المستخدمين:POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/subscriptionsv2/tokens/{purchaseToken}:activateOfferTargeting { "offerId": "retention-peruser-30off" }يعرض الطلب الناجح رمز الحالة HTTP
204 No Contentبدون نص استجابة. يخزّن Google Play الاستهداف مع الاشتراك، لذا لا تحتاج إلى طلب واجهة برمجة التطبيقات في وقت إلغاء المشترك. في المرة التالية التي يبدأ فيها المشترك عملية الإلغاء في Google Play، يمكن لـ Google Play عرض العرض الترويجي، طالما أنّ الاشتراك يستوفي متطلبات الأهلية. يحلّ الاستهداف لكل مستخدم محلّ قواعد الأهلية التي يحدّدهاretentionRuleفقط. وستظل سارية جميع متطلبات الأهلية الأخرى وعمليات التحقّق التي يجريها Google Play على مستوى المنصة، مثل متطلبات الامتثال الإقليمية.يمكنك استهداف أكثر من عرض واحد للحفاظ على المستخدمين لكل مستخدم في الاشتراك نفسه. لإجراء ذلك، استدعِ طريقة
activateOfferTargetingمرة واحدة لكل عرض. سيواصل Google Play عرض عرض ترويجي واحد على الأكثر للاحتفاظ بالمشتركين في مسار الإلغاء. لمعرفة تفاصيل حول كيفية اختيار Google Play للعرض، يُرجى الاطّلاع على مقالة ضبط عروض الحفاظ على المشتركين.الطريقة
activateOfferTargetingهي طريقة متكررة. إذا طلبت ذلك لعرض يستهدفه الاشتراك حاليًا، سينجح الطلب وسيعدّل Google Play قيمةactivateTimeللعرض إلى وقت آخر طلب.أزِل الاستهداف عند الحاجة. إذا أردت عدم تلقّي أحد المشتركين للعرض، مثلاً بسبب تغيُّر احتمالية توقّفه عن الاشتراك، يمكنك طلب طريقة
purchases.subscriptionsv2.deactivateOfferTargetingباستخدام اسم الحزمة نفسه وpurchaseTokenوofferId. يعرض الطلب الناجح رمز الحالة HTTP204 No Contentبدون نص استجابة.تتسم طريقة
deactivateOfferTargetingأيضًا بأنّها متكررة. إذا لم يكن العرض مستهدفًا للاشتراك، على سبيل المثال لأنّك لم تفعّل الاستهداف مطلقًا، سينجح الطلب ولن يكون له أي تأثير.
ينطبق الاستهداف على purchaseToken واحد ولا تنتهي صلاحيته طالما أنّ الاشتراك نشط ويتم تجديده تلقائيًا. ويظلّ في مكانه بعد أن يرى المشترك
العرض أو يقبله أو يرفضه. ولا يزيلها Google Play إلا عند استدعاء
الطريقة deactivateOfferTargeting أو بعد 60 يومًا من انتهاء صلاحية
الاشتراك. إذا أدى تغيير الخطة أو إعادة الاشتراك إلى إنشاء purchaseToken جديد، لن يتم نقل الاستهداف.
لمعرفة عروض الحفاظ على المستخدمين المخصّصة لكل مستخدم والموجّهة إلى اشتراك معيّن، يمكنك استدعاء الإجراء purchases.subscriptionsv2.get. يسرد الحقل developerTargetedOffers لكل بند إعلاني العروض المستهدَفة. يحتوي كل إدخال على
offerId وactivateTime عند تفعيل الاستهداف:
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"developerTargetedOffers": [
{
"offerId": "retention-peruser-30off",
"activateTime": "2026-12-03T15:04:05Z"
}
]
}
]
}
التعامل مع أخطاء الاستهداف
عندما يتعذّر طلب الطريقة activateOfferTargeting أو deactivateOfferTargeting، تحتوي الاستجابة على رمز حالة HTTP وحالة خطأ تصف السبب. يسرد الجدول التالي رموز حالة HTTP وحالات الخطأ التي يمكن أن تعرضها هذه الطرق:
| رمز حالة HTTP | حالة الخطأ | الطرق | السبب |
|---|---|---|---|
404 Not Found |
NOT_FOUND |
كلاهما | purchaseToken غير متوفّر. |
400 Bad Request |
INVALID_ARGUMENT |
activateOfferTargeting |
لا يتوفّر offerId في الخطة الأساسية الحالية للاشتراك، أو لا يزال العرض في حالة المسودة ولم يتم تفعيله مطلقًا. |
400 Bad Request |
FAILED_PRECONDITION |
activateOfferTargeting |
لم يتم ضبط السمة targeting للعرض على
retentionPerUserRule. |
400 Bad Request |
FAILED_PRECONDITION |
activateOfferTargeting |
انتهت صلاحية الاشتراك. |
لا تتحقّق طريقة activateOfferTargeting مما إذا كان الاشتراك غير منتهي الصلاحية مؤهلاً للاستفادة من العرض. على سبيل المثال، إذا تم إلغاء الاشتراك ولكن لم تنتهِ صلاحيته بعد، يتم تنفيذ الطلب بنجاح ويخزّن متجر Google Play الاستهداف. يقيّم Google Play أهلية الاشتراك عندما يبدأ المشترك في إجراءات سير عملية الإلغاء.
التعامل مع أحداث عروض الاحتفاظ بالمشتركين في الخلفية
عندما يقبل المشترك عرضًا ترويجيًا للاحتفاظ بالمشتركين، وعندما يتم تجديد الاشتراك بسعر مخفَّض لاحقًا، يرسل Google Play إشعارات RTDN إلى الخلفية. بعد تلقّي كل إشعار، يمكنك استدعاء الأسلوب purchases.subscriptionsv2.get باستخدام purchaseToken من الإشعار للحصول على أحدث حالة للاشتراك.
لا يؤدي قبول عرض ترويجي للاحتفاظ بالمشتركين إلى إنشاء عملية شراء جديدة. يظل purchaseToken
كما هو، لذا لا تحتاج إلى إعلامنا باستلام رسوم الاشتراك مرة أخرى، ولا ينشئ Google
Play رمز linkedPurchaseToken. الإبقاء على إذن الوصول الحالي للمشترك يُرجى معالجة طلب التجديد المخفَّض بالطريقة نفسها التي يتم بها تجديد أي اشتراك آخر.
| نوع الإشعار | وقت إرسال البيانات | الإجراءات المطلوبة |
|---|---|---|
SUBSCRIPTION_PLAN_TRANSITION_UPDATED (21) |
عندما يقبل المشترك عرضًا للاحتفاظ به في مسار الإلغاء | استدعِ الطريقة purchases.subscriptionsv2.get وتحقَّق من
planTransitionDetails. قيمة العمود "transitionState" هي
IN_PROGRESS. يظل الاشتراك نشطًا ويتم تجديده تلقائيًا، لذا يجب الاستمرار في منح إذن الوصول. |
SUBSCRIPTION_RENEWED (2) |
عند انتهاء مدة الفوترة الحالية وتجديد الاشتراك بسعر عرض الاحتفاظ بالمشتركين المخفَّض | استدعِ طريقة purchases.subscriptionsv2.get، وتأكَّد من أنّ offerDetails.offerId هو معرّف عرض الاحتفاظ بالمشتركين وأنّ planTransitionDetails لم يعُد متوفّرًا، ومدِّد فترة وصول المشترك إلى expiryTime الجديد. |
يحتوي عنصر planTransitionDetails على الحقول التالية:
-
productId: معرّف المنتج للخطة التي ينتقل إليها الاشتراك بالنسبة إلى عرض الاحتفاظ بالمشتركين، يكون هذا هو المنتج نفسه. -
basePlanId: معرّف الخطة الأساسية التي ينتقل إليها الاشتراك -
offerId: معرّف عرض الحفاظ على المشتركين الذي قبله المشترك. استخدِم هذا الحقل لتحديد عرض الاحتفاظ بالمشتركين الذي تم تحصيل قيمته. -
transitionInfo.transitionState: حالة عملية النقل بالنسبة إلى عروض الاحتفاظ بالمشتركين، تكون الحالةIN_PROGRESSأثناء انتظار عملية الانتقال. -
transitionInfo.expectedTransitionTime: الوقت المتوقّع لبدء سريان شروط عرض الاحتفاظ بالمشتركين
يتضمّن Google Play "planTransitionDetails" فقط عندما تكون عملية النقل
قيد الانتظار. عند تجديد الاشتراك بسعر عرض الاحتفاظ بالعملاء المخفَّض،
تكتمل عملية الانتقال ويزيل Google Play planTransitionDetails من
استجابة purchases.subscriptionsv2.get. منذ ذلك الحين، يعرض البند نفسه
خصم الاحتفاظ النشط:
-
offerDetails.offerIdهو معرّف عرض الاحتفاظ بالمشتركين الذي تم قبوله. -
offerPhaseهو{"introductoryPrice": {}}خلال مُدد الفوترة التي تم تطبيق الخصم عليها. بعد انتهاء مُدد الفوترة المخفَّضة وتجديد الاشتراك بالسعر العادي للخطة الأساسية، تتغيّر قيمةofferPhaseإلى{"basePrice": {}}.
الردّ بعد قبول المشترك للعرض
بعد قبول المشترك لعرض الاحتفاظ، تستمر مدة الفوترة الحالية
بدون تغيير. يعرض العنصر planTransitionDetails عملية النقل المجدوَلة
باستخدام transitionState من IN_PROGRESS:
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"expiryTime": "2026-12-15T10:00:00Z",
"offerDetails": {
"basePlanId": "monthly-base"
},
"autoRenewingPlan": {
"autoRenewEnabled": true,
"planTransitionDetails": {
"productId": "premium_monthly_sub",
"basePlanId": "monthly-base",
"offerId": "retention-50off-2m",
"transitionInfo": {
"transitionState": "IN_PROGRESS",
"expectedTransitionTime": "2026-12-15T10:00:00Z"
}
}
}
}
]
}
الردّ بعد التجديد بسعر مخفَّض
بعد مرور تاريخ التجديد وتحصيل السعر المخفَّض من المشترك، يعرض offerDetails.offerId عرض الاحتفاظ بالمشتركين، ويعرض offerPhase introductoryPrice، ولا يتضمّن الردّ بعد ذلك planTransitionDetails:
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"expiryTime": "2027-01-15T10:00:00Z",
"offerDetails": {
"basePlanId": "monthly-base",
"offerId": "retention-50off-2m"
},
"offerPhase": {
"introductoryPrice": {}
},
"autoRenewingPlan": {
"autoRenewEnabled": true,
"recurringPrice": {
"currencyCode": "USD",
"units": "9",
"nanos": 990000000
}
}
}
]
}
التفاعلات خلال مراحل النشاط
يُرجى مراعاة السلوكيات التالية عند التعامل مع عروض الاحتفاظ بالمشتركين:
- انتهاء الخصم: بعد انتهاء مُدد الفوترة المخفَّضة، يتم تجديد الاشتراك تلقائيًا بسعر الخطة الأساسية العادي. ستتلقّى إشعارًا من
SUBSCRIPTION_RENEWED، كما هو الحال مع أي تجديد آخر، وستتغيّر قيمةofferPhaseفي البند الإعلاني إلى{"basePrice": {}}. وليس على المشترك اتخاذ أي إجراء. - استرداد الدفعة بعد انتهاء الخصم: إذا تم رفض تجديد الاشتراك بسعر الخطة الأساسية العادي بعد انتهاء الخصم ودخل الاشتراك في فترة سماح أو تعليق الاشتراك، يتم تحصيل سعر الخطة الأساسية العادي عند استرداد الدفعة. لا يطبّق Google Play الخصم المكتمل لعرض الحفاظ على المشتركين. إذا تم رفض دفعة التجديد الأولى بالسعر المخفَّض، يتم الاحتفاظ بعملية الانتقال المعلَّقة، ويتم تطبيق سعر عرض الاحتفاظ بالمشتركين عند استرداد الدفعة.
- الفوترة المؤجَّلة: إذا طلبت طريقة
purchases.subscriptionsv2.deferأثناء انتقال عرض الحفاظ على المشتركين إلى الحالةIN_PROGRESS، يتم الاحتفاظ بعملية الانتقال المعلّقة وتطبيقها عند التجديد المؤجَّل. للحصول على تاريخ التجديد الجديد، يُرجى الاطّلاع علىexpiryTimeالخاص بالبند الإعلاني. - تغيير الخطة قبل الانتقال: لا يسري عرض الاحتفاظ بالمشتركين إلا على
purchaseTokenالاشتراك الذي قبله المشترك. إذا بدّل المشترك إلى خطة أساسية أو اشتراك مختلف قبلexpectedTransitionTime، ينشئ Google Play رمزًا مميزًا جديدًا للشراء ويلغي عملية الانتقال المُجدوَلة ويمحوplanTransitionDetails. ولا ينطبق عرض الاحتفاظ بالمشتركين المعلّق على الخطة الجديدة. - الإلغاء والاستعادة: إذا ألغى المشترك اشتراكه بعد
قبول عرض الاحتفاظ بالمشتركين، تظل عملية الانتقال المُجدوَلة في انتظار المراجعة
ويظل
transitionStateIN_PROGRESS. إذا استعاد المشترك الاشتراك قبل انتهاء صلاحيته، سيظل خصم عرض الاحتفاظ بالمشتركين ساريًا عند التجديد. - انتهاء الصلاحية وإعادة الاشتراك: إذا انتهت صلاحية الاشتراك بدون استعادته، يلغي Google Play عملية الانتقال المعلَّقة. إذا أعاد المستخدم الاشتراك أو اشترك مرة أخرى لاحقًا، ينشئ Google Play عملية شراء اشتراك جديدة، ولا يسري عرض الاحتفاظ بالمشتركين الذي تم قبوله سابقًا.
- تغييرات العروض: إذا غيّرت الخصم أو مُدد الفوترة لعرض الحفاظ على المشتركين، لن ينطبق التغيير إلا على عمليات الاستفادة من العرض في المستقبل. ويحتفظ المشتركون الذين سبق لهم قبول العرض بالبنود الأصلية.
- إيقاف العرض الترويجي: في حال إيقاف عرض ترويجي للحفاظ على المشتركين أو انتهاء صلاحيته، يحتفظ المشتركون الذين قبلوه بالشروط التي وافقوا عليها. سيظل المشتركون الذين لديهم عملية انتقال من
IN_PROGRESSيحصلون على الخصم عند التجديد التالي، وسيحتفظ المشتركون الذين هم في فترات الفوترة المخفَّضة بالخصم طوال المدة المتفق عليها. - تغييرات الأسعار: تظلّ تغييرات أسعار الخطة الأساسية سارية. لا ينقل Google Play المشترك إلى سعر جديد إلا إذا كان المشترك يدفع السعر العادي ولم يكن لديه عرض ترويجي معلّق للاحتفاظ به. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تغيير أسعار الاشتراك.
- ردّ الأموال: يمكنك ردّ الأموال إلى المشترك باستخدام واجهات برمجة التطبيقات العادية لردّ الأموال وإلغاء الاشتراك، مثل طريقة
purchases.subscriptionsv2.revoke. يؤدي هذا الإجراء إلى ردّ الأموال المدفوعة في آخر دفعة وإنهاء وصول المشترك إلى المحتوى.
اختبار عروض الحفاظ على المشتركين
لا يعرض Google Play سوى عروض الاحتفاظ بالمشتركين النشطة في مسار الإلغاء، ويقيّم قواعد الأهلية في الوقت الفعلي. لاختبار عروض الاحتفاظ بالمشتركين باستخدام حساب مختبِر حائز على ترخيص، اتّبِع إحدى الطريقتَين التاليتَين:
- اختبِر عرضًا ترويجيًا للحفاظ على المستخدمين في خطة أساسية للإصدار العلني، بدون إظهار العرض للمشتركين الحقيقيين.
- اختبِر عرض الاحتفاظ بالمشتركين المستنِد إلى قاعدة في تطبيق تجريبي أو في خطة أساسية تجريبية لا يمكن لمستخدمي الإصدار العلني الوصول إليها.
قبل استخدام أيّ من الطريقتَين، انتقِل إلى الإعدادات > اختبار الترخيص في Google Play Console وأضِف حساب Google الاختباري كمختبِر للترخيص.
اختبار عرض الحفاظ على المستخدمين على المستوى الفردي
يعرض Google Play عرضًا ترويجيًا للحفاظ على المستخدمين لكل مستخدم على حدة، وذلك للاشتراكات التي تستهدفها فقط، حتى تتمكّن من اختباره على خطة أساسية في مرحلة الإنتاج بدون عرضه على المشتركين الفعليين. لاختبار عرض ترويجي مخصّص لكل مستخدم، اتّبِع الخطوات التالية:
- أنشِئ عرضًا ترويجيًا للحفاظ على المستخدمين لكل مستخدم ضِمن الخطة الأساسية، ثم فعِّله. في Google Play Console، اختَر عرض الاحتفاظ بالمشتركين على مستوى المستخدم.
باستخدام Google Play Developer API، اضبط
targetingعلى عنصرretentionPerUserRule. لمعرفة التفاصيل، يُرجى الاطّلاع على استهداف مشتركين محدّدين بعروض ترويجية للحفاظ على اشتراكهم. - إذا فعّلت العرض للتو، يُرجى الانتظار لمدة تتراوح بين 10 و15 دقيقة حتى يتم تطبيق التغيير، ثم محو ذاكرة التخزين المؤقت لتطبيق "متجر Google Play".
- على جهاز الاختبار، سجِّل الدخول باستخدام حساب مختبِر الترخيص، ثم اشترِ الخطة الأساسية في تطبيقك.
- من الخلفية، يمكنك استدعاء الطريقة
purchases.subscriptionsv2.activateOfferTargetingباستخدام اسم حزمة تطبيقك، وpurchaseTokenالخاص بمختبِر الترخيص، وofferIdعرض الاحتفاظ بالمشتركين. - في تطبيق "متجر Google Play"، انتقِل إلى الدفعات والاشتراكات > الاشتراكات، واختَر الاشتراك، ثم انقر على إلغاء الاشتراك. يظهر عرض الاحتفاظ بالمشتركين في مسار الإلغاء.
- اقبل العرض، ثم تأكَّد من أنّ الخلفية تتلقّى
إشعار RTDN الخاص بـ
SUBSCRIPTION_PLAN_TRANSITION_UPDATEDوتعالج عملية التجديد بسعر مخفَّض.
اختبار عرض للاحتفاظ بالعملاء مستند إلى القواعد
بعد تفعيل عرض ترويجي للاحتفاظ بالمشتركين يستند إلى القواعد، يمكن لـ Google Play عرضه لأي مشترك مؤهَّل في الخطة الأساسية. لتجنُّب عرض العرض الترويجي لمستخدمي الإصدار العلني، اختبِره في تطبيق اختباري غير مخصّص للإصدار العلني أو في خطة أساسية اختبارية مخصّصة لا يمكن لمستخدمي الإصدار العلني الوصول إليها. لاختبار عرض ترويجي للاحتفاظ بالمشتركين مستند إلى قواعد، اتّبِع الخطوات التالية:
- في تطبيقك التجريبي أو خطتك الأساسية التجريبية، أنشئ عرضًا ترويجيًا للاحتفاظ بالمشتركين مستندًا إلى القواعد، واضبط
minDurationعلىP0D(0 يوم). في Google Play Console، اختَر عرض الاحتفاظ بالمشتركين على مستوى المجموعة النموذجية. باستخدام واجهة Google Play Developer API، اضبطtargetingعلى عنصرretentionRule. لمعرفة التفاصيل، يُرجى الاطّلاع على ضبط قواعد أهلية الاحتفاظ بالبيانات. - فعِّل العرض، وانتظِر من 10 إلى 15 دقيقة حتى يتم نشر التغيير، ثم امسح ذاكرة التخزين المؤقت لتطبيق "متجر Google Play".
- على جهاز الاختبار، سجِّل الدخول باستخدام حساب مختبِر الترخيص، ثم اشترِ الخطة الأساسية الاختبارية.
- في تطبيق "متجر Google Play"، انتقِل إلى الدفعات والاشتراكات > الاشتراكات، واختَر الاشتراك، ثم انقر على إلغاء الاشتراك. بما أنّ العرض لا يتطلّب حدًا أدنى لمدة الاشتراك المدفوع، يمكنك بدء عملية الإلغاء بعد الشراء مباشرةً. يظهر عرض الاحتفاظ بالمشتركين في خطوات الإلغاء.
- اقبل العرض، ثم تأكَّد من أنّ الخلفية تتلقّى
إشعار RTDN الخاص بـ
SUBSCRIPTION_PLAN_TRANSITION_UPDATEDوتعالج عملية التجديد بسعر مخفَّض.
بعد التحقّق من عملية الدمج، أنشِئ عرض الاحتفاظ بالمشتركين المستنِد إلى القواعد وفعِّله في خطتك الأساسية في مرحلة الإنتاج.
تحديد المشاكل وحلّها في اختبار عروض الاحتفاظ بالمشتركين
إذا لم يظهر عرض الاحتفاظ بالمشتركين، يُرجى التحقّق مما يلي:
- عرض الاحتفاظ بالمشتركين نشط، والوقت الحالي يقع بين
startTimeوendTime، إذا ضبطتهما. - بالنسبة إلى عرض الحفاظ على المستخدمين على المستوى الفردي، يتضمّن الحقل
developerTargetedOffersفي استجابةpurchases.subscriptionsv2.getلـpurchaseTokenالخاص بمختبِر الترخيص العرض. - أن يكون الاشتراك فرديًا، وليس اشتراكًا يتضمّن ميزات إضافية
- ألا يكون الاشتراك في فترة سماح أو معلّقًا أو متوقفًا مؤقتًا.
- لا يتضمّن الاشتراك أي تغيير في الخطة أو السعر في انتظار المراجعة.
- وسيتم التجديد التالي بسعر الخطة الأساسية العادي. بالنسبة إلى الفترات التجريبية المجانية والعروض التمهيدية، لا يتوفّر عرض الاحتفاظ بالمشتركين إلا خلال مدة الفوترة النهائية من الفترة التجريبية أو المرحلة التمهيدية.
- انتظرت لمدة تتراوح بين 10 و15 دقيقة بعد تفعيل العرض الترويجي أو تغييره، ومحوت ذاكرة التخزين المؤقت لتطبيق "متجر Google Play".