با استفاده از Google Wallet API مجوزها را در وب ایجاد کنید

۱. مقدمه

نمای کلی

رابط برنامه‌نویسی کاربردی (API) کیف پول گوگل به شما امکان می‌دهد از طریق انواع مختلف کارت‌های اعتباری با کاربران تعامل داشته باشید: کارت‌های وفاداری، پیشنهادها، کارت‌های هدیه، بلیط‌های رویداد، بلیط‌های حمل و نقل عمومی، بلیط‌های سوار شدن به هواپیما و موارد دیگر. هر نوع کارت اعتباری یا کلاس کارت اعتباری، فیلدها و ویژگی‌های خاص خود را برای بهبود تجربه کاربری دارد.

با این حال، این موارد ممکن است برای هر مورد استفاده‌ای مناسب نباشند. برای ایجاد یک تجربه سفارشی‌تر، می‌توانید از نوع گذر عمومی استفاده کنید. در اینجا چند مورد استفاده از نوع گذر عمومی آورده شده است:

  • کارت‌های پارکینگ
  • کارت‌های عضویت کتابخانه
  • کوپن‌های ارزش ذخیره‌شده
  • کارت‌های عضویت باشگاه ورزشی
  • رزروها

شما می‌توانید از پاس‌های عمومی برای هر موردی که با موارد زیر ارائه می‌شود، استفاده کنید:

  • حداکثر سه ردیف اطلاعات
  • (اختیاری) بارکد گرافیکی
  • (اختیاری) بخش جزئیات

نمونه‌ای از کارت اعتباری گوگل والت برای یک رویداد کنفرانس

برای اطلاعات بیشتر در مورد API کیف پول گوگل یا افزودن دکمه «افزودن به کیف پول گوگل» به یک صفحه وب، لطفاً به مستندات توسعه‌دهنده کیف پول گوگل مراجعه کنید.

کلاس‌ها و اشیاء را ارسال کنید

API کیف پول گوگل متدهایی را برای ایجاد موارد زیر ارائه می‌دهد:

نوع

توضیحات

کلاس قبولی

یک الگو برای یک شیء عبوری منفرد. این الگو حاوی اطلاعات مشترک بین همه اشیاء عبوری متعلق به این کلاس است.

شیء عبور

نمونه‌ای از کلاس عبور که مختص یک شناسه کاربری است.

درباره این آزمایشگاه کد

در این آزمایشگاه کد، وظایف زیر را انجام خواهید داد.

  1. ایجاد حساب صادرکننده جدید در حالت آزمایشی
  2. ایجاد حساب کاربری سرویس برای صدور مجوز
  3. یک کلاس Generic pass جدید ایجاد کنید
  4. یک شیء عبور جدید ایجاد کنید
  5. برای ذخیره یک رمز عبور، دکمه « افزودن به کیف پول گوگل» را ایجاد کنید
  6. دکمه را در صفحه وب خود نمایش دهید
  7. نتیجه ذخیره گذر را مدیریت کنید

پیش‌نیازها

اهداف

پس از اتمام این codelab، شما قادر خواهید بود موارد زیر را انجام دهید:

  • با استفاده از Google Wallet اشیاء عبوری ایجاد کنید
  • دکمه افزودن به کیف پول گوگل را ایجاد کنید

پشتیبانی

اگر در هر مرحله از codelab به مشکل برخوردید، مخزن گیت‌هاب google-pay/wallet-web-codelab حاوی یک راه‌حل کامل برای مراجعه است.

۲. راه‌اندازی

در این مرحله، یک حساب صادرکننده (Subscriber) در حالت آزمایشی (demo) ایجاد خواهید کرد. این به شما امکان می‌دهد کلاس‌ها و اشیاء مجوز (pass class) ایجاد کنید که می‌توانند به کیف پول‌های کاربر اضافه شوند. در مرحله بعد، یک حساب پروژه و سرویس Google Cloud ایجاد خواهید کرد. از این حساب‌ها برای ایجاد کلاس‌ها و اشیاء مجوز به صورت برنامه‌نویسی شده، به همان روشی که در سرور backend استفاده می‌شود، استفاده خواهد شد. در نهایت، به حساب سرویس Google Cloud اجازه می‌دهید تا مجوزها را در حساب صادرکننده Google Wallet شما مدیریت کند.

