نظرة عامة على فئات البطاقات والعناصر

يحدّد مكونان في جميع البطاقات التي يمكنك إصدارها للمستخدم النهائي لحفظها في "محفظة Google" هما: فئة البطاقات وعنصر البطاقات. في أيّ وقت تصدر فيه بطاقة لمستخدم، يجب توفير مثيل لـ "فئة البطاقات" و"عنصر البطاقات" لتحديد نوع البطاقة التي يجب إنشاؤها بالإضافة إلى التفاصيل التي يجب عرضها على البطاقة، مثل قيمة بطاقة الهدايا أو اسم حامل التذكرة.

توفّر Google Wallet API مجموعة محدّدة مسبقًا من فئات البطاقات وعناصر البطاقات التي تنشئ نُسخًا منها، ثم تستخدمها لإنشاء بطاقة يتم إصدارها لمستخدم، مثل GiftCardClass وGiftCardObject وGenericClass وGenericObject وغير ذلك.

يتم تعريف كل مثيل من "فئة البطاقات" و"عنصر التمرير" باعتباره كائن JSON يتضمّن مجموعة من السمات المطلوبة والاختيارية التي تتوافق مع حالة الاستخدام المحدّدة المخصّصة لنوع البطاقة هذا.

فئات البطاقات

يمكنك اعتبار "فئة البطاقات" نموذجًا مشترَكًا يُستخدم لإنشاء بطاقة واحدة أو أكثر ستصدرها للمستخدمين. تحدّد فئة البطاقات مجموعة شائعة من السمات التي سيتم تضمينها في جميع البطاقات التي تشير إليها.

على سبيل المثال، يحدّد المثال التالي من EventTicketClass الحقول الشائعة لكل التذاكر التي تم إصدارها لفعالية قادمة(المكان واسم الحدث وجهة الإصدار والتاريخ/الوقت).

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "eventName": {
    "defaultValue": {
      "language": "en-US",
      "value": "Google Live"
    }
  },
  "venue": {
    "name": {
      "defaultValue": {
        "language": "en-US",
        "value": "Shoreline Amphitheater"
      }
    },
    "address": {
      "defaultValue": {
        "language": "en-US",
        "value": "ADDRESS_OF_THE_VENUE"
      }
    }
  },
  "dateTime": {
    "start": "2023-04-12T11:30"
  },
  "reviewStatus": "UNDER_REVIEW"
}
  

يتطلب كل مثيل من فئة البطاقات سمة id التي تحدّدها. يعمل رقم تعريف الفئة هذا كمعرّف فريد ستشير إليه عند استخدامه لإنشاء مثيل جديد من "عناصر البطاقات".

عناصر التمرير

يحدِّد عنصر "فئة البطاقات" مجموعة من الخصائص المشتركة لاستخدامها في بطاقة واحدة أو أكثر، في حين يحدّد عنصر البطاقات التفاصيل الفريدة لبطاقة معيّنة يتم إصدارها لمستخدم محدّد.

على سبيل المثال، عند إنشاء "بطاقة تذكرة لحضور فعالية" باستخدام Google Wallet API، يتضمّن المثال EventTicketObject سمات للمقعد المخصّص لتلك التذكرة لأنّ هذه القيم ستكون فريدة لكل تذكرة يتم إصدارها.

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "9"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "L"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "45"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "7C"
      }
    }
  },
  "barcode": {
    "type": "BARCODE_TYPE_UNSPECIFIED",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}
  

يتطلّب كل مثيل لكائن البطاقات السمة id التي تحدِّدها. يعمل رقم تعريف العنصر هذا كمعرّف فريد عليك الرجوع إليه عند إصدار البطاقة لأحد المستخدمين.

آلية عمل فئات البطاقات مع عناصر البطاقات

يجب أن توسّع كائنات البطاقات نسخة عن "فئة البطاقات" إما من خلال الإشارة إلى معرّف الفئة الخاص بها أو تضمين تعريف فئة البطاقات بالكامل. تشير هذه العلاقة بين "فئة البطاقات" و"مثيل عنصر البطاقات" إلى أنّه يمكنك ضبط السمات المشتركة في جميع البطاقات التي تم إصدارها وتعديلها من خلال النسخة الخاصة بـ "فئة البطاقات"، والخصائص الفريدة الخاصة ببطاقة فردية في النسخة الخاصة بـ "البطاقات".

على سبيل المثال، يوضِّح الرسم البياني التالي الخاص بتذكرة فعالية بسيطة كيفية دمج الحقول المحدّدة في EventTicketClass المشتركة والحقول الخاصة بتذكرة معيّنة والمحدّدة في EventTicketObject لإنشاء البطاقة النهائية الصادرة. يُرجى العلم أنّه تتم الإشارة إلى رقم تعريف فئة البطاقات في السمة classId ضمن عنصر البطاقات.

وسيتم فورًا نشر التغييرات التي يتم إجراؤها على النسخة الافتراضية من فئة البطاقات على جميع الأجهزة التي تشير إليها. وسيرى المستخدمون أي تغييرات تجريها على النسخة الافتراضية لفئة "البطاقات" تظهر في تطبيق "محفظة Google" في المرة التالية التي تتم فيها المزامنة.

إضافة بطاقة إلى "محفظة Google" الخاصة بالمستخدم

لإضافة بطاقة إلى "محفظة Google" الخاصة بالمستخدم، عليك إنشاء رمز JSON المميّز للويب (JWT) يتضمّن المطالبات التي تقدّمها أنت (جهة الإصدار) بشأن النسخة الافتراضية لـ Pass Object والتي سيتمّ حفظها في "محفظة Google" الخاصة بالمستخدم، والأهم من ذلك هو معرّف العنصر لنسخة عنصر البطاقات التي تصدرها للمستخدم. يتم بعد ذلك تسليم JWT إلى المستخدم بالنقر على زر الإضافة إلى "محفظة Google" أو رابط الإضافة إلى "محفظة Google".

بعد أن ينقر المستخدم على الزر أو الرابط لإضافة بطاقة تم إصدارها إلى "محفظة Google"، يتم ربط رابط نسخة البطاقات التي تم ترميزها في JWT بحساب هذا المستخدم على Google. ويعني هذا أنّه عندما ينقر المستخدم على الزر مرّة أخرى، سيظهر رابط يؤدي إلى هذا العنصر من البطاقات، لذلك لن تتم إضافة النُسخ المكرّرة إلى محفظة المستخدم.

إذا أزال أحد المستخدمين بطاقة من تطبيق "محفظة Google"، سيتم تلقائيًا إلغاء ربط مثيل "البطاقات" المقابلة لدى المستخدم، ولكن لن يتم حذفه. وهذا يعني أنّه يمكن للمستخدم النقر على زر أو الرابط الإضافة إلى "محفظة Google" مرة أخرى لحفظ البطاقة بدون الحاجة إلى إنشاء مثيل جديد من "عنصر البطاقات" أو JWT.