مراحل نشاط الاشتراك

يمكن أن تمر عمليات شراء الاشتراكات خلال عدة ولايات مختلفة اعتمادًا على عدة عوامل، منها سلوك التجديد التلقائي والدفع ومواقف الرفض وإجراءات إدارة المطورين.

معالجة دورة حياة الاشتراكات التي يتم تجديدها تلقائيًا

عندما تتغير حالة اشتراك أحد المستخدمين، يتلقى خادم الخلفية رسالة SubscriptionNotification

الشكل 1. حالات مراحل النشاط والأحداث الانتقالية عمليات شراء الاشتراكات التي يتم تجديدها تلقائيًا

لتعديل الحالة في الخلفية، يُرجى طلب purchases.subscriptionsv2.get واجهة برمجة التطبيقات مع الرمز المميّز للشراء المضمّن في الإشعار توفر نقطة النهاية هذه آخر حالة اشتراك بالنظر إلى رمز الشراء المميز مصدرًا أساسيًا لإدارة الاشتراكات

يكون الرمز المميز للشراء صالحًا من الاشتراك في الاشتراك حتى 60 يومًا بعد انتهاء الصلاحية. بعد هذا التاريخ، لن يصبح الرمز المميّز للشراء صالحًا للاستخدام: عن طريق الاتصال بواجهة برمجة تطبيقات Google Play Developer API.

عمليات شراء الاشتراكات الجديدة التي يتم تجديدها تلقائيًا

عندما يشتري مستخدم اشتراكًا، ستظهر رسالة SubscriptionNotification مع النوع SUBSCRIPTION_PURCHASED يتم إرساله إلى عميل RTDN. ما إذا تلقيت هذا الإشعار أو أنك تسجّل عملية شراء جديدة داخل التطبيق من خلال PurchasesUpdatedListener أو جلب المشتريات يدويًا في طريقة onResume() التطبيق، يجب معالجة عملية الشراء الجديدة في الخلفية. لإجراء هذا، اتبع هذه الخطوات:

  1. الاستعلام عن purchases.subscriptionsv2.get نقطة نهاية للحصول على اشتراك المرجع يتضمّن آخر حالة اشتراك
  2. تأكد من أن قيمة subscriptionState هو SUBSCRIPTION_STATE_ACTIVE.
  3. تأكيد عملية الشراء
  4. امنح المستخدم إذن الوصول إلى المحتوى. إنّ حساب المستخدِم المرتبط عملية الشراء من خلال ExternalAccountIdentifiers من مورد الاشتراك إذا تم ضبط المعرّفات عند الشراء وقت استخدام setObfuscatedAccountId أو setObfuscatedProfileId

تتضمّن مكتبة فوترة Play أيضًا طريقة لتأكيد الاشتراك acknowledgePurchase()، وطريقة للتحقق من حالة الإقرار isAcknowledged() ومع ذلك، ننصحك بمعالجة عمليات الشراء في الخلفية للحصول على أمان أفضل.

يبدو مورد الاشتراك لعمليات الشراء الجديدة مشابهًا لما يلي: مثال:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_PENDING", // need to acknowledge new purchases
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

عمليات تجديد الاشتراك

بالنسبة إلى الاشتراكات غير القابلة للتقسيط والتجديد التلقائي: SUBSCRIPTION_RENEWED يتم إرسال إشعار عند تجديد الاشتراك. للتقسيط الاشتراكات، يتم إرسال إشعار SUBSCRIPTION_RENEWED في كل مرة يتم تحصيل رسوم الاشتراك في تاريخ الفوترة المحدد. تأكد من أن المستخدم لا يزال التي يحق لها الاشتراك ثم تحديث حالة الاشتراك مبلغ expiryTime المقدَّم في الاشتراك المصدر الذي تم إرجاعه من Google Play واجهة برمجة التطبيقات Developer API. يبدو مورد الاشتراك مشابهًا للمثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ]
}

لا تحتاج إلى الإقرار بتجديد الاشتراك.

فترة السماح

في حال حدوث مشاكل في الدفع أثناء تجديد الاشتراك، تُرسِل Google إشعارًا إلى المستخدم ويحاول بشكل دوري تجديد الاشتراك لبعض الوقت قبل بانتهاء صلاحية الاشتراك. يمكن أن تتكون فترة الاسترداد هذه من فترة سماح متبوعة بفترة تعليق الاشتراك. أثناء فترة السماح، على المستخدم يمكنهم الوصول إلى إذن استخدام الاشتراك

تشير رسالة الأشكال البيانية queryPurchasesAsync() إرجاع المشتريات التي لا تزال في فترة السماح. إذا كان تطبيقك وحدها على queryPurchasesAsync للتحقّق مما إذا كان المستخدم يحق له الحصول على الاشتراك، فسيتعامل تطبيقك تلقائيًا مع فترات السماح، لأن تظهر هذه الاشتراكات على أنّها نشِطة في Play Billing Library.

