איך מנפיקים wallet passes מותאמים אישית דרך API

wallet pass API מאפשר ל-backend שלכם ליצור כרטיס לכל לקוח, עם השם, היתרה, הברקוד והמיקומים שלו, ולעדכן אותו בכל פעם שהנתונים משתנים. מעצבים תבנית פעם אחת, שולחים ערכים אישיים לכל משתמש, ומקבלים בחזרה install link ל-Apple Wallet או save link ל-Google Wallet.

לא כל צוות צריך את זה. אבל לסטארטאפים ישראליים ולצוותי API-first, שבהם היתרה, המנוי או ההזמנה כבר חיים במערכת משלכם, זו בדרך כלל נקודת הפתיחה הטבעית. הדוגמאות לקוחות מ-Wallet passes API של Pushwoosh, שבו כל כרטיס קשור ל-User ID שמניע גם את ה-push, האימייל וה-journeys שלכם.

מתי ה-API עדיף על ה-builder

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

הסתכלו על עמודת ה-journey לפני שאתם כותבים שורת קוד. אם הטריגר הוא פעולה של לקוח ש-Pushwoosh כבר עוקבת אחריה, שלב Issue Wallet Pass ב-Customer Journey חוסך לא פעם את הקוד המותאם.

תבניות וערכים אישיים

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

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

ב-journey, שלב Issue Wallet Pass מקבל את קמפייני הכרטיסים של Apple ו-Google (apple_campaign_id, google_campaign_id) ואת ה-personal_values למילוי. שלב 1 יכול להנפיק את שתי הגרסאות לאותו User ID, וזה חשוב בישראל, שבה חדירת ה-iPhone גבוהה ו-Android עדיין חזק.

ה-flow של Apple Wallet

כל מה שה-pass builder של Apple עושה זמין גם ב-Apple Wallet PassKit API: יצירה, עדכון, רשימה, הורדה ומחיקה של כרטיסים.

לאינטגרציה טיפוסית יש 4 שלבים.

צריך תעודת Pass Type ID (.p12) לכל אפליקציה וחשבון Apple Developer ($99 לשנה). ההגדרה מפורטת ב-תיעוד הגדרת Wallet pass ל-iOS.

ה-flow של Google Wallet

ה-Google Wallet API מכסה את אותו מחזור חיים לכרטיסי Google.

צריך Issuer ID מ-Google Pay & Wallet Console, עם חשבון השירות של Pushwoosh מוזמן ל-issuer שלכם, פעם אחת לכל אפליקציה. ההגדרה מפורטת ב-תיעוד הגדרת Google Wallet.

עדכונים בקנה מידה

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

עדכון שקט יכול לרוץ בכל שעה, גם בשבת: הכרטיס מתרענן ואף אחד לא מקבל התראה. מה שכדאי לתזמן הוא ההתראה עצמה. אם ריצת העדכון מצמידה change message או notifyMessage, לקהלים מסורתיים עדיף להריץ אותה אחרי צאת השבת או החג, ואת שאר העדכונים להשאיר שקטים.

3 כללים שומרים על ריצות עדכון גדולות:

• מתחילים מהכרטיס הנוכחי. העדכון של Apple מקבל את אובייקט הכרטיס המלא, אז שולפים את הכרטיס ומשנים רק את הערכים שזזו. העדכון של Google עושה patch לאובייקט.
• מחליטים על התראות שדה אחרי שדה. ב-Apple רק שדות עם change message מציגים התראה במסך הנעילה. ב-Google, notifyOnUpdate מבקש מ-Google התראה משלה, שיוצאת רק בכרטיסי loyalty, event ticket ו-flight, לכל היותר 3 לכרטיס ב-24 שעות. notifyMessage שולח טקסט התראה משלכם ל-Android בכל סוג כרטיס.
• ההתראות נשארות על הכרטיס. Apple ו-Google מתירות התראות על הכרטיס, לא מבצעים.

דוגמאות קוד

שני ה-APIs משתמשים ב-base URL https://apple-passkit.svc-nue.pushwoosh.com ובטוקן הגישה ל-API של Pushwoosh בכותרת Authorization: Token <api-token>. גופי הבקשות למטה הם הדוגמאות מתוך ה-API reference.

יצירת כרטיס Apple Wallet: POST /api/pass/create. התגובה מחזירה את ה-serialNumber של הכרטיס.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

יצירת כרטיס Google Wallet: POST /api/google/pass/create. התגובה מחזירה את ה-serialNumber ו-saveLink.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

לעדכון, שולחים את התוכן החדש עם המספר הסידורי: POST /api/pass/update/{serialNumber} ל-Apple, POST /api/google/pass/update/{serialNumber} ל-Google.

Builder, API או journey: כלל מהיר

משתמשים ב-builder כדי לעצב ולבדוק. משתמשים בשלב ה-journey כשהטריגר הוא אירוע לקוח שכבר נמצא ב-Pushwoosh, כמו הרשמה או רכישה ראשונה. משתמשים ב-API כשהטריגר או הנתונים חיים ב-backend שלכם.

רוב הצוותים בסוף משתמשים בכל ה-3, וזה בסדר: ה-builder לעיצוב, ה-journeys לרגעים במחזור החיים, ה-API ליתרות ולסטטוס בזמן אמת. הטעות היא להכריח 1 מהם לעשות את העבודה של האחרים.

בישראל, שבה WhatsApp הוא ערוץ התקשורת הדומיננטי, צוותים רבים מפיצים את קישור ההתקנה דווקא שם. ה-API מחזיר install link או save link, ובזכות אותו User ID אפשר לשלוח אותו ב-WhatsApp מתוך אותו journey, בלי לייצא רשימות לספק נפרד.

להתאים אישית כל כרטיס בקנה מידה עם Pushwoosh

Pushwoosh נותנת builder ויזואלי, שלב ב-journey ו-API ל-כרטיסי Apple Wallet ו-Google Wallet נייטיב, בלי ספק pass נפרד באמצע. כל כרטיס חולק User ID עם ה-push, ה-in-app, האימייל, ה-SMS וה-WhatsApp שלכם, כך שסט נתונים 1 מניע כל ערוץ. הנתונים מעובדים על תשתית עם הסמכות SOC 2 Type 2 ו-ISO 27001:2022, בהתאמה ל-GDPR, עם מרכזי נתונים באיחוד האירופי ובארה”ב.

התאמה אישית בקנה מידה היא לא עניין של עוד תבניות. היא מקור אמת 1 שכל כרטיס בכל ארנק משקף.

שאלות נפוצות