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

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

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