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

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