מדריך עזר בנושא התראות בזמן אמת למפתחים

במסמך הזה מפורטים סוגי ההתראות למפתחים בזמן אמת שאפשר לקבל מ-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,
  "testNotification": TestNotification
}

השדות האלה מתוארים בטבלה הבאה.

שם הנכס הערך תיאור
גרסה מחרוזת גרסת ההתראה. הערך הראשוני הוא '1.0'. הגרסה הזו שונה משדות גרסה אחרים.
packageName מחרוזת שם החבילה של האפליקציה שאליה ההתראה הזו מתייחסת (לדוגמה, com.some.thing).
eventTimeMillis ארוך חותמת הזמן שבה האירוע התרחש, באלפיות השנייה מאז תחילת התקופה של זמן מערכת.
subscriptionNotification SubscriptionNotification אם השדה הזה מופיע, המשמעות היא שההתראה הזו קשורה למינוי, והשדה מכיל מידע נוסף שקשור למינוי. שימו לב: השדה הזה לא יכול להיות משולב עם השדות oneTimeProductNotification,‏ voidedPurchaseNotification ו-testNotification.
oneTimeProductNotification OneTimeProductNotification אם השדה הזה מופיע, המשמעות היא שההתראה הזו קשורה לרכישה חד-פעמית, והשדה מכיל מידע נוסף שקשור לרכישה. שימו לב: השדה הזה לא יכול להיות בשימוש עם השדות subscriptionNotification,‏ voidedPurchaseNotification ו-testNotification.
voidedPurchaseNotification VoidedPurchaseNotification אם השדה הזה קיים, המשמעות היא שההתראה הזו קשורה לרכישה שבוטלה, והשדה מכיל מידע נוסף שקשור לרכישה שבוטלה. שימו לב: השדה הזה לא יכול להיות משולב עם השדות oneTimeProductNotification,‏ subscriptionNotification ו-testNotification.
testNotification TestNotification אם השדה הזה קיים, ההתראה הזו קשורה לפרסום של בדיקה. ההודעות האלה נשלחות רק דרך Google Play Console. הערה: השדה הזה לא יכול להופיע יחד עם השדות oneTimeProductNotification,‏ subscriptionNotification ו-voidedPurchaseNotification.

SubscriptionNotification

אובייקט SubscriptionNotification מכיל את השדות הבאים:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string
}
שם הנכס הערך תיאור
גרסה מחרוזת גרסת ההתראה. הערך הראשוני הוא '1.0'. הגרסה הזו שונה משדות גרסה אחרים.
notificationType INT הערך של 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 – המינוי הסתיים.
  • ‫(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 INT סוג ההתראה. הערכים האפשריים:
  • ‫(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: מציין את סוג ההחזר שביטל את הרכישה.

TestNotification

אובייקט TestNotification מכיל את השדות הבאים:

{
  "version": string
}
שם הנכס הערך תיאור
גרסה מחרוזת גרסת ההתראה. הערך הראשוני הוא '1.0'. הגרסה הזו שונה משדות גרסה אחרים.

דוגמה

דוגמה להודעת בדיקה:

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