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

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

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"
  }
}