برای حساب صادرکننده کیف پول گوگل ثبت نام کنید

برای ایجاد و توزیع کارت‌های اعتباری برای Google Wallet، یک حساب کاربری صادرکننده ضروری است. می‌توانید با استفاده از کنسول Google Pay & Wallet ثبت نام کنید. در ابتدا، در حالت آزمایشی به ایجاد کارت‌های اعتباری دسترسی خواهید داشت. این بدان معناست که فقط کاربران آزمایشی خاص می‌توانند کارت‌های اعتباری ایجاد شده توسط شما را اضافه کنند. کاربران آزمایشی را می‌توان در کنسول Google Pay & Wallet مدیریت کرد.

برای اطلاعات بیشتر در مورد حالت آزمایشی، به پیش‌نیازهای عمومی مراجعه کنید.

  1. کنسول Google Pay & Wallet را باز کنید
  2. برای ایجاد حساب صادرکننده، دستورالعمل‌های روی صفحه را دنبال کنید
  3. انتخاب API کیف پول گوگل
  4. تأیید کنید که شرایط خدمات و سیاست حفظ حریم خصوصی را درک می‌کنید
  5. مقدار شناسه صادرکننده را در یک ویرایشگر متن یا مکان دیگر کپی کنید
  6. در زیر برگه مدیریت ، گزینه تنظیم حساب‌های آزمایشی را انتخاب کنید.
  7. هر آدرس ایمیلی که در این آزمایشگاه کد استفاده خواهید کرد را اضافه کنید

فعال کردن API کیف پول گوگل

  1. وارد کنسول گوگل کلود شوید
  2. اگر از قبل پروژه گوگل کلود ندارید، همین حالا یکی ایجاد کنید (برای اطلاعات بیشتر به ایجاد و مدیریت پروژه‌ها مراجعه کنید)
  3. API کیف پول گوگل (که به آن API پرداخت گوگل برای کارت‌های اعتباری نیز گفته می‌شود) را برای پروژه خود فعال کنید.

یک حساب کاربری و کلید سرویس ایجاد کنید

یک حساب کاربری سرویس و یک کلید حساب کاربری سرویس برای فراخوانی API کیف پول گوگل ضروری هستند. حساب کاربری سرویس، هویتی است که API کیف پول گوگل را فراخوانی می‌کند. کلید حساب کاربری سرویس حاوی یک کلید خصوصی است که برنامه شما را به عنوان حساب کاربری سرویس شناسایی می‌کند. این کلید حساس است، بنابراین آن را محرمانه نگه دارید.

ایجاد حساب کاربری سرویس

  1. در کنسول گوگل کلود، بخش حساب‌های سرویس (Service Accounts) را باز کنید.
  2. نام، شناسه و توضیحی برای حساب سرویس خود وارد کنید
  3. ایجاد و ادامه را انتخاب کنید
  4. انتخاب کنید انجام شد

ایجاد کلید حساب سرویس

  1. حساب کاربری سرویس خود را انتخاب کنید
  2. منوی کلیدها را انتخاب کنید
  3. گزینه ADD KEY و سپس Create new key را انتخاب کنید.
  4. نوع کلید JSON را انتخاب کنید
  5. ایجاد را انتخاب کنید

از شما خواسته می‌شود که فایل کلید را در رایانه‌ی محلی خود ذخیره کنید. حتماً محل آن را به خاطر بسپارید.

متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید

متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS توسط SDK های گوگل برای احراز هویت به عنوان یک حساب کاربری سرویس و دسترسی به API های مختلف برای یک پروژه Google Cloud استفاده می شود.

  1. برای تنظیم متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS دستورالعمل‌های موجود در مستندات کلیدهای حساب سرویس ابری گوگل را دنبال کنید.
  2. تأیید کنید که متغیر محیطی در یک جلسه جدید ترمینال (MacOS/Linux) یا خط فرمان (Windows) تنظیم شده است (اگر از قبل یک جلسه باز دارید، ممکن است لازم باشد یک جلسه جدید را شروع کنید) 
    echo $GOOGLE_APPLICATION_CREDENTIALS

حساب سرویس را مجاز کنید