من خلال مزامنة حالة الاشتراك مع الخلفية، يمكنك أن تكون أكثر وعيًا. من عمليات رفض الدفعات، ويمنحك سياقًا إضافيًا عند محاولة الحد من الخسارة الإجبارية انسحاب أحد العملاء. الاستماع إلى SubscriptionNotification رسالة من النوع SUBSCRIPTION_IN_GRACE_PERIOD ليتم إخطار المستخدم عند إدخال فترة السماح. وعندما يكون المستخدم في فترة السماح، لن يتمكن الاشتراك المرجع يحتوي على autoRenewEnabled = true. يعمل Google Play على توسيع نطاق expiryTime حتى انتهاء فترة السماح بسبب الاستحقاق إلى أن يلغي المستخدم اشتراكه أو تستمر فترة السماح الحد الأقصى للطول. قيمة الحقل subscriptionState خلال هذه الفترة هي SUBSCRIPTION_STATE_IN_GRACE_PERIOD يبدو مورد الاشتراك مشابهًا في المثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_IN_GRACE_PERIOD",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_future,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

يُعلِم Play المستخدمين الذين هم في فترة السماح برفض عملية الدفع. ويطلب منهم حل مشاكل طريقة الدفع في "متجر Play". عندما دخول المستخدم في فترة سماح، فيجب عليك أيضًا تشجيع المستخدم على إصلاح طريقة الدفع في حال كان الإخفاق إجباريًا. هناك طريقة مباشرة للقيام وهي استخدام ميزة المراسلة داخل التطبيق API. في حال استدعاء واجهة برمجة التطبيقات هذه عندما يفتح المستخدم تطبيقك، ستظهر له رسالة Play في شريط إعلام منبثق يخبر المستخدم برفض الدفع. هذه الرسالة تتضمّن أيضًا رابطًا لصفحة في التطبيق ليتمكّن المستخدم من تصحيح طريقة الدفع على Google اللعب.

عندما يصلح المستخدم طريقة الدفع، يتم تجديد الاشتراك مع تاريخ التجديد الأصلي، ويمكنك معالجة التجديد على النحو الموضَّح في عمليات التجديد:

إذا لم يقم المستخدم بإصلاح طريقة الدفع خلال فترة السماح، يجب يدخل الاشتراك في فترة تعليق الاشتراك، ويفقد الاستحقاق.

الوصول إلى فترة السماح واستردادها

يوضح الشكل 2 مخططًا زمنيًا للاشتراك الذي يدخل في فترة سماح ثم يتم استردادها عندما يصلح المستخدم طريقة الدفع. بعد فترة السماح ينتهي، يُفترَض أن يفقد المستخدم مزايا الاشتراك وأن يدخل في فترة تعليق الاشتراك.

الشكل 2. المخطط الزمني للاشتراك الذي يدخل في فترة سماح الدورة الشهرية وتتعافى قبل انتهائها.

من المهم تذكر النقاط التالية:

  • خلال فترة السماح، يجب أن يحتفظ المستخدم بإمكانية الوصول إلى مزايا الاشتراك.
  • عندما يتم استرداد اشتراك خلال فترة السماح، يُحفَظ تاريخ التجديد لم تتم إعادة ضبطه.
  • في حال زيادة فترة السماح - على سبيل المثال، من 7 أيام إلى 14 يومًا - المستخدمون الذين في فترة السماح، يمكنهم الحصول على إمكانية وصول إضافي إلى مزايا الاشتراك.
  • في حال تقليل فترة السماح، سيحصل المستخدمون الذين لم يصلوا إلى فترة السماح القديمة بما يكفي فترة السماح الجديدة لتجاوز فترة السماح الجديدة على الفور. على سبيل المثال، إذا قمت بتقليل فترة السماح من 14 يومًا إلى 7 أيام، فالمستخدمون خلال الفترة من 8 إلى 14 من فترة السماح القديمة وإبطال مزايا اشتراكهم على الفور.
  • يظل الاشتراك في حالة نشطة ولن تحصل على فترة سماح. فترة ”مراسلة نصية في الوقت الفعلي“ حتى انتهاء فترة السماح الصامتة

فترة السماح الصامتة

يمكنك ضبط فترة سماح لتكون 0 يوم، ولكن سينتظر Play لمدة يوم واحد على الأقل ضمان الوقت الكافي لمحاولات الدفع. تقدم فترة السماح الصامتة هذه شبكة أمان لمعالجة عمليات الدفع. خلال هذه الفترة التي تبلغ 24 ساعة يبقى اشتراكك في حالة ACTIVE.

