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

يسرد هذا المستند أنواع الإشعارات في الوقت الفعلي الخاصة بالمطوّرين التي يمكنك تلقّيها من 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,
  "testNotification": TestNotification
}

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

اسم الموقع القيمة الوصف
إصدار سلسلة تمثّل هذه السمة إصدار هذا الإشعار. في البداية، تكون القيمة "1.0". يختلف هذا الإصدار عن حقول الإصدارات الأخرى.
packageName سلسلة تمثّل هذه السمة اسم حزمة التطبيق الذي يرتبط به هذا الإشعار (على سبيل المثال، `com.some.thing`).
eventTimeMillis طويلة الطابع الزمني لوقوع الحدث، بالمللي ثانية منذ الحقبة
subscriptionNotification SubscriptionNotification في حال توفّر هذا الحقل، يعني ذلك أنّ الإشعار مرتبط باشتراك، ويحتوي هذا الحقل على معلومات إضافية متعلقة بالاشتراك. يُرجى العِلم أنّ هذا الحقل يستبعد الحقول oneTimeProductNotification وvoidedPurchaseNotification وtestNotification.
oneTimeProductNotification OneTimeProductNotification إذا كان هذا الحقل متوفّرًا، يعني ذلك أنّ الإشعار مرتبط بعملية شراء لمرة واحدة، ويحتوي هذا الحقل على معلومات إضافية ذات صلة بعملية الشراء. يُرجى العِلم أنّ هذا الحقل يستبعد الحقول subscriptionNotification وvoidedPurchaseNotification وtestNotification.
voidedPurchaseNotification VoidedPurchaseNotification في حال توفّر هذا الحقل، يعني ذلك أنّ هذا الإشعار مرتبط بعملية شراء تم إلغاؤها، ويحتوي هذا الحقل على معلومات إضافية ذات صلة بعملية الشراء الملغاة. يُرجى العِلم أنّ هذا الحقل يستبعد الحقول oneTimeProductNotification وsubscriptionNotification وtestNotification.
testNotification TestNotification في حال توفّر هذا الحقل، يعني ذلك أنّ هذا الإشعار مرتبط بنشر تجريبي. ويتم إرسال هذه الرسائل من خلال Google Play Console فقط. يُرجى العِلم أنّ هذا الحقل يستبعد الحقول 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 - انتهت صلاحية الاشتراك.
  • ‫(20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - تم إلغاء معاملة اشتراك معلّقة.
  • (19) SUBSCRIPTION_PRICE_CHANGE_UPDATED - تم تعديل تفاصيل تغيير سعر أحد عناصر الاشتراك.
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
  }
}

Consuming VoidedPurchaseNotification

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

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

TestNotification

يتضمّن TestNotification الحقول التالية:

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

مثال

في ما يلي مثال على إشعار مُرسَل على سبيل الاختبار:

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