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

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

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

שם המאפיין ערך תיאור
גרסה מחרוזת גרסת ההתראה. הערך הראשוני הוא '1.0'. הגרסה הזו שונה משדות גרסה אחרים.
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 API.

שימו לב: השדה הזה לא יכול להופיע יחד עם השדות subscriptionNotification,‏ oneTimeProductNotification,‏ voidedPurchaseNotification ו-testNotification.
testNotification TestNotification

אם השדה הזה מופיע, ההתראה הזו קשורה לפרסום של בדיקה. ההודעות האלה נשלחות רק דרך Google Play Console.

שימו לב: השדה הזה לא יכול להיות מוגדר יחד עם השדות pendingRefundReviewNotification,‏ 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 – המינוי הסתיים.
  • ‫(17) SUBSCRIPTION_ITEMS_CHANGED – פריט בחבילת מינוי השתנה.
  • ‫(18) SUBSCRIPTION_CANCELLATION_SCHEDULED – ביטול של מינוי בתשלומים נקבע לתאריך מסוים בסוף תקופת ההתחייבות.
  • ‫(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 מחרוזת האסימון שסופק למכשיר של המשתמש בזמן הרכישה.
מק"ט מחרוזת מזהה המוצר בחיוב חד-פעמי שנרכש (לדוגמה, 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: מציין את סוג ההחזר שביטל את הרכישה.

PendingRefundReviewNotification

הודעה על PendingRefundReviewNotification נשלחת כשמשתמש מבקש החזר כספי על רכישה, והבקשה דורשת בדיקה של המפתח. כשמקבלים את ההודעה הזו, צריך לבדוק את הבקשה ולשלוח הצעה להחזר כספי והוכחה לשימוש ברכישה תוך 24 שעות באמצעות קריאה ל-API‏ ReviewRefund.

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

{
  "version": string,
  "pendingRefundToken": string,
  "orderId": string,
  "refundReason": int,
  "obfuscatedAccountId": string,
  "obfuscatedProfileId": string
}
שם המאפיין ערך תיאור
גרסה מחרוזת גרסת ההתראה. הערך הראשוני הוא '1.0'. הגרסה הזו שונה משדות גרסה אחרים.
pendingRefundToken מחרוזת אסימון ייחודי שמזהה את הבקשה להחזר כספי שנמצאת בבדיקה. מעבירים את הטוקן הזה כשקוראים ל-ReviewRefund API.
orderId מחרוזת מזהה ההזמנה של הרכישה שנתונה לבדיקה בנוגע להחזר כספי בהמתנה.
refundReason INT הסיבה לבקשת ההחזר הכספי. הסיבה היחידה להחזר כספי שנתמכת בביקורות בהמתנה היא 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
}
שם המאפיין ערך תיאור
גרסה מחרוזת גרסת ההתראה. הערך הראשוני הוא '1.0'. הגרסה הזו שונה משדות גרסה אחרים.

דוגמה

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

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