أفضل طريقة للبقاء على اطّلاع دائم على تغييرات حالة الاشتراك هي الاستماع إلى إشعارات المطوّرين في الوقت الفعلي (RTDN) والتفاعل معها عليك استدعاء purchases.subscriptionsv2.get() في وقت RTDN بدلاً من وقت انتهاء الصلاحية للحصول على بيانات أكثر دقة حالة الاشتراك.

استنادًا إلى حالة الاشتراك بعد فترة السماح الصامتة التي تبلغ مدتها 24 ساعة ستتلقى أحد الإشعارات التالية:

  • SUBSCRIPTION_ON_HOLD (في حال تفعيله)
  • SUBSCRIPTION_CANCELED (في حال الإلغاء)
  • SUBSCRIPTION_EXPIRED (في حال انتهاء صلاحيته)
  • SUBSCRIPTION_RENEWED (في حال التجديد بنجاح)

ويمكنك أيضًا استدعاء طريقة subscriptionV2.get() في أي وقت بعد فترة سماح صامتة لمدة 24 ساعة للاطّلاع على أحدث حالة للاشتراك.

تعليق الحساب

في حال حدوث مشاكل في الدفع في تجديد الاشتراك بعد أي فترة السماح الفترة، وبدأت فترة تعليق الاشتراك. عندما يدخل الاشتراك فترة تعليق الاشتراك، فيجب حظر الوصول إلى الاشتراك الوصول.

عليك مواصلة معالجة أيّ عمليات إلغاء خلال فترة تعليق الاشتراك. عمليات استعادة اشتراكاتك أو إعادة شرائها حسب الحاجة لأنه يمكن للمستخدم إجراء هذه التغييرات أثناء اشتراك معلّقة.

تُعلمك شبكات RTDN عندما يدخل المستخدم فترة تعليق الاشتراك، حتى تتمكّن من إعلامك في أقرب وقت ممكن عن سبب تعليق وصولهم إلى الاشتراك. ومن الطرق المباشرة لإجراء ذلك استخدام ميزة المراسلة داخل التطبيق API. يتطلب الاتصال بواجهة برمجة التطبيقات هذه عند عندما يفتح المستخدِم التطبيق، سيعرض رسالة للمستخدم في شريط نصي مؤقت لإبلاغه برفض الدفعة. تتضمن هذه الرسالة أيضًا رابط لصفحة في التطبيق يمكن للمستخدم من خلاله تصحيح طريقة الدفع على Google Play.

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

لا يتم إرجاع الاشتراك من خلال queryPurchasesAsync() أثناء فترة تعليق الاشتراك، لذلك إذا كان تطبيقك يعتمد على هذه الطريقة لعرض عمليات الشراء الحالية، فينبغي عليك دعم فترة تعليق الاشتراك بشكل افتراضي.

مع مطوّر في الوقت الفعلي الإشعارات، ستتلقى رسالة SubscriptionNotification من النوع SUBSCRIPTION_ON_HOLD عند دخول الاشتراك في فترة تعليق الاشتراك اتصل الـ purchases.subscriptionsv2.get من خادم الخلفية الآمن لاسترداد الاشتراك الجديد المعلومات. أثناء فترة تعليق الاشتراك في الحقل expiryTime ضمن الاشتراك المرجع على طابع زمني من الماضي، والحقل subscriptionState على SUBSCRIPTION_STATE_ON_HOLD:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ON_HOLD",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_past,
      ...
    }
  ],
}

لاستعادة إمكانية الوصول إلى البيانات، على المستخدمين تصحيح معلومات طريقة الدفع. يُعلِم Play المستخدمين في تعليق حسابه على رفض الدفعة، كما ننصحك بتشجيعه على حل طريقة الدفع التي اختاروها.

بعد تصحيح المستخدم لطريقة الدفع، يعود الاشتراك إلى وضع نشط. وينبغي عليك بعد ذلك استعادة إمكانية الدخول إلى المحتوى الذي اشتركت فيه. وفي هذه الحالة، وأن الرمز المميّز للشراء هو نفسه الذي كان عليه قبل بدء فترة تعليق الاشتراك بسبب استرداد عملية الشراء نفسها، وتتلقى RTDN SUBSCRIPTION_RECOVERED

بالنسبة إلى الاشتراكات المستندة إلى الأقساط، قد يتم رفض الدفعات واستردادها في لأي محاولة دفع فردية.

بعد استرداد الاشتراك، تُرجع Play Billing Library الاشتراك مرة أخرى من خلال طريقة queryPurchasesAsync(). إذا استخدمت هذه الطريقة لتحديد ما إذا يحقّ للمستخدم الحصول على اشتراك، فيجب أن يتعامل تطبيقك تلقائيًا استرداد الاشتراك بعد تجاوز فترة تعليق الاشتراك

