نمای کلی کلاس‌ها و اشیای مجوزها

تقریباً همه مجوزهایی که می‌توانید برای کاربر نهایی صادر کنید تا در «کیف پول 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 ذخیره کند.