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

בנושא הזה מפורטים ומתוארים סוגי ההתראות בזמן אמת למפתחים שאפשר לקבל מ-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 Developer 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 > Account > Subscriptions. המינוי בוטל אבל התוקף שלו עדיין לא פג כשהמשתמש ביצע את השחזור. מידע נוסף זמין במאמר שחזור.
  • (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
  }
}

שימוש ב-VoidedPurchaseNotification

כשלקוח RTDN מקבל VoidedPurchaseNotification, חשוב לשים לב למידע הבא:

  • packageName: זהו המזהה של האפליקציה.
  • eventTimeMillis: השדה הזה מעדכן את המפתח לגבי המועד שבו בוצע השינוי בסטטוס.
  • purchaseToken: האסימון שסופק למכשיר של המשתמש כשהמוצר נרכש.
  • orderId: זהו המזהה של ההזמנה שמשויכת לעסקה שבוטלה.
  • productType: כאן מצוין אם הרכישה שבוטלה הייתה רכישה מתוך האפליקציה או מינוי.
  • refundType: כאן מצוין סוג ההחזר הכספי שגרם לביטול הרכישה.

אם כל מה שצריך לעשות כדי לבצע התאמות בהרשאות הוא לאתר את הרכישה וההזמנה הנכונות, אז יש לך את כל המידע הדרוש בשלב הזה. כדי לקבל מידע נוסף על הרכישה שבוטלה, כדאי לעיין ב-Google Play Voided Purchases API, שהוא מודל משיכה שמספק נתונים נוספים על רכישות שבוטלו בין חותמת זמן נתונה.

ברכישות של כמה פריטים שבוטלו חלקית, השדה refundableQuantity שמסופק על ידי purchases.products מכיל את מספר המוצרים שנותרו מהרכישה שלא בוטלו.

TestNotification

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

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

דוגמה

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

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