الاستماع إلى رسالة SubscriptionNotification من النوع SUBSCRIPTION_RECOVERED ليتم إرسال إشعار عند انتهاء مدة الاشتراك استرداده ويجب على المستخدم استعادة إمكانية الوصول. في حال طلب اشتراك بعد تلقّي هذا الإشعار، يتم ضبط الحقل expiryTime على طابع زمني. في المستقبل ويتم ضبط الحقل subscriptionState على SUBSCRIPTION_STATE_ACTIVE مرة أخرى:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      ...
    }
  ],
}

إذا لم يقم المستخدم بتصحيح طريقة الدفع قبل نهاية فترة تعليق الاشتراك ستتلقى بدلاً من ذلك RTDN من النوع SUBSCRIPTION_CANCELED. بالنسبة إرشادات حول التعامل مع عملية الإلغاء، راجع عمليات الإلغاء. عندما تريد عن اشتراك تم إلغاؤه بهذه الطريقة، تم ضبط حقل expiryTime على طابع زمني سابق:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_past,
      ...
    }
  ],
}

فور إعلامك بالإلغاء مباشرةً أثناء فترة تعليق الاشتراك، سيتلقّى أيضًا ”الإشعارات في الوقت الفعلي الخاصة بالمطوّرين“ من النوع SUBSCRIPTION_EXPIRED لأنّ المستخدم خارج الاستحقاق المدفوع وتم إيقاف الاشتراك مع الإلغاء. يمكنك التعامل مع انتهاء الصلاحية هذا بالطريقة المعتادة.

يمكن للمستخدم استعادة إمكانية الوصول من خلال إعادة شراء خطة الاشتراك نفسها أو أي خطة خطة أخرى تقدّمها من خلال التطبيق خلال فترة تعليق الاشتراك عملية الشراء الأصلية. وفي هذه الحالة، يتم إصدار رمز مميّز جديد للشراء يتم عرض القيمة الجديدة كجزء من حدث SUBSCRIPTION_PURCHASED الذي يمثل هذا المثيل الجديد.

الوصول إلى فترة تعليق الاشتراك واستردادها

يوضح الشكل 3 مخططًا زمنيًا للاشتراكات التي تدخل في فترة تعليق الاشتراك ثم يتم استردادها عندما يصلح المستخدم طريقة الدفع.

الشكل 3. المخطط الزمني للاشتراك الذي يدخل فترة تعليق الاشتراك لاسترداد الحساب قبل انتهائها.

على غرار المثال السابق، يعرض الشكل 4 مخططًا زمنيًا للاشتراك تدخل في فترة سماح أولاً قبل فترة تعليق الاشتراك، ثم يتعافى أثناء الانتظار.

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

من المهم تذكر النقاط التالية:

  • قبل دخول الاشتراك في فترة تعليق الاشتراك، يقدّم Google Play مبالغ إضافية محاولة تحصيل الرسوم من طريقة الدفع لمدة تصل إلى 48 ساعة يحتفظ المستخدم مزايا الاشتراك خلال هذه الفترة. وبعد انقضاء فترة إعادة المحاولة هذه، يدخل الاشتراك في فترة تعليق الاشتراك، ومن المفترض أن يفقد المستخدم الوصول إلى مزايا الاشتراك.
  • يدخل الاشتراك في فترة تعليق الاشتراك مباشرةً عندما استئنافه من حالة توقف مؤقتًا مع عدم نجاح طريقة الدفع.
  • عندما يسترد الاشتراك فترة تعليقه، تتم إعادة ضبط تاريخ التجديد.

فترات انتهاء الصلاحية

بعد انتهاء صلاحية الاشتراك، من المفترض أن يفقد المستخدم إمكانية الوصول إلى الاشتراك. حاسمة تم إرسال رسالة واحدة (SubscriptionNotification) من النوع SUBSCRIPTION_EXPIRED في هذه الحالة. عند تلقّي هذا الإشعار، يمكنك طلب المساعدة من مطوِّر برامج Google Play. واجهة برمجة التطبيقات للحصول على أحدث اشتراكات المرجع. بعد التأكّد من أنّ قيمة subscriptionState هي SUBSCRIPTION_STATE_EXPIRED، أزِل الإذن وسجِّل حالة الشراء على أنّها غير صالحة في الخلفية. يبدو مورد الاشتراك مشابهًا للمثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time_in_past,
      ...
    }
  ],
}

عمليات إلغاء الاشتراكات

يمكن للمستخدم إلغاء اشتراك طوعًا من مركز اشتراكات Play. أو سيتم إلغاء اشتراكهم تلقائيًا في حال عدم استرداد الاشتراك بعد قيد تعليق الاشتراك. يمكن للمطوّرين أيضًا تشغيل إمكانية الإلغاء مع purchases.subscriptions.cancel عند إلغاء اشتراك، يحتفظ المستخدم بإمكانية الوصول إلى المحتوى حتى نهاية دورة الفوترة الحالية. عند انتهاء دورة الفوترة، من المفترض أن يكون بإمكانك الوصول إلى الحساب إبطاله.

