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

يتم تحديد جميع البطاقات تقريبًا التي يمكنك إصدارها ليحفظها المستخدم النهائي في "محفظة 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.

عناصر البطاقات

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

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

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

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

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

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

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

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

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

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