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

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

توفّر 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 التي تحدّدها. يعمل رقم تعريف الفئة كمعرِّف فريد ستشير إليه كلما استخدمته لإنشاء مثيل جديد لـ "عنصر البطاقات".

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

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

على سبيل المثال، عند إنشاء تذكرة Event Ticket API باستخدام 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 التي تحدّدها. إنّ رقم تعريف العنصر هذا هو معرّف فريد ستشير إليه عند إصدار البطاقة لأحد المستخدمين.

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

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

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

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

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

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

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

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