يؤدي إلغاء اشتراك غير مستند إلى تقسيط إلى ظهور إشعار واحد (SUBSCRIPTION_CANCELED) فعندما تلقيت هذا الإشعار، تجدر الإشارة إلى أن اشتراك المرجع التي يتم عرضها من خلال Google Play Developer API تحتوي على الحقل subscriptionState على SUBSCRIPTION_STATE_CANCELED، ويحتوي الحقل expiryTime على التاريخ الذي ينبغي أن يفقد فيه المستخدم إمكانية الوصول إلى الاشتراك. إذا كان هذا التاريخ في في الماضي، فيجب أن يفقد المستخدم إذن الوصول إليه على الفور. يمكن أن يحدث هذا، إذا ألغى أحد المستخدمين اشتراكًا أثناء استخدام الحساب تعليق بسبب رفض الدفعة.

يبدو مورد الاشتراك لعملية الشراء الملغاة مشابهًا لما يلي: مثال:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ],
}

بالنسبة إلى اشتراكات الأقساط، يجب إدخال SUBSCRIPTION_CANCELLATION_SCHEDULED يتم إرسال إشعار عند إلغاء اشتراك المستخدم في حال بقيت الدفعات عن مدة الاشتراك عملية الإلغاء في انتظار المراجعة وستدخل حيز التنفيذ في نهاية مدة الاشتراك الحالية عند تلقّي هذا الإشعار، سيتم في مورد الاشتراك الذي تم إرجاعه من واجهة برمجة تطبيقات Google Play Developer API تم ضبط الحقل SubscriptionState على SUBSCRIPTION_STATE_ACTIVE لأنّ لا يزال اشتراك الأقساط نشطًا حتى انتهاء مدة الاشتراك. ومع ذلك، هناك عنصر فارغ في انتظار الإلغاء. يتم إرسال إشعار SUBSCRIPTION_CANCELED متبوعًا SUBSCRIPTION_EXPIRED في نهاية مدة الاشتراك.

مرجع الاشتراك الخاص بعملية شراء الاشتراك بالتقسيط الذي عملية الإلغاء في انتظار المراجعة مشابهة للمثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_plan01",
      "expiryTime": expiration_time,
      "autoRenewingPlan": {
        "autoRenewEnabled": true,
        "recurringPrice": {
          "currencyCode": "USD",
          "units": "1",
          "nanos": 990000000
        },
        "installmentDetails": {
          "initialCommittedPaymentsCount": 6,
          "remainingCommittedPaymentsCount": 5,
          "pendingCancellation": {}
      ...
        }
      }
    }
  ],
}

يمكنك الاطّلاع على الحقل canceledStateContext في مورد الاشتراكات من أجل التعرّف على سبب إلغاء الاشتراك (على سبيل المثال، ما إذا كان الاشتراك المستخدم أو النظام أو أنت). إذا كان الاشتراك تم إلغاؤها من قِبل المستخدم، يمكنك الاطّلاع على الحقل userInitiatedCancellation التعرّف على سبب إلغاء المستخدم للاشتراك. يمكن أن يساعد هذا في إبلاغ التواصل والاستراتيجيات.

في حال إلغاء اشتراك بدون انتهاء صلاحيته بعد، لا يزال عاد من queryPurchasesAsync() قد ترغب في عرض رسالة في تطبيقك تخبر المستخدم بأن تم إلغاء الاشتراك ومنحهم تاريخ انتهاء الصلاحية.

عمليات الإبطال

يمكن إبطال الاشتراك لأسباب مختلفة، بما فيها الخلفية. إلغاء الاشتراك باستخدام purchases.subscriptionsv2.revoke أو عند استرداد مبلغ عملية الشراء في هذه الحالة، أبطل توجيه المستخدم بشكل فوري. رسالة SubscriptionNotification من النوع ويتم إرسال SUBSCRIPTION_REVOKED عند حدوث ذلك. عندما تتلقى هذه الرسالة الإشعار، سيتم إرسال اشتراك المرجع التي يتم عرضها من خلال Google Play Developer API تحتوي على الحقل subscriptionState مضبوطة على SUBSCRIPTION_STATE_EXPIRED

يبدو مورد الاشتراك لعملية شراء تم إبطالها مشابهًا لما يلي: مثال:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ]
}

الاشتراكات المؤجلة

