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

1. معرفی

بررسی اجمالی

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

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

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

می‌توانید از مجوزهای عمومی برای هر موردی که می‌توان با آن ارائه کرد استفاده کنید:

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

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

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

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

Google Wallet API روش‌هایی را برای ایجاد موارد زیر نشان می‌دهد:

تایپ کنید

شرح

گذراندن کلاس

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

عبور شی

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

درباره این کد لبه

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

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

پیش نیازها

اهداف

پس از تکمیل این کد لبه، می توانید کارهای زیر را انجام دهید:

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

حمایت کردن

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

2. راه اندازی

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

برای یک حساب Google Wallet Issuer ثبت نام کنید

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

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

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

Google Wallet API را فعال کنید

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

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

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

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

  1. در کنسول Google Cloud، حساب‌های سرویس را باز کنید
  2. نام، شناسه و توضیحات حساب سرویس خود را وارد کنید
  3. ایجاد و ادامه را انتخاب کنید
  4. انجام شد را انتخاب کنید

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

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

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

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

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

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

مجوز حساب سرویس

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

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

3. نمونه برنامه Node.js را راه اندازی کنید

مدت زمان 10:00

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

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

مخزن google-pay/wallet-web-codelab حاوی یک پروژه نمونه مبتنی بر Node.js و فایل‌های اسکریپت مختلف است که از یک سرور backend تقلید می‌کنند که برای تهیه کلاس‌ها و اشیاء پاس استفاده می‌شود. شما این موارد را ویرایش خواهید کرد تا دکمه افزودن به 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 را انتخاب کنید، هیچ اتفاقی نمی افتد. در مراحل بعدی، برنامه را برای ایجاد کلاس و شیء پاس جدید پیکربندی خواهید کرد.

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

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

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

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

  1. فایل web/app.js را باز کنید
  2. شناسه صادرکننده خود را از Google Pay & Wallet Console
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
    جایگزین مقدار issuerId کنید
  3. تابع createPassClass را پیدا کنید
  4. در تابع، یک کلاینت HTTP احراز هویت شده ایجاد کنید و از Google Wallet 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://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/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!');
  }
}
    استفاده کنید.

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

5. یک شی گذر عمومی ایجاد کنید

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

شی pass را در سرور باطن ایجاد کنید

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

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

در این رویکرد، شی pass تعریف شده و در یک JWT امضا شده در سرور باطن رمزگذاری می شود. سپس یک دکمه افزودن به کیف پول Google در برنامه مشتری که به JWT اشاره می کند، ارائه می شود. هنگامی که کاربر دکمه را انتخاب می کند، از JWT برای ایجاد شی عبور استفاده می شود. این بهترین گزینه برای مواردی است که پذیرش کاربر متغیر یا ناشناخته است، زیرا از ایجاد و عدم استفاده اشیاء عبور جلوگیری می کند. این رویکرد در نرم افزار Codelab استفاده خواهد شد.

  1. فایل web/app.js را باز کنید
  2. تابع createPassObject را پیدا کنید
  3. در تابع، یک شی pass جدید برای کاربر خود
    // 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://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/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://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/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 تعریف می شود، اما هیچ خروجی برگردانده نمی شود. در مرحله بعد، پاس را به پیوند افزودن به کیف پول Google تبدیل می کنید.

6. یک دکمه افزودن به کیف پول گوگل ایجاد کنید

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

  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. آدرس ایمیل خود را در فرم وارد کرده و Create pass را انتخاب کنید
  4. وقتی ظاهر شد، دکمه Add to Google Wallet را انتخاب کنید

دکمه افزودن به Google Wallet با موفقیت در قسمت جلوی برنامه ارائه شد

7. تبریک می گویم

نمونه ای از شیء پاس عمومی

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

بیشتر بدانید

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

مجوز ایجاد کنید و درخواست دسترسی تولید کنید

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

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