כרטיסים שמקושרים באופן אוטומטי

רקע

התכונה 'כרטיסים מקושרים באופן אוטומטי' מאפשרת לכם לשלוח כרטיסים נוספים למשתמש שכבר יש לו את הכרטיס הקיים שלכם ב-Google Wallet. אפשר גם לקשר מראש כרטיסים לכרטיס ראשי כשהמשתמש שומר את הכרטיס הראשי (העיקרי). הכרטיס המקושר באופן אוטומטי מקובץ עם הכרטיס הראשי, עם הודעה מעל הכרטיס הראשי על כך שקישרתם כרטיס חדש. סוגי הכרטיסים הבאים נתמכים ככרטיסים ראשיים או מקושרים.

  • כרטיס לאירוע
  • כרטיס עלייה למטוס
  • כרטיס לתחבורה ציבורית
  • ההצעה
  • כרטיס מתנה
  • כרטיס מועדון לקוחות
  • כרטיס גנרי
דוגמה ראשית לכרטיס מקושר אוטומטי דוגמה משנית של כרטיס שקושר אוטומטית
כרטיס ראשי עם ההודעה על הוספת כרטיס חדש כרטיס חדש שמקושר לכרטיס הראשי

תרחישים לדוגמה

יכול להיות שתצטרכו לקשר כרטיסים לכרטיס קיים במגוון תרחישים לדוגמה. לדוגמה:

  • מקשרים מבצע לכרטיס מועדון לקוחות קיים.
  • לקשר שובר לארוחה לכרטיס עלייה למטוס או לכרטיס לאירוע.
  • קישור של כרטיס חניה לכרטיס לאירוע.

כמה שיקולים בזמן השימוש בכרטיסים שמקושרים אוטומטית

  • באובייקט הראשי ובאובייקט המקושר צריך להשתמש באותו מזהה מנפיק (issuerId).
  • יש מגבלה של 50 אובייקטים מקושרים לכל אובייקט ראשי.
  • דחיפת הכרטיסים המקושרים באופן אוטומטי לא מובטחת, והפעולה הזו נחשבת הטובה ביותר. המשתמשים יכולים לבטל את ההסכמה לקבלת כרטיסים שמקושרים באופן אוטומטי. אם התרחיש לדוגמה הוא קריטי והמשתמש חייב לקבל את הכרטיס המקושר, מומלץ ליצור קשר דרך ערוץ אחר כדי לוודא שהמשתמש מוסיף את הכרטיס.
  • העדכונים במדיניות ה-AUP של Google Wallet כוללים הנחיות לשימוש בכרטיסים מקושרים באופן אוטומטי, שעליכם לפעול לפיהן.

שלבי ההטמעה

אם כבר יצרתם אובייקט ראשי, אתם יכולים לדלג על שלב 1.

  1. יוצרים אובייקט מכל סוג כרטיס שמופיע עם הפרמטרים הנדרשים. זהו האובייקט הראשי.
  2. יצירת אובייקט נוסף מסוג כרטיס כלשהו שמופיע ברשימה. זה יהיה האובייקט המקושר.
  3. לפני או אחרי שמירת האובייקט הראשי, מעדכנים את האובייקט הראשי עם מזהה האובייקט המקושר בפרמטר linkObjectIds.

יש עומס מינימלי נדרש כדי להגדיר את linkedObjectIds בכרטיס ראשי. 3 הפרמטרים הנדרשים הם:

  1. ISSUERID.PRIMARY_OBJECT_ID
  2. ISSUERID.PRIMARY_CLASS_ID
  3. ISSUERID.LINKED_OBJECT_ID

דוגמה לבקשת JSON להוספת אובייקט מקושר לאובייקט Pass

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
  }
  …

דוגמה לתגובה בפורמט JSON אחרי קישור אובייקט לאובייקט כרטיס

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

התנהגות צפויה

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

טיפול בחריגות

שגיאות פוטנציאליות עשויות להתרחש כתוצאה משימוש שגוי ב-API, למשל:

Message סיבה
לאובייקט הראשי ולאובייקט המקושר אין את אותו מזהה מנפיק. אי אפשר לצרף אובייקט מקושר לאובייקט של מנפיק אחר.
האובייקט הראשי והאובייקט המקושר מתייחסים לאותו אובייקט. אי אפשר לצרף את אותו אובייקט כמו linkedObject.
האובייקט המקושר לא קיים. האובייקט המקושר צריך להיות כבר מוכנס ל-Wallet API.
לאובייקט המקושר יש כבר אובייקט מקושר אחר. אי אפשר להוסיף אובייקטים מקושרים בתצוגת עץ. לא ניתן לקשר אובייקט מקושר לאובייקט מקושר אחר.
האובייקט כבר מקושר לאובייקט אחר. אי אפשר להוסיף אובייקטים מקושרים בתצוגת עץ. אובייקט ראשי לא יכול להיות אובייקט מקושר בפני עצמו.
אי אפשר להוסיף עוד אובייקטים מקושרים, חרגתם מהמגבלה. הגעתם למגבלה של 50 כרטיסים מקושרים בכרטיס הראשי.