هناك مجموعة متنوعة من الأسباب التي قد تدفعك إلى توسيع نطاق الوصول. على سبيل المثال، قد ترغب في منح المستخدمين وصولاً مجانيًا إلى مثل تقديم أسبوع مجاني لشراء فيلم أو تقديم الوصول إلى العملاء كإيماءة حسنة. يمكنك استخدام صفحة purchases.subscriptions.defer من Play Developer API لتقديم تاريخ الفوترة التالي تجديد الاشتراك تلقائيًا. عند إجراء ذلك، سيتم تنفيذ الإجراء على SubscriptionNotification يتم إرسال رسالة من النوع SUBSCRIPTION_DEFERRED. خلال فترة التأجيل، يكون المستخدم مشتركًا في المحتوى الخاص بك مع إمكانية الوصول الكامل ولكن لا يتم تحصيل رسوم منه. تشير رسالة الأشكال البيانية يتم تعديل تاريخ تجديد الاشتراك ليوافق التاريخ الجديد.

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

يبدو مورد الاشتراك للاشتراك المؤجل مشابهًا المثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_future,
      ...
    }
  ],
}

الاشتراكات المتوقفة مؤقتًا

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

تكرار الاشتراك أسبوعيًا شهريًا ثلاثة أشهر ستة أشهر السنوية
مدد الإيقاف المؤقت المتاحة* أسبوع واحد
أسبوعان
3 أسابيع
4 أسابيع		 شهر واحد
شهران
3 أشهر		 شهر واحد
شهران
3 أشهر		 شهر واحد
شهران
3 أشهر		 لا ينطبق
*قابلة للتغيير في أي وقت.

لا يتم إيقاف الاشتراك مؤقتًا إلا بعد انتهاء المدة الحالية للفوترة. أثناء إيقاف الاشتراك مؤقتًا، لا يمكن للمستخدم الوصول إلى الاشتراك، ولا يدفعون سعر التجديد. في نهاية الإيقاف المؤقت يتم استئناف الاشتراك وستحاول Google تجديده. وفي حال تم تفعيل استئناف الاشتراك، سيصبح نشطًا مرة أخرى. إذا كانت استئنافه بسبب مشكلة في الدفع، يدخل المستخدم في حالة تعليق الحساب كما هو موضح في الشكلين 5 و6:

الشكل 5. يتوقف المستخدم مؤقتًا ثم يستأنف اشتراكك.
الشكل 6. يوقف المستخدم اشتراكه مؤقتًا ثم يدخل فترة تعليق الاشتراك

ويمكن للمستخدم أيضًا اختيار استئناف الاشتراك يدويًا في أي وقت أثناء لفترة الإيقاف المؤقت، كما هو موضح في الشكل 6. عندما يستأنف المستخدم العمل يدويًا، يتم إصدار تغييرات التاريخ إلى تاريخ الاستئناف اليدوي.

عند إيقاف اشتراك المستخدم مؤقتًا، لا يتم عرض واجهة برمجة التطبيقات Play Billing Library الاشتراك من خلال queryPurchasesAsync() . في حال استئناف الاشتراك، استخدِم طريقة queryPurchasesAsync() وإعادته مرة أخرى.

الاستماع إلى ”إشعارات الوقت الفعلي الخاصة بالمطوّرين (RTDN)“ لمعرفة متى يوقف المستخدم اشتراكه مؤقتًا هذه تتيح لك الإشعارات أيضًا إبلاغ المستخدمين في تطبيقك بأنهم إيقاف اشتراكهم مؤقتًا ولا يمكنهم الوصول إليه. يجب عليك أيضًا تقديم للمستخدم لاستئناف اشتراكه يدويًا في أي وقت باستخدام رابط لصفحة في التطبيق إلى Google Play.

رسالة SubscriptionNotification من النوع SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED عندما يبدأ المستخدم الإيقاف المؤقت لاشتراكهم. في هذا الوقت، يجب على المستخدم الاحتفاظ بإمكانية الوصول إلى اشتراكهم حتى تاريخ التجديد التالي، ويشمل ذلك المرجع يحتوي على autoRenewEnabled = true. قيمة الحقل subscriptionState يبلغ SUBSCRIPTION_STATE_ACTIVE في هذه المرحلة.

يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_PAUSED عند الإيقاف المؤقت. عندما يحدث هذا، من المفترض أن يفقد المستخدم إمكانية الوصول إلى اشتراكك، ويحتوي مورد الاشتراك على autoRenewEnabled = true وتم ضبط الحقل subscriptionState على SUBSCRIPTION_STATE_PAUSED. يمكنك يمكنك معرفة الموعد المتوقَّع لتجديد الاشتراك من خلال التحقّق من PausedStateContext الخاص بك.

يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_RENEWED إذا أن يتم استئناف الاشتراك تلقائيًا إما في نهاية فترة الإيقاف المؤقت أو إذا اختار المستخدم استئناف الاشتراك يدويًا يجب معالجة هذا الأمر كما هو موضح في عمليات التجديد.

