הוספה ומחיקה של שיחות חוזרות

במדריך הזה מוסבר איך להשתמש בפונקציות קריאה חוזרת (callback) עם Google Wallet API. כשיוצרים או מוחקים כרטיס, Google יכולה לבצע קריאה חוזרת לנקודת קצה של HTTPS שתבחרו. הקריאה החוזרת הזו ספציפית למחלקה, והיא כוללת נתונים על האירוע, כמו המחלקה, האובייקט וסוג האירוע. אפשר להשתמש בנתונים האלה כדי לעקוב אחרי מספר המשתמשים שנוספו או נמחקו. לדוגמה, אפשר להגדיר קריאות חוזרות כדי לשלוח אירועים לאפליקציית ניתוח נתונים, ולעקוב אחרי מעורבות הלקוח במהלך אירועים שיווקיים.

דרישות מוקדמות

לפני שמתחילים, חשוב לעיין בדרישות המוקדמות הבאות:

  • מקימים נקודת קצה (endpoint) של HTTPS שמטפלת בבקשות POST. נקודת הקצה הזו צריכה להיות זמינה לכולם.
  • מעדכנים באופן פרוגרמטי את נקודת הקצה של הקריאה החוזרת לכל כיתה. אפשר לראות את המאפיין callbackOptions לפי מחלקה ב-API בארכיטקטורת REST.
  • מומלץ: להשתמש בספריית Tink כדי לאמת את החתימות.

הטמעה של התקשרות חזרה

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

אימות החתימה

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

בדוגמה הבאה אפשר לראות איך משתמשים בספריית Tink כדי להטמיע את PaymentMethodTokenRecipient: 

import java.io.IOException;
import javax.servlet.http.*;
import com.google.common.io.CharStreams;
import com.google.crypto.tink.apps.paymentmethodtoken.*;

// Replace ISSUER_ID with your issuer id
private static final String RECIPIENT_ID = "ISSUER_ID";

private static final String PUBLIC_KEY_URL = "https://pay.google.com/gp/m/issuer/keys";
private static final String SENDER_ID = "GooglePayPasses";
private static final String PROTOCOL = "ECv2SigningOnly";

private static final GooglePaymentsPublicKeysManager keysManager = new GooglePaymentsPublicKeysManager.Builder()
        .setKeysUrl(PUBLIC_KEY_URL)
        .build();

public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
  try {
    // Extract signed message with signature from POST request body.
    String signedMessage = CharStreams.toString(request.getReader());
    PaymentMethodTokenRecipient recipient =
            new PaymentMethodTokenRecipient.Builder()
                    .protocolVersion(PROTOCOL)
                    .fetchSenderVerifyingKeysWith(keysManager)
                    .senderId(SENDER_ID)
                    .recipientId(RECIPIENT_ID)
                    .build();

    String serializedJsonMessage = recipient.unseal(signedMessage);

    // Use serializedJsonMessage to extract the details
  } catch (Exception e) {
    // Handle the error
  }
}

הפורמט הצפוי של ההודעה

פורמט ההודעה הוא JSON שעבר סריאליזציה למחרוזת עם המאפיינים הבאים:

מזהה תיאור
classId

מזהה המחלקה שמוגדר במלואו. הפורמט שבו משתמשים:

<issuer_id.class_id>
objectId

מזהה אובייקט מוגדר במלואו. הפורמט שבו משתמשים:

<issuer_id.object_id>
expTimeMillis תאריך התפוגה באלפיות השנייה מאז ראשית התקופה של זמן מערכת. אחרי תאריך התפוגה, ההודעה צריכה להיחשב כלא תקפה.
eventType הערך יכול להיות del או save עבור DELETE ו-SAVE.
nonce צופן חד-פעמי (nonce) למעקב אחרי משלוחים כפולים.

טיפול בבקשה משרת של Google

בהמשך מפורטים השדות העיקריים בכותרת של הבקשה שנשלחת לנקודת הקצה של הקריאה החוזרת:

  • User-Agent: Googlebot or Google-Valuables
  • סוג התוכן: application/json

מגדירים את השרת כך שהוא לא ידחה את הבקשה. כדי לעשות זאת, אפשר להגדיר את ההגדרות הבאות ב-robots.txt: 

User-agent: Googlebot
Disallow:

ניסיונות חוזרים

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

משלוחים כפולים

במקרים מסוימים, יכול להיות שיהיו משלוחים כפולים. מומלץ להשתמש ב-nonce כדי לבטל את הכפילויות.