الدليل المرجعي لإشعارات المطوِّرين في الوقت الفعلي

يسرد هذا المستند أنواع الإشعارات في الوقت الفعلي الخاصة بالمطوّرين التي يمكنك تلقّيها من Google Play ويصفها.

التشفير

يحتوي كل منشور يتم نشره في موضوع Cloud Pub/Sub على حقل بيانات واحد بترميز base64.

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "eyAidmVyc2lvbiI6IHN0cmluZywgInBhY2thZ2VOYW1lIjogc3RyaW5nLCAiZXZlbnRUaW1lTWlsbGlzIjogbG9uZywgIm9uZVRpbWVQcm9kdWN0Tm90aWZpY2F0aW9uIjogT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24sICJzdWJzY3JpcHRpb25Ob3RpZmljYXRpb24iOiBTdWJzY3JpcHRpb25Ob3RpZmljYXRpb24sICJ0ZXN0Tm90aWZpY2F0aW9uIjogVGVzdE5vdGlmaWNhdGlvbiB9",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

بعد فك ترميز حقل البيانات بترميز base64، يحتوي DeveloperNotification على الحقول التالية:

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification,
  "pendingRefundReviewNotification": PendingRefundReviewNotification,
  "testNotification": TestNotification
}

يتم وصف هذه الحقول في الجدول التالي.

اسم الموقع القيمة الوصف
الإصدار سلسلة تمثّل هذه السمة إصدار الإشعار. في البداية، تكون هذه القيمة "1.0". يختلف هذا الإصدار عن حقول الإصدارات الأخرى.
packageName سلسلة تمثّل هذه السمة اسم حزمة التطبيق الذي يرتبط به هذا الإشعار (على سبيل المثال، `com.some.thing`).
eventTimeMillis طويلة الطابع الزمني لوقت وقوع الحدث، بالملي ثانية منذ بدء الحقبة
subscriptionNotification SubscriptionNotification

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

يُرجى العِلم أنّ هذا الحقل يستبعد الحقول pendingRefundReviewNotification وoneTimeProductNotification وvoidedPurchaseNotification وtestNotification.
oneTimeProductNotification OneTimeProductNotification

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

يُرجى العِلم أنّ هذا الحقل يستبعد الحقول pendingRefundReviewNotification وsubscriptionNotification وvoidedPurchaseNotification وtestNotification.
voidedPurchaseNotification VoidedPurchaseNotification

في حال توفّر هذا الحقل، يعني ذلك أنّ الإشعار مرتبط بعملية شراء تم إلغاؤها، ويتضمّن هذا الحقل معلومات إضافية ذات صلة بعملية الشراء الملغاة.

يُرجى العِلم أنّ هذا الحقل يستبعد الحقول pendingRefundReviewNotification وoneTimeProductNotification وsubscriptionNotification وtestNotification.
pendingRefundReviewNotification PendingRefundReviewNotification

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

يُرجى العِلم أنّ هذا الحقل يستبعد الحقول subscriptionNotification وoneTimeProductNotification وvoidedPurchaseNotification وtestNotification.
testNotification TestNotification

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

يُرجى العِلم أنّ هذا الحقل يستبعد كلّاً من pendingRefundReviewNotification وoneTimeProductNotification وsubscriptionNotification وvoidedPurchaseNotification.

SubscriptionNotification