در نهایت، برای مدیریت مجوزهای Google Wallet، باید حساب سرویس را تأیید کنید.

  1. کنسول Google Pay & Wallet را باز کنید
  2. کاربران را انتخاب کنید
  3. دعوت از کاربر را انتخاب کنید
  4. آدرس ایمیل حساب سرویس را وارد کنید (مثلاً test-svc@myproject.iam.gserviceaccount.com )
  5. از منوی کشویی سطح دسترسی ، توسعه‌دهنده یا مدیر را انتخاب کنید.
  6. دعوت را انتخاب کنید

۳. برنامه نمونه Node.js را اجرا کنید

مدت زمان ۱۰:۰۰

در این مرحله، شما یک برنامه Node.js نمونه اجرا خواهید کرد که به عنوان یک وب‌سایت خرید و سرور backend عمل می‌کند.

مخزن نمونه را کلون کنید

مخزن google-pay/wallet-web-codelab شامل یک پروژه نمونه مبتنی بر Node.js و فایل‌های اسکریپت مختلفی است که از یک سرور backend که برای تأمین کلاس‌ها و اشیاء pass استفاده می‌شود، تقلید می‌کنند. شما این فایل‌ها را ویرایش خواهید کرد تا دکمه « افزودن به Google Wallet» را در صفحه جزئیات محصول قرار دهید.

  1. مخزن را به ایستگاه کاری محلی خود کلون کنید 
    git clone https://github.com/google-pay/wallet-web-codelab.git

نصب وابستگی‌های پروژه

  1. مخزن کلون شده را در ترمینال یا خط فرمان خود باز کنید.
  2. به دایرکتوری web بروید (این برنامه‌ای است که در ادامه‌ی این آزمایشگاه کد، آن را تغییر خواهید داد) 
    cd web
  3. وابستگی‌های Node.js را نصب کنید 
    npm install .
  4. برنامه را شروع کنید 
    node app.js
  5. برنامه را در حال اجرا روی http://localhost:3000 باز کنید.

یک برنامه وب نمونه با فیلدی برای وارد کردن آدرس ایمیل و دکمه ایجاد رمز عبور

اگر آدرس ایمیل خود را وارد کنید و Create pass را انتخاب کنید، هیچ اتفاقی نمی‌افتد. در مراحل بعدی، برنامه را برای ایجاد یک کلاس و شیء pass جدید پیکربندی خواهید کرد.

۴. یک کلاس Generic pass ایجاد کنید

در این مرحله، شما کلاس پایه را برای pass خود ایجاد خواهید کرد. هر زمان که یک pass جدید برای یک کاربر ایجاد شود، ویژگی‌های تعریف شده در کلاس pass را به ارث می‌برد.

کلاس pass که در طول این کدنویسی ایجاد خواهید کرد، از انعطاف‌پذیری Generic passes برای ایجاد شیء‌ای استفاده می‌کند که هم به عنوان نشان هویت و هم ردیاب نقاط چالش عمل می‌کند. وقتی یک شیء pass از این کلاس ایجاد می‌شود، مانند تصویر زیر خواهد بود.

کلاس‌های Pass را می‌توان مستقیماً در کنسول Google Pay & Wallet یا با استفاده از API Google Wallet ایجاد کرد. در این آزمایشگاه کد، شما کلاس Generic pass را با استفاده از API ایجاد خواهید کرد. این فرآیندی را دنبال می‌کند که یک سرور خصوصی و backend برای ایجاد کلاس‌های pass استفاده می‌کند.

  1. فایل web/app.js را باز کنید.
  2. مقدار issuerId را با شناسه صادرکننده خود از کنسول Google Pay & Wallet جایگزین کنید. 
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. تابع createPassClass را پیدا کنید.
  4. در تابع، یک کلاینت HTTP احراز هویت شده ایجاد کنید و از API کیف پول گوگل برای ایجاد یک کلاس عبور جدید استفاده کنید. 
    // TODO: Create a Generic pass class
let genericClass = {
  'id': `${classId}`,
  'classTemplateInfo': {
    'cardTemplateOverride': {
      'cardRowTemplateInfos': [
        {
          'twoItems': {
            'startItem': {
              'firstValue': {
                'fields': [
                  {
                    'fieldPath': "object.textModulesData['points']"
                  }
                ]
              }
            },
            'endItem': {
              'firstValue': {
                'fields': [
                  {
                    'fieldPath': "object.textModulesData['contacts']"
                  }
                ]
              }
            }
          }
        }
      ]
    },
    'detailsTemplateOverride': {
      'detailsItemInfos': [
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': "class.imageModulesData['event_banner']"
                }
              ]
            }
          }
        },
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': "class.textModulesData['game_overview']"
                }
              ]
            }
          }
        },
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': "class.linksModuleData.uris['official_site']"
                }
              ]
            }
          }
        }
      ]
    }
  },
  'imageModulesData': [
    {
      'mainImage': {
        'sourceUri': {
          'uri': 'https://codelabs.developers.google.com/static/add-to-wallet-web/images/google-io-2021-card.png'
        },
        'contentDescription': {
          'defaultValue': {
            'language': 'en-US',
            'value': 'Google I/O 2022 Banner'
          }
        }
      },
      'id': 'event_banner'
    }
  ],
  'textModulesData': [
    {
      'header': 'Gather points meeting new people at Google I/O',
      'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.',
      'id': 'game_overview'
    }
  ],
  'linksModuleData': {
    'uris': [
      {
        'uri': 'https://io.google/2022/',
        'description': 'Official I/O \'22 Site',
        'id': 'official_site'
      }
    ]
  }
};

let response;
try {
  // Check if the class exists already
  response = await httpClient.request({
    url: `${baseUrl}/genericClass/${classId}`,
    method: 'GET'
  });

  console.log('Class already exists');
  console.log(response);
} catch (err) {
  if (err.response && err.response.status === 404) {
    // Class does not exist
    // Create it now
    response = await httpClient.request({
      url: `${baseUrl}/genericClass`,
      method: 'POST',
      data: genericClass
    });

    console.log('Class insert response');
    console.log(response);
  } else {
    // Something else went wrong
    console.log(err);
    res.send('Something went wrong...check the console logs!');
  }
}

وقتی کد شما اجرا می‌شود، یک کلاس pass جدید ایجاد می‌کند و شناسه کلاس را در خروجی نمایش می‌دهد. شناسه کلاس از شناسه صادرکننده و به دنبال آن یک پسوند تعریف‌شده توسط توسعه‌دهنده تشکیل شده است. در این حالت، پسوند روی codelab_class تنظیم شده است (شناسه کلاس شبیه به 1234123412341234123.codelab_class خواهد بود). گزارش‌های خروجی همچنین شامل پاسخ از API کیف پول گوگل نیز خواهند بود.

۵. یک شیء Generic pass ایجاد کنید

در این مرحله، برنامه Node.js خود را طوری پیکربندی خواهید کرد که با استفاده از کلاسی که قبلاً ایجاد کرده‌اید، یک شیء Pass عمومی ایجاد کند. دو جریان برای ایجاد اشیاء Pass برای کاربران وجود دارد.

شیء pass را در سرور backend ایجاد کنید

در این رویکرد، شیء pass در یک سرور backend ایجاد شده و به عنوان یک JWT امضا شده به برنامه کلاینت بازگردانده می‌شود. این روش برای مواردی که پذیرش کاربر بالا است، مناسب‌ترین گزینه است، زیرا قبل از اینکه کاربر سعی کند شیء را به کیف پول خود اضافه کند، از وجود آن اطمینان حاصل می‌کند.

وقتی کاربر شیء pass را به کیف پول خود اضافه می‌کند، آن را ایجاد می‌کند.

در این رویکرد، شیء pass تعریف و در یک JWT امضا شده در سرور backend کدگذاری می‌شود. سپس یک دکمه Add to Google Wallet در برنامه کلاینت که به JWT ارجاع می‌دهد، رندر می‌شود. وقتی کاربر دکمه را انتخاب می‌کند، از JWT برای ایجاد شیء pass استفاده می‌شود. این روش برای مواردی که پذیرش کاربر متغیر یا ناشناخته است، مناسب‌ترین است، زیرا از ایجاد و عدم استفاده از اشیاء pass جلوگیری می‌کند. این رویکرد در codelab استفاده خواهد شد.

  1. فایل web/app.js را باز کنید.
  2. تابع createPassObject را پیدا کنید.
  3. در تابع، یک شیء عبور جدید برای کاربر خود تعریف کنید 
    // TODO: Create a new Generic pass for the user
let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`;
let objectId = `${issuerId}.${objectSuffix}`;

let genericObject = {
  'id': `${objectId}`,
  'classId': classId,
  'genericType': 'GENERIC_TYPE_UNSPECIFIED',
  'hexBackgroundColor': '#4285f4',
  'logo': {
    'sourceUri': {
      'uri': 'https://developers.google.com/static/wallet/site-assets/images/pass-builder/pass_google_logo.jpg'
    }
  },
  'cardTitle': {
    'defaultValue': {
      'language': 'en',
      'value': 'Google I/O \'22'
    }
  },
  'subheader': {
    'defaultValue': {
      'language': 'en',
      'value': 'Attendee'
    }
  },
  'header': {
    'defaultValue': {
      'language': 'en',
      'value': 'Alex McJacobs'
    }
  },
  'barcode': {
    'type': 'QR_CODE',
    'value': `${objectId}`
  },
  'heroImage': {
    'sourceUri': {
      'uri': 'https://developers.google.com/static/wallet/site-assets/images/pass-builder/google-io-hero-demo-only.jpg'
    }
  },
  'textModulesData': [
    {
      'header': 'POINTS',
      'body': '1234',
      'id': 'points'
    },
    {
      'header': 'CONTACTS',
      'body': '20',
      'id': 'contacts'
    }
  ]
};

// TODO: Create the signed JWT and link
res.send("Form submitted!");

اگر برنامه را دوباره بارگذاری کنید، آدرس ایمیل خود را وارد کنید و فرم را ارسال کنید، هیچ خروجی مشاهده نخواهید کرد. شیء pass توسط برنامه backend تعریف می‌شود، اما هیچ خروجی برگردانده نمی‌شود. در مرحله بعد، pass را به یک لینک Add to Google Wallet تبدیل خواهید کرد.

۶. دکمه‌ی «افزودن به کیف پول گوگل» را ایجاد کنید

برای مرحله آخر، شما یک JWT امضا شده ایجاد می‌کنید و لینکی را برمی‌گردانید که می‌تواند در دکمه «افزودن به کیف پول گوگل» استفاده شود. وقتی کاربر دکمه را انتخاب می‌کند، از او خواسته می‌شود که رمز عبور را در کیف پول خود ذخیره کند.

  1. ادعاهای JWT را ایجاد کنید، آنها را با استفاده از کلید خصوصی حساب سرویس رمزگذاری کنید و یک دکمه افزودن به Google Wallet را با پیوند تعبیه شده برگردانید. 
    // TODO: Create the signed JWT and link
const claims = {
  iss: credentials.client_email,
  aud: 'google',
  origins: [],
  typ: 'savetowallet',
  payload: {
    genericObjects: [
      genericObject
    ]
  }
};

const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' });
const saveUrl = `https://pay.google.com/gp/v/save/${token}`;

res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`);
  2. برنامه در حال اجرا در مرورگر خود را دوباره بارگیری کنید
  3. آدرس ایمیل خود را در فرم وارد کنید و گزینه ایجاد رمز عبور را انتخاب کنید.
  4. وقتی ظاهر شد، دکمه «افزودن به کیف پول گوگل» را انتخاب کنید.

دکمه «افزودن به کیف پول گوگل» با موفقیت در صفحه اصلی برنامه نمایش داده می‌شود.

۷. تبریک

یک مثال از شیء Generic pass

تبریک می‌گویم، شما با موفقیت API کیف پول گوگل را در وب ادغام کردید!

بیشتر بدانید

نگاهی به یکپارچه‌سازی کامل در مخزن گیت‌هاب google-pay/wallet-web-codelab بیندازید.

ایجاد مجوزها و درخواست دسترسی به تولید

وقتی آماده صدور مجوزهای خود در محیط عملیاتی شدید، برای درخواست دسترسی به محیط عملیاتی به کنسول Google Pay & Wallet بروید.

برای کسب اطلاعات بیشتر به پیش‌نیازهای Web API مراجعه کنید.