كيف تُصدر بطاقات محفظة رقمية مخصصة عبر API

يتيح API بطاقات المحفظة الرقمية لنظامك الخلفي (backend) إنشاء بطاقة مخصصة لكل عميل، باسمه ورصيده ورمزه الشريطي ومواقعه، ثم تحديثها كلما تغيرت بياناتك. تصمم القالب مرة واحدة، وترسل القيم الشخصية لكل مستخدم، وتحصل على رابط تثبيت (install link) لـ Apple Wallet أو رابط حفظ (save link) لـ Google Wallet.

لا يحتاجه كل فريق. الأمثلة هنا من API بطاقات المحفظة في Pushwoosh، حيث ترتبط كل بطاقة بمعرّف مستخدم (User ID) يقود أيضاً الإشعارات الفورية والبريد الإلكتروني ورحلات العملاء. وهو مناسب خاصة للتطبيقات المالية ومتاجر التجارة الإلكترونية في دول الخليج، حيث يعيش الرصيد والطلبات في أنظمة الشركة نفسها.

متى يتفوّق API على المنشئ

المنشئ هو الأداة الصحيحة لتصميم البطاقة وللإرسالات الصغيرة أو لمرة واحدة. أما API فيتولى المهمة عندما تعتمد البطاقات على بيانات تعيش في أنظمتك الخاصة.

انظر إلى عمود الرحلة قبل أن تكتب أي كود. إذا كان المحفّز إجراءً من العميل يتتبعه Pushwoosh أصلاً، فإن خطوة Issue Wallet Pass في Customer Journey (رحلة العميل) تغنيك غالباً عن الكود المخصص.

في السوق الخليجية يتضح هذا الفرق بسرعة. متجر إلكتروني في السعودية أو الإمارات أو مصر يُصدر بطاقة الولاء عند أول طلب، وهو حدث يتتبعه Pushwoosh أصلاً، فتكفيه خطوة الرحلة. أما التطبيق المالي الذي يقرأ الرصيد والمستوى من نظامه المصرفي، أو تطبيق الخدمات الحكومية الذي يقرأ المواعيد من نظام الحجوزات، فيحتاج إلى API لأن مصدر الحقيقة يعيش خارج المنصة.

القوالب والقيم الشخصية

النمط واحد على المنصتين. القالب يحمل التخطيط والهوية البصرية وبنية الحقول. والقيم الخاصة بكل مستخدم تملؤه لحظة الإصدار.

القيم الشخصية هي ما يتغير من عميل إلى آخر: الاسم، رقم العضوية، النقاط، المستوى، قيمة الرمز الشريطي، تاريخ الانتهاء، أقرب فرع. كل ما عدا ذلك يأتي من القالب، فينطبق أي تغيير في التصميم على كل بطاقة جديدة دون المساس بالتكامل.

في الرحلة، تأخذ خطوة Issue Wallet Pass حملتَي بطاقات Apple وGoogle (apple_campaign_id وgoogle_campaign_id) والقيم الشخصية personal_values المطلوب ملؤها. وخطوة واحدة تستطيع إصدار النسختين لمعرّف المستخدم نفسه، وهذا مهم في منطقة يتجاوز فيها نصيب Android ‏70% ويحمل فيها جزء من العملاء أجهزة iPhone.

تدفق Apple Wallet

كل ما يفعله منشئ بطاقات Apple متاح أيضاً في Apple Wallet PassKit API: إنشاء البطاقات وتحديثها وعرضها وتنزيلها وحذفها.

يتكون التكامل المعتاد من أربع خطوات.

تحتاج إلى شهادة Pass Type ID (.p12) لكل تطبيق، وإلى حساب Apple Developer (بتكلفة $99 سنوياً). الإعداد موضح في وثائق إعداد بطاقات المحفظة على iOS.

تدفق Google Wallet

يغطي Google Wallet API دورة الحياة نفسها لبطاقات Google.

تحتاج إلى Issuer ID من Google Pay & Wallet Console، مع دعوة حساب الخدمة (service account) الخاص بـ Pushwoosh إلى حساب المُصدِر، ويُضبط ذلك مرة واحدة لكل تطبيق. الإعداد موضح في وثائق إعداد Google Wallet.

