راهنمای مرجع اعلان‌های بی‌درنگ توسعه‌دهنده

این سند انواع اعلان‌های بی‌درنگ توسعه‌دهنده را که می‌توانید از 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
}

این فیلدها در جدول زیر شرح داده شده‌اند.

نام دارایی مقدار شرح
نسخه رشته نسخه این اعلان. در ابتدا، این مقدار «۱.۰» است. این نسخه با فیلدهای نسخه دیگر متفاوت است.
نام بسته رشته نام بسته برنامه‌ای که این اعلان به آن مربوط است (برای مثال، `com.some.thing`).
eventTimeMillis طولانی مُهر زمان وقوع رویداد، برحسب میلی‌ثانیه از تاریخ یونیکس.
subscriptionNotification SubscriptionNotification

اگر این فیلد وجود داشته باشد، این اعلان مربوط به اشتراک است و این فیلد حاوی اطلاعات تکمیلی مربوط به اشتراک است.

توجه داشته باشید که این فیلد با pendingRefundReviewNotification،‏ oneTimeProductNotification،‏ voidedPurchaseNotification، و testNotification ناسازگار است.
oneTimeProductNotification OneTimeProductNotification

اگر این فیلد وجود داشته باشد، این اعلان مربوط به خرید یک‌باره است و این فیلد حاوی اطلاعات تکمیلی مربوط به خرید است.

توجه داشته باشید که این فیلد با pendingRefundReviewNotification،‏ subscriptionNotification،‏ voidedPurchaseNotification، و testNotification ناسازگار است.
voidedPurchaseNotification VoidedPurchaseNotification

اگر این فیلد وجود داشته باشد، این اعلان مربوط به خرید باطل‌شده است و این فیلد حاوی اطلاعات تکمیلی مربوط به خرید باطل‌شده است.

توجه داشته باشید که این فیلد با pendingRefundReviewNotification،‏ oneTimeProductNotification، subscriptionNotification، و testNotification متقابلاً انحصاری است.
pendingRefundReviewNotification PendingRefundReviewNotification

اگر این فیلد وجود داشته باشد، این اعلان مربوط به درخواست استرداد وجهی است که می‌توانید برای آن راه‌حلی پیشنهاد دهید. با فراخوانی کردن API‏ `ReviewRefund` به این اعلان پاسخ دهید.

توجه داشته باشید که این فیلد با subscriptionNotification،‏ oneTimeProductNotification،‏ voidedPurchaseNotification، و testNotification به‌صورت متقابل انحصاری است.
testNotification TestNotification

اگر این فیلد وجود داشته باشد، این اعلان مربوط به انتشار آزمایشی است. این اعلان‌ها فقط ازطریق Google Play Developer Console ارسال می‌شوند.

توجه داشته باشید که این فیلد با pendingRefundReviewNotification،‏ oneTimeProductNotification،‏ subscriptionNotification، و voidedPurchaseNotification به‌صورت متقابل انحصاری است.

SubscriptionNotification