يتم إرسال رسالة SubscriptionNotification من النوع SUBSCRIPTION_ON_HOLD إذا تعذّر الدفع أثناء محاولة استئناف الاشتراك بعد الإيقاف المؤقت. ويجب التعامل مع هذا الإجراء على النحو الموضّح في مقالة فترة تعليق الاشتراك.

إعادة الاشتراك

بالنسبة إلى الخطط الأساسية للاشتراكات التي يتم تجديدها تلقائيًا، قد يعرض "متجر Google Play" زر إعادة الاشتراك يتيح هذا الزر للمستخدمين استعادة إمكانية الوصول. إلى اشتراك وقد لا يظهر لأسباب مختلفة، على سبيل المثال: عندما انتهت صلاحية اشتراك منذ وقت طويل.

الشكل 7. الحساب > قسم "الاشتراكات" تطبيق "متجر Google Play" يعرض اشتراكًا تم إلغاؤه من خلال زر إعادة الاشتراك

على الرغم من أنّ الزر يحمل اسم إعادة الاشتراك دائمًا، تعتمد وظائفه على وفقًا لحالة الاشتراك

على الرغم من إلغاء الاشتراك ولكن لم تنتهِ صلاحيته بعد، يظل المستخدم المشتركين وتلقّي مزايا الاشتراك إذا نقر المستخدم على "إعادة الاشتراك"، يتم التراجع عن الإلغاء بشكلٍ فعلي مع استمرار تجديد الاشتراك. ويُعرف هذا الإجراء باسم الاستعادة في مستندات المطوّرين على Play وواجهات برمجة التطبيقات.

بعد انتهاء صلاحية الاشتراك الذي يتم تجديده تلقائيًا، يمكنك السماح للمستخدمين بالشراء. نفس الخطة الأساسية للاشتراك. يُعرف هذا الإجراء باسم إعادة الاشتراك في مستندات مطوّري برامج Play وواجهات برمجة التطبيقات يمكنك ضبط هذا الخيار. لكل خطة أساسية في Play Console أو باستخدام واجهة برمجة التطبيقات.

استعادة البيانات قبل انتهاء الصلاحية

إذا كان تطبيقك يعتمد فقط على queryPurchasesAsync() لتحديد ما إذا كان المستخدم يحق له الحصول على اشتراك، سيثبت تطبيق من المفترض أن تعالج عمليات الاستعادة تلقائيًا نظرًا لأن queryPurchasesAsync() إرجاع عمليات الشراء المُلغاة قبل تواريخ انتهاء صلاحيتها. حاسمة سيستمر تجديد الاشتراك الذي تمت استعادته كما لو لم يتم إلغاؤه.

إذا كان التطبيق يزامن حالة الاشتراك مع الخلفية، يجب أن يستمع المستخدم إلى البيانات. لـ SubscriptionNotification رسالة من النوع SUBSCRIPTION_RESTARTED. بعد تلقي RTDN هذا، يمكن لتطبيقك الاستجابة إلى الإشعار، وتسجيل أنّ الاشتراك أصبح الآن الضبط على تجديد رسائل الاستعادة وإيقاف عرضها في تطبيقك. تشير رسالة الأشكال البيانية يبدو مورد الاشتراك مشابهًا للمثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date
      ...
    }
  ],
}

إعادة الاشتراك بعد انتهاء الصلاحية

في حال إعداد خطة أساسية تتجدّد تلقائيًا باستخدام Google Play Console أو واجهة برمجة التطبيقات للسماح بإعادة الاشتراك، يمكن للمستخدمين إعادة شراء اشتراك منتهي الصلاحية من خلال "متجر Google Play".

هذه عمليات شراء جديدة. يصدر Google Play رمزًا مميزًا جديدًا للشراء، الخلفية تتلقّى RTDN من النوع SUBSCRIPTION_PURCHASED. حالة الشراء لهذا النوع من عمليات الشراء خارج التطبيق لا تشمل linkedPurchaseToken المرتبطة بعملية الشراء الأصلية في هذه الحالة، نظرًا لأن الأصل انتهاء صلاحية اشتراكك بالكامل. هذه هي عمليات الشراء الجديدة التي يجب على الخلفية الحصول عليها والإقرار بالموافقة مثل أي عملية شراء أخرى.

عمليات الترقية والرجوع إلى إصدار سابق وإعادة الاشتراك

عندما يقوم المستخدم بالترقية أو الرجوع إلى إصدار سابق أو الاشتراك بعد الإلغاء من تطبيقك قبل انتهاء صلاحية الاشتراك، يتم إلغاء صلاحية الاشتراك وإنشاء اشتراك جديد يتضمن رمز شراء مميز جديد.