التحديث على نطاق واسع

في التحديثات يثبت API قيمته. يستطيع سجل النقاط أو نظام الحجوزات تحديث البطاقة في اللحظة التي تتغير فيها القيمة، فتطابق البطاقة في محفظة العميل مصدر الحقيقة لديك. مثال ذلك تطبيق مصرفي رقمي في الخليج يحدّث مستوى العضوية، أو تطبيق خدمات حكومية ضمن مبادرات التحول الرقمي في رؤية 2030 يحدّث موعداً على بطاقة.

ثلاث قواعد تجعل دفعات التحديث الكبيرة آمنة:

• ابدأ من البطاقة الحالية. تحديث Apple يأخذ كائن البطاقة كاملاً، لذا اجلب البطاقة وغيّر القيم التي تغيرت فقط. أما تحديث Google فيعدّل الكائن جزئياً (patch).
• قرّر التنبيهات حقلاً بحقل. في Apple لا تعرض تنبيهاً على شاشة القفل إلا الحقول التي لها رسالة تغيير. وفي Google يطلب notifyOnUpdate من Google تنبيهها الخاص، ولا يعمل إلا على بطاقات الولاء وتذاكر الفعاليات وبطاقات الطيران، بحد أقصى 3 لكل بطاقة خلال 24 ساعة. أما notifyMessage فيرسل نص إشعار Android الخاص بك على أي نوع من البطاقات.
• اجعل التنبيهات عن البطاقة. تسمح Apple وGoogle بالإشعارات المتعلقة بالبطاقة، لا بالعروض الترويجية.

أمثلة الكود

يستخدم كلا الـ API عنوان URL الأساسي https://apple-passkit.svc-nue.pushwoosh.com ورمز الوصول إلى Pushwoosh API في ترويسة Authorization: Token <api-token>. أجسام الطلبات أدناه هي الأمثلة الواردة في مرجع API.

تبقى مراجع API وأمثلة الكود بالإنجليزية، فهي اللغة التي يعمل بها المطورون في المنطقة. أما ما يراه العميل فشأن آخر: عناوين الحقول وقيمها، مثل الاسم والمستوى واسم البرنامج، نصوص عادية ترسلها في الطلب، فيمكن أن تصل البطاقة إلى محفظة العميل بالعربية بالكامل. وإن كان جمهورك يقرأ العربية والإنجليزية معاً، فاحفظ اللغة المفضلة في ملف المستخدم وأرسل القيم المناسبة لكل عميل.

إنشاء بطاقة 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.

المنشئ أم API أم الرحلة: قاعدة سريعة

استخدم المنشئ للتصميم والاختبار. واستخدم خطوة الرحلة عندما يكون المحفّز حدثاً للعميل موجوداً أصلاً في Pushwoosh، مثل التسجيل أو أول عملية شراء. واستخدم API عندما يعيش المحفّز أو البيانات في نظامك الخلفي.

معظم الفرق ينتهي بها الأمر إلى استخدام الثلاثة، ولا بأس في ذلك: المنشئ للتصميم، والرحلات للحظات دورة حياة العميل، وAPI للأرصدة والحالات اللحظية. الخطأ هو إجبار أحدها على أداء مهام الآخرين.

خصّص كل بطاقة على نطاق واسع مع Pushwoosh

يمنحك Pushwoosh منشئاً مرئياً وخطوة في الرحلة وAPI لـ بطاقات Apple Wallet وGoogle Wallet الأصلية، دون مزوّد بطاقات منفصل في المنتصف. تتشارك كل بطاقة معرّف المستخدم مع الإشعارات الفورية والرسائل داخل التطبيق والبريد الإلكتروني وSMS، فتقود مجموعة بيانات واحدة كل القنوات. وتُعالج هذه البيانات على بنية حاصلة على شهادتي ISO 27001:2022 وSOC 2 Type 2، ومتوافقة مع GDPR، مع مراكز بيانات في الاتحاد الأوروبي والولايات المتحدة.

التخصيص على نطاق واسع ليس مسألة قوالب أكثر. إنه مصدر حقيقة واحد تعكسه كل بطاقة في كل محفظة.

الأسئلة الشائعة