SubscriptionNotification شامل فیلدهای زیر است:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string
}
نام دارایی مقدار شرح
نسخه رشته نسخه این اعلان. در ابتدا، این مقدار «1.0» است. این نسخه با فیلدهای نسخه دیگر متفاوت است.
notificationType قطع توپ notificationType برای اشتراک می‌تواند مقادیر زیر را داشته باشد:
  • (۱) SUBSCRIPTION_RECOVERED - اشتراکی از تعلیق حساب بازیابی شده یا از توقف موقت ازسر گرفته شده است.
  • (۲) SUBSCRIPTION_RENEWED - اشتراک فعال تمدید شد.
  • (۳) SUBSCRIPTION_CANCELED - اشتراکی به‌صورت داوطلبانه یا غیرداوطلبانه لغو شده است. برای لغو داوطلبانه، زمانی ارسال می‌شود که کاربر لغو می‌کند.
  • (۴) SUBSCRIPTION_PURCHASED - اشتراک جدیدی خریداری شده است.
  • (۵) SUBSCRIPTION_ON_HOLD - اشتراک وارد حالت تعلیق حساب شده است (درصورت فعال بودن).
  • (۶) SUBSCRIPTION_IN_GRACE_PERIOD - اشتراک وارد مهلت ارفاقی شده است (اگر فعال باشد).
  • (۷) SUBSCRIPTION_RESTARTED - کاربر اشتراکش را از Play > حساب > اشتراک‌ها بازیابی کرده است. اشتراک لغو شده بود اما وقتی کاربر آن را بازیابی کرد هنوز منقضی نشده بود. برای اطلاعات بیشتر، بازیابی قبل‌از انقضا را ببینید.
  • (۸) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED (منسوخ‌شده) - تغییر قیمت اشتراک باموفقیت توسط کاربر تأیید شده است.
  • (۹) SUBSCRIPTION_DEFERRED - زمان تکرار اشتراک تمدید شده است.
  • (۱۰) SUBSCRIPTION_PAUSED - اشتراکی موقتاً متوقف شده است.
  • (۱۱) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED - زمان‌بندی توقف موقت اشتراک تغییر کرده است.
  • (۱۲) SUBSCRIPTION_REVOKED - اشتراک کاربر قبل‌از زمان انقضا لغو شده است.
  • (۱۳) SUBSCRIPTION_EXPIRED - اشتراکی منقضی شده است.
  • (17) SUBSCRIPTION_ITEMS_CHANGED - موردی در دسته اشتراک تغییر کرده است.
  • (18) SUBSCRIPTION_CANCELLATION_SCHEDULED - لغو اشتراک قسطی برای اعمال در پایان دوره تعهد زمان‌بندی شده است.
  • ‫(۱۹) 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 قطع توپ نوع اعلان. می‌تواند مقادیر زیر را داشته باشد:
  • (۱) ONE_TIME_PRODUCT_PURCHASED - محصول یک‌باره باموفقیت توسط کاربر خریداری شد.
  • (۲) 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 برای خرید باطل‌شده می‌تواند مقادیر زیر را داشته باشد:

  • (۱) PRODUCT_TYPE_SUBSCRIPTION - خرید اشتراک باطل شده است.
  • (۲) PRODUCT_TYPE_ONE_TIME - خرید یک‌باره‌ای باطل شده است.

refundType

int

refundType برای خرید باطل‌شده می‌تواند مقادیر زیر را داشته باشد:

  • (۱) REFUND_TYPE_FULL_REFUND - خرید کاملاً باطل شده است.
  • (۲) 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 ارسال می‌شود. وقتی این اعلان را دریافت می‌کنید، باید درخواست را ارزیابی کنید و با فراخوانی کردن میانای برنامه‌سازی کاربردی ReviewRefund، پیشنهاد استرداد مبلغ و مدرک استفاده از خرید را ظرف ۲۴ ساعت ارائه دهید.

PendingRefundReviewNotification شامل فیلدهای زیر است:

{
  "version": string,
  "pendingRefundToken": string,
  "orderId": string,
  "refundReason": int,
  "obfuscatedAccountId": string,
  "obfuscatedProfileId": string
}
نام دارایی مقدار شرح
نسخه رشته نسخه این اعلان. در ابتدا، این مقدار «۱.۰» است. این نسخه از دیگر فیلدهای نسخه متمایز است.
pendingRefundToken رشته یک توکن یکتا که درخواست بازپرداخت معلق تحت بازبینی را شناسایی می‌کند. این کد را هنگام فراخواندن ReviewRefund API ارسال کنید.
orderId رشته شناسه سفارش خریدی که تحت بازبینی استرداد مبلغ معلقه است.
refundReason قطع توپ دلیل درخواست استرداد مبلغ. مرورهای معلقه فقط از CHARGEBACK (۷) به‌عنوان دلیل استرداد مبلغ پشتیبانی می‌کنند. کد شما باید دلایل جدید را به‌محض دردسترس قرار گرفتن مدیریت کند.
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"
  }
}