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

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

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

توجه داشته باشید که این فیلد با 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
}
نام دارایی مقدار شرح
نسخه رشته نسخه این اعلان. در ابتدا، این مقدار «۱.۰» است. این نسخه با فیلدهای نسخه دیگر متفاوت است.
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 - اشتراکی منقضی شده است.
  • (۱۷) SUBSCRIPTION_ITEMS_CHANGED - موردی در بسته اشتراک تغییر کرده است.
  • (۱۸) SUBSCRIPTION_CANCELLATION_SCHEDULED - لغو اشتراک قسطی برنامه‌ریزی شده است تا در پایان دوره تعهد اعمال شود.
  • (۱۹) SUBSCRIPTION_PRICE_CHANGE_UPDATED - جزئیات تغییر قیمت یک مورد اشتراک به‌روزرسانی می‌شود.
  • ‫(۲۰) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - تراکنش معلقه اشتراک لغو شده است.
  • (۲۲) 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
}
نام دارایی مقدار شرح
نسخه رشته نسخه این اعلان. در ابتدا، این مقدار «۱.۰» خواهد بود. این نسخه با فیلدهای نسخه دیگر متفاوت است.
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 API، پیشنهاد استرداد مبلغ و مدرک استفاده از خرید را ارائه دهید.

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

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

مثال

در اینجا نمونه‌ای از اعلان آزمایشی آورده شده است:

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