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

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

توفّر واجهة 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) الذي يحتوي على مطالبات. أنت (جهة الإصدار) بصدد إنشاء مثيل عنصر التفويض الذي سيتم حفظه في "محفظة Google" للمستخدم. والأهم من ذلك، رقم تعريف العنصر لمثيل كائن البطاقات الذي تصدره للمستخدم. رمز JWT يتم تسليمه إلى المستخدم عبر زر الإضافة إلى محفظة Google أو زر الإضافة إلى محفظة Google .

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

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