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

במסמך הזה מפורטים סוגי ההתראות למפתחים בזמן אמת שאפשר לקבל מ-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 – המינוי הסתיים.
  • ‫(20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED – עסקה בהמתנה של מינוי בוטלה.
  • ‫(19) SUBSCRIPTION_PRICE_CHANGE_UPDATED – פרטי השינוי במחיר של פריט במינוי עודכנו.
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"
  }
}