بالإضافة إلى ذلك، إنّ اشتراك المرجع التي تعرضها واجهة برمجة التطبيقات Google Play Developer API تحتوي على linkedPurchaseToken الذي يشير إلى عملية الشراء القديمة التي قام المستخدم بالترقية منها، أو الرجوع إلى إصدار سابق، أو أعادوا الاشتراك يمكنك استخدام رمز الشراء المميز في هذا الحقل للبحث عن الرمز القديم الاشتراك وتحديد حساب المستخدم الحالي لتتمكن من ربط عملية الشراء الجديدة باستخدام الحساب نفسه.

قبل توفير خيارات الترقية أو الاشتراك في خطة أقلّ كلفة أو إعادة الاشتراك للمستخدم في تطبيقك، يجب الإقرار بالاشتراك الحالي. عند تغيير الخطة أو إعادة الاشتراك إذا كان الاشتراك الحالي لا يزال في انتظار الإقرار.

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

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "linkedPurchaseToken": old_purchase_token,
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

تغييرات السعر

الاطّلاع على دليل أفضل الممارسات المتعلّقة بتغيير السعر مزيد من المعلومات حول تغيير أسعار الاشتراكات التي يتم تجديدها تلقائيًا وإعلام المستخدمين عندما يكون ذلك مناسبًا.

عندما تفعّل هذه التغييرات على الأسعار للمشتركين الحاليين، يجب: تلقّي RTDN في حال اتّخذ المستخدم إجراءً لتأكيد السعر الجديد أو رفضه.

التعامل مع تأكيد المستخدم لتغيير السعر

عندما يقبل المستخدِم زيادة سعر اشتراكك، ستتلقّى رسالة SubscriptionNotification من النوع SUBSCRIPTION_PRICE_CHANGED_CONFIRMED. بسعر لا يُطبَّق على المستخدمين تخفيضًا، أو عند تجديد الزيادة في سعر الاشتراك، ستتلقى رسالة واحدة (SubscriptionNotification) من النوع SUBSCRIPTION_RENEWED. التعامل مع هذه المشكلة إشعار مثل أي تجديد آخر.

التعامل مع الحالات التي لا يتم فيها قبول الزيادة في السعر التي تتطلّب موافقة

إذا لم يقبل المستخدم الزيادة في السعر التي تتطلب موافقة المستخدم قبل أن يحتاج إلى التجديد مقابل سعر أعلى، فسيتم إلغاء اشتراكهم تلقائيًا وتحصل على رسالة SubscriptionNotification من النوع SUBSCRIPTION_CANCELED. التعامل مع هذا الحدث على النحو الموضَّح في عمليات الإلغاء:

يمكن للمستخدمين أيضًا إلغاء اشتراكاتهم بسبب زيادة في السعر لا تتطلّب موافقة. باتباع الآلية نفسها.

التعامل مع دورة حياة خطط الدفع المُسبق

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

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

الشكل 8. حالات مراحل النشاط والأحداث الانتقالية شراء الاشتراكات

رسالة SubscriptionNotification ذات النوع SUBSCRIPTION_PURCHASED إلى عميل RTDN: يتم شراء الاشتراك في خطة الدفع المُسبق، بما في ذلك كل عملية إضافة رصيد. عليك استدعاء purchases.subscriptionsv2.get للتحقّق من أحدث حالة اشتراك في خطة الدفع المُسبَق.

يتم إصدار رمز شراء مميّز جديد لعمليات الشراء التي تتم إضافة رصيد إليها، وستتلقّى رمز الشراء السابق في الحقل linkedPurchaseToken كجزء من الرمز الجديد حالة شراء الاشتراك. الرمز المميّز للشراء صالح من الاشتراك الاشتراك حتى 60 يومًا من انتهاء الصلاحية. وبعد هذا التاريخ، سيصبح رمز الشراء لم تعد صالحة للاستخدام لطلب واجهة برمجة التطبيقات Google Play Developer API.

يبدو مورد الاشتراك لعملية شراء خطة دفع مُسبَق مشابهًا المثال التالي:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
  "lineItems": [
    {
      "productId": "prepaid_plan01",
      "expiryTime": expiry_date,
      "prepaidPlan": {
        "allowExtendAfterTime": timestamp_after_which_topups_are_allowed
      }
    }
  ]
}

يمكنك معرفة وقت انتهاء الإذن بالوصول في الحقل expiryTime. إضافة رصيد تؤدي عمليات الشراء إلى زيادة وقت الوصول إلى الموقع الإلكتروني من خلال تجميعه. هذا يعني أنه إذا يضيف المستخدِم رصيدًا قبل انتهاء إذن الوصول الأصلي، وتتم إضافة الوقت الجديد بالإضافة إلى تاريخ انتهاء الصلاحية السابق.

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

لا يتم تجديد خطط الدفع المُسبق تلقائيًا، لذا لا يمكن إلغاؤها. إذا أراد أحد المستخدمين إلغاء خطة دفع مُسبق، قد يسمح لها ببلوغ تاريخ انتهاء صلاحيتها.