يحتوي SubscriptionNotification على الحقول التالية:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string
}
اسم الموقع القيمة الوصف
الإصدار سلسلة تمثّل نسخة هذا الإشعار. في البداية، تكون القيمة "1.0". يختلف هذا الإصدار عن حقول الإصدارات الأخرى.
notificationType تدخُّل دفاعي يمكن أن تتضمّن السمة notificationType الخاصة بالاشتراك القيم التالية:
  • ‫(1) SUBSCRIPTION_RECOVERED: تم استرداد اشتراك من تعليق الاشتراك أو تم استئنافه من الإيقاف المؤقت.
  • (2) SUBSCRIPTION_RENEWED - تم تجديد اشتراك نشط.
  • ‫(3) SUBSCRIPTION_CANCELED: تم إلغاء الاشتراك إما طوعًا أو قسرًا. بالنسبة إلى الإلغاء الطوعي، يتم إرسال هذا الإشعار عندما يلغي المستخدم اشتراكه.
  • ‫(4) SUBSCRIPTION_PURCHASED: تم شراء اشتراك جديد.
  • ‫(5) SUBSCRIPTION_ON_HOLD: تم تعليق الاشتراك في الحساب (في حال تفعيل هذه الميزة).
  • (6) SUBSCRIPTION_IN_GRACE_PERIOD - دخل الاشتراك في فترة سماح (في حال تفعيلها).
  • (7) SUBSCRIPTION_RESTARTED: أعاد المستخدم اشتراكه من خلال Play > الحساب > الاشتراكات. تم إلغاء الاشتراك ولكن لم تنتهِ صلاحيته بعد عندما يستعيده المستخدم. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة استعادة الاشتراك قبل انتهاء صلاحيته.
  • ‫(8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED (متوقّف نهائيًا): أكّد المستخدم تغيير سعر الاشتراك بنجاح.
  • ‫(9) SUBSCRIPTION_DEFERRED: تم تمديد وقت تكرار الاشتراك.
  • ‫(10) SUBSCRIPTION_PAUSED: تم إيقاف الاشتراك مؤقتًا.
  • ‫(11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED - تم تغيير جدول إيقاف الاشتراك مؤقتًا.
  • ‫(12) SUBSCRIPTION_REVOKED: تم إلغاء اشتراك المستخدم قبل تاريخ انتهاء الصلاحية.
  • ‫(13) SUBSCRIPTION_EXPIRED: انتهت صلاحية الاشتراك.
  • ‫(17) SUBSCRIPTION_ITEMS_CHANGED: تم تغيير عنصر في حزمة اشتراك.
  • ‫(18) SUBSCRIPTION_CANCELLATION_SCHEDULED - تم تحديد موعد لإلغاء اشتراك بنظام الأقساط، وسيكون الإلغاء ساريًا في نهاية مدة الالتزام.
  • ‫(19) SUBSCRIPTION_PRICE_CHANGE_UPDATED: تم تعديل تفاصيل تغيير سعر عنصر الاشتراك.
  • ‫(20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - تم إلغاء معاملة في انتظار المعالجة خاصة باشتراك.
  • ‫(22) SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED: بدأت فترة الموافقة على زيادة سعر الاشتراك أو قدّم المستخدم موافقته على زيادة السعر. لا يتم إرسال إشعار RTDN هذا إلا للاشتراكات في منطقة تتطلب زيادة السعر.
purchaseToken سلسلة تمثّل هذه السمة الرمز المميز الذي تم تقديمه إلى جهاز المستخدم عند شراء الاشتراك.

مثال

في ما يلي مثال على إشعار بشأن عملية شراء اشتراك جديد:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "subscriptionNotification":
  {
    "version":"1.0",
    "notificationType":4,
    "purchaseToken":"PURCHASE_TOKEN"
  }
}

OneTimeProductNotification

يحتوي OneTimeProductNotification على الحقول التالية:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "sku": string
}
اسم الموقع القيمة الوصف
الإصدار سلسلة تمثّل نسخة هذا الإشعار. في البداية، ستكون هذه القيمة "1.0". يختلف هذا الإصدار عن حقول الإصدارات الأخرى.
notificationType تدخُّل دفاعي تمثّل هذه السمة نوع الإشعار. يمكن أن تتضمّن القيم التالية:
  • ‫(1) ONE_TIME_PRODUCT_PURCHASED - شراء أحد المستخدمين منتجًا مدفوعًا لمرة واحدة
  • ‫(2) ONE_TIME_PRODUCT_CANCELED: تم إلغاء أو إبطال عملية شراء منتج مدفوع لمرة واحدة.
purchaseToken سلسلة الرمز المميز الذي تم تقديمه إلى جهاز المستخدم عند إجراء عملية الشراء.
sku سلسلة معرّف المنتج المدفوع لمرة واحدة الذي تم شراؤه (على سبيل المثال، "sword_001")

مثال

في ما يلي مثال على إشعار بشأن عملية شراء جديدة لمرة واحدة:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "oneTimeProductNotification":
  {
    "version":"1.0",
    "notificationType":1,
    "purchaseToken":"PURCHASE_TOKEN",
    "sku":"my.sku"
  }
}

VoidedPurchaseNotification

يحتوي VoidedPurchaseNotification على الحقول التالية:

اسم الموقع القيمة الوصف

purchaseToken

string

الرمز المميّز المرتبط بعملية الشراء التي تم إلغاؤها ويتم تقديم هذه المعلومات إلى المطوّر عند إجراء عملية شراء جديدة.

orderId

string

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

productType

int

يمكن أن يحتوي productType لعملية شراء باطلة على القيم التالية:

  • (1) PRODUCT_TYPE_SUBSCRIPTION - تم إلغاء عملية شراء اشتراك.
  • (2) تم إبطال عملية شراء PRODUCT_TYPE_ONE_TIME لمرة واحدة.

refundType

int

يمكن أن يحتوي refundType لعملية شراء باطلة على القيم التالية:

  • ‫(1) REFUND_TYPE_FULL_REFUND: تم إلغاء عملية الشراء بالكامل.
  • ‫(2) REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND: تم إلغاء عملية الشراء جزئيًا من خلال ردّ جزء من الأموال استنادًا إلى الكمية، ولا ينطبق ذلك إلا على عمليات الشراء المتعددة الكميات. يمكن إبطال عملية شراء جزئيًا عدة مرات.

يُرجى العِلم أنّه عند ردّ الأموال المتبقية من إجمالي كمية عملية شراء متعددة الكميات، سيكون refundType هو REFUND_TYPE_FULL_REFUND.

مثال

في ما يلي مثال على إشعار بشأن عملية شراء مُلغاة جديدة:

{
  "version":"1.0",
  "packageName":"com.some.app",
  "eventTimeMillis":"1503349566168",
  "voidedPurchaseNotification":
  {
    "purchaseToken":"PURCHASE_TOKEN",
    "orderId":"GS.0000-0000-0000",
    "productType":1
    "refundType":1
  }
}

استخدام VoidedPurchaseNotification

عندما يتلقّى برنامج RTDN VoidedPurchaseNotification، سجِّل المعلومات التالية:

  • ‫packageName: يحدّد التطبيق.
  • eventTimeMillis: لإعلامك بوقت حدوث تغيير الحالة.
  • ‫purchaseToken: الرمز المميّز الذي يتم تقديمه إلى جهاز المستخدم عند شراء المنتج.
  • orderId: تحدّد هذه السمة الطلب المرتبط بالمعاملة الملغاة.
  • productType: يشير إلى ما إذا كانت عملية الشراء الباطلة عملية شراء داخل التطبيق أو اشتراكًا.
  • ‫refundType: تحدّد نوع عملية ردّ الأموال التي أدّت إلى إلغاء عملية الشراء.

PendingRefundReviewNotification

يتم إرسال PendingRefundReviewNotification عندما يطلب المستخدم ردّ الأموال المدفوعة مقابل عملية شراء، ويتطلّب الطلب مراجعة من المطوّر. عند تلقّي هذا الإشعار، عليك تقييم الطلب وتقديم اقتراح بردّ الأموال ودليل على استخدام عملية الشراء في غضون 24 ساعة من خلال طلب البيانات من واجهة برمجة التطبيقات ReviewRefund.

يحتوي PendingRefundReviewNotification على الحقول التالية:

{
  "version": string,
  "pendingRefundToken": string,
  "orderId": string,
  "refundReason": int,
  "obfuscatedAccountId": string,
  "obfuscatedProfileId": string
}
اسم الموقع القيمة الوصف
الإصدار سلسلة تمثّل نسخة هذا الإشعار. في البداية، تكون القيمة "1.0". يختلف هذا الإصدار عن حقول الإصدارات الأخرى.
pendingRefundToken سلسلة رمز مميز فريد يحدّد طلب استرداد الأموال المعلق الذي تتم مراجعته. يُرجى تمرير هذا الرمز المميّز عند طلب واجهة برمجة التطبيقات ReviewRefund API.
orderId سلسلة معرّف طلب الشراء الذي يخضع لمراجعة طلب ردّ الأموال في انتظار المراجعة
refundReason تدخُّل دفاعي سبب طلب استرداد الأموال لا تتيح المراجعات في انتظار المراجعة سوى السبب CHARGEBACK (7) لطلب ردّ الأموال. يجب أن يتعامل الرمز مع الأسباب الجديدة عند توفّرها.
obfuscatedAccountId سلسلة (إذا كان ذلك منطبقًا) رقم تعريف حساب المستخدم المموَّه الذي حدّده المطوّر وتم تقديمه عند إجراء عملية الشراء.
obfuscatedProfileId سلسلة (في حال توفّره) معرّف الملف الشخصي المشوَّش الذي يحدّده المطوِّر والذي تم تقديمه عند إجراء عملية الشراء

مثال

في ما يلي مثال على إشعار بمراجعة عملية ردّ الأموال المعلقة:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "pendingRefundReviewNotification":
  {
    "version":"1.0",
    "pendingRefundToken":"example-token",
    "orderId":"GPA.1234-5678-9012-34567",
    "refundReason":7,
    "obfuscatedAccountId":"user-account-id",
    "obfuscatedProfileId":"user-profile-id"
  }
}

TestNotification

يحتوي TestNotification على الحقول التالية:

{
  "version": string
}
اسم الموقع القيمة الوصف
الإصدار سلسلة تمثّل نسخة هذا الإشعار. في البداية، تكون القيمة "1.0". يختلف هذا الإصدار عن حقول الإصدارات الأخرى.

مثال

في ما يلي مثال على إشعار تجريبي:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "testNotification":
  {
    "version":"1.0"
  }
}