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

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

في حال توفّر هذا الحقل، يعني ذلك أنّ هذا الإشعار مرتبط بعملية نشر تجريبية. ويتم إرسال هذه الرسائل من خلال Google 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
  }
}

Consuming 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"
  }
}