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

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

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

نام دارایی مقدار شرح
نسخه رشته نسخه این اعلان. در ابتدا، این مقدار «۱.۰» است. این نسخه با دیگر فیلدهای نسخه متفاوت است.
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» ارسال می‌شوند.

توجه داشته باشید که این فیلد با 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 - اشتراک وارد تعلیق حساب شده است (درصورت فعال بودن).
  • (6) SUBSCRIPTION_IN_GRACE_PERIOD - اشتراک وارد مهلت ارفاقی شده است (اگر فعال باشد).
  • (۷) SUBSCRIPTION_RESTARTED - کاربر اشتراکش را از Play > حساب > اشتراک‌ها بازیابی کرده است. اشتراک لغو شده بود اما وقتی کاربر بازیابی می‌کند هنوز منقضی نشده بود. برای اطلاعات بیشتر، بازیابی پیش‌از انقضا را ببینید.
  • (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED (منسوخ‌شده) - تغییر قیمت اشتراک باموفقیت توسط کاربر تأیید شده است.
  • (9) SUBSCRIPTION_DEFERRED - زمان تکرار اشتراک تمدید شده است.
  • (۱۰) SUBSCRIPTION_PAUSED - اشتراک موقتاً متوقف شده است.
  • (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED - زمان‌بندی توقف موقت اشتراک تغییر کرده است.
  • (۱۲) SUBSCRIPTION_REVOKED - اشتراکی قبل‌از زمان انقضا از کاربر لغو شده است.
  • (۱۳) SUBSCRIPTION_EXPIRED - اشتراکی منقضی شده است.
  • (17) SUBSCRIPTION_ITEMS_CHANGED - موردی در دسته اشتراک تغییر کرده است.
  • (۱۸) SUBSCRIPTION_CANCELLATION_SCHEDULED - لغو اشتراک قسطی زمان‌بندی شده است تا در پایان دوره تعهد اعمال شود.
  • (۱۹) SUBSCRIPTION_PRICE_CHANGE_UPDATED - جزئیات تغییر قیمت محصول اشتراکی به‌روزرسانی شده است.
  • (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - تراکنش معلق اشتراک لغو شده است.
  • (۲۱) SUBSCRIPTION_PLAN_TRANSITION_UPDATED - گذار طرح زمان‌بندی‌شده اشتراک به‌روز شده است (برای مثال، وقتی کاربر پیشنهاد حفظ را می‌پذیرد).
  • ‫(۲۲) 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 (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
}
نام دارایی مقدار شرح
نسخه رشته نسخه این اعلان. در ابتدا، این مقدار «۱.۰» است. این نسخه با دیگر فیلدهای نسخه متفاوت است.

مثال

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

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