Создавайте пропуска в Интернете с помощью API Google Кошелька.

Создавайте пропуска в Интернете с помощью API Google Кошелька.

О практической работе

Последнее обновление: янв. 19, 2023

Авторы: Nick Alteen

1. Введение

Обзор

API Google Кошелька позволяет взаимодействовать с пользователями с помощью различных типов пропусков: карты лояльности, специальные предложения, подарочные карты, билеты на мероприятия, транзитные билеты, посадочные талоны и многое другое. Каждый тип прохода или класс прохода содержит поля и функции, специфичные для конкретного случая использования, которые улучшают взаимодействие с пользователем.

Однако они могут не подходить для каждого случая использования. Чтобы создать более индивидуальный подход, вы можете использовать общий тип пропуска. Вот несколько примеров использования универсального типа прохода:

• Парковочные талоны
• Членские билеты библиотеки
• Ваучеры с сохраненной стоимостью
• Членские билеты в тренажерный зал
• Бронирование

Вы можете использовать общие проходы для любого варианта использования, который может быть представлен с помощью:

• До трех строк информации
• (Необязательно) Графический штрих-код
• (Необязательно) Раздел «Подробности»

Дополнительную информацию об API Google Кошелька или добавлении кнопки «Добавить в Google Кошелек» на веб-страницу см. в документации для разработчиков Google Кошелька .

Все классы и объекты пропуска должны соответствовать Политике допустимого использования .

Передавать классы и объекты

API Google Кошелька предоставляет методы для создания следующего:

Тип	Описание
Пройти класс	Шаблон для отдельного объекта пропуска. Он содержит информацию, общую для всех объектов прохода, принадлежащих этому классу.
Передать объект	Экземпляр проходного класса, уникальный для идентификатора пользователя.

Об этой кодовой лаборатории

В этой лаборатории кода вы выполните следующие задачи.

1. Создайте новую учетную запись эмитента в демо-режиме
2. Создать аккаунт сервиса для выдачи пропусков
3. Создайте новый класс общего пропуска.
4. Создайте новый объект пропуска
5. Создайте кнопку «Добавить в Google Кошелек» , чтобы сохранить пропуск.
6. Отобразите кнопку на своей веб-странице
7. Обработка результата сохранения прохода

Предварительные условия

• Гит
• Аккаунт Google с доступом к консоли Google Cloud.
• Node.js версии 10 или выше

Цели

После завершения этой лаборатории кода вы сможете делать следующее:

• Создание объектов пропусков с помощью Google Кошелька
• Создайте кнопку «Добавить в Google Кошелек»

Поддерживать

Если вы застряли на каком-то этапе работы с кодом, репозиторий GitHub google-pay/wallet-web-codelab содержит полное решение для справки.

2. Настраивать

На этом этапе вы создадите учетную запись эмитента в демонстрационном режиме. Это позволит вам создавать классы пропусков и объекты, которые можно добавлять в кошельки пользователей. Далее вы создадите проект Google Cloud и учетную запись службы. Они будут использоваться для программного создания проходных классов и объектов так же, как и внутренний сервер. Наконец, вы разрешите учетной записи службы Google Cloud управлять пропусками в вашей учетной записи эмитента Google Кошелька.

В общедоступных клиентах, таких как мобильные приложения, можно создавать проходные классы и объекты. Однако более безопасно создавать проходы на частном клиенте, например на внутреннем сервере, или получать их из клиентских приложений с помощью аутентифицированных и безопасных запросов.

Зарегистрируйте аккаунт эмитента Google Кошелька

Учетная запись эмитента необходима для создания и распространения пропусков для Google Кошелька. Вы можете зарегистрироваться с помощью консоли Google Pay & Wallet . Изначально вам будет доступен доступ к созданию пропусков в демонстрационном режиме. Это означает, что только определенные тестовые пользователи смогут добавлять созданные вами проходы. Тестовыми пользователями можно управлять в консоли Google Pay & Wallet.

Дополнительную информацию о демонстрационном режиме см. в разделе Предварительные требования для общего пропуска .

1. Откройте консоль Google Pay и Кошелька.
2. Следуйте инструкциям на экране, чтобы создать учетную запись эмитента.
3. Выберите API Google Кошелька.
4. Подтвердите, что вы понимаете условия обслуживания и политику конфиденциальности.
5. Скопируйте значение идентификатора эмитента в текстовый редактор или другое место.
6. На вкладке «Управление» выберите «Настроить тестовые учетные записи».
7. Добавьте все адреса электронной почты, которые вы будете использовать в этой лаборатории кода.

Включите API Google Кошелька

1. Войдите в консоль Google Cloud.
2. Если у вас еще нет проекта Google Cloud, создайте его сейчас (дополнительную информацию см. в разделе Создание проектов и управление ими ).
3. Включите API Google Кошелька (также называемый API Google Pay for Passes) для своего проекта.

Создайте сервисную учетную запись и ключ

Для вызова API Google Кошелька необходимы учетная запись службы и ключ учетной записи службы. Учетная запись службы — это идентификатор, который вызывает API Google Кошелька. Ключ учетной записи службы содержит закрытый ключ, который идентифицирует ваше приложение как учетную запись службы. Этот ключ конфиденциальен, поэтому сохраняйте его конфиденциальность.

Будьте осторожны при использовании существующей учетной записи службы для этой лаборатории кода, так как она может иметь разрешения на доступ к другим ресурсам, которые не требуются.

Создать учетную запись службы

1. В консоли Google Cloud откройте Сервисные аккаунты .
2. Введите имя, идентификатор и описание своей учетной записи службы.
3. Выберите СОЗДАТЬ И ПРОДОЛЖИТЬ.
4. Выберите ГОТОВО

Создайте ключ сервисного аккаунта

1. Выберите свою учетную запись службы
2. Выберите меню КЛЮЧИ.
3. Выберите «ДОБАВИТЬ КЛЮЧ» , затем «Создать новый ключ».
4. Выберите тип ключа JSON
5. Выберите СОЗДАТЬ

Вам будет предложено сохранить файл ключа на локальной рабочей станции. Обязательно запомните его местоположение.

Установите переменную среды GOOGLE_APPLICATION_CREDENTIALS

Переменная среды GOOGLE_APPLICATION_CREDENTIALS используется Google SDK для аутентификации в качестве учетной записи службы и доступа к различным API для проекта Google Cloud.

1. Следуйте инструкциям в документации по ключам учетной записи Google Cloud Service, чтобы установить переменную среды GOOGLE_APPLICATION_CREDENTIALS
2. Убедитесь, что переменная среды установлена ​​в новом сеансе терминала (MacOS/Linux) или командной строки (Windows) (возможно, вам придется запустить новый сеанс, если он у вас уже открыт)

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Авторизовать учетную запись службы

Наконец, вам необходимо авторизовать учетную запись службы для управления пропусками Google Кошелька.

1. Откройте консоль Google Pay и Кошелька.
2. Выберите пользователей
3. Выберите Пригласить пользователя.
4. Введите адрес электронной почты учетной записи службы (например, [e-mail] ).
5. Выберите «Разработчик» или «Администратор» в раскрывающемся меню «Уровень доступа».
6. Выберите Пригласить

3. Запустите пример приложения Node.js.

Продолжительность 10:00

На этом этапе вы запустите пример приложения Node.js, которое действует как веб-сайт для покупок и внутренний сервер.

Клонировать образец репозитория

Репозиторий google-pay/wallet-web-codelab содержит пример проекта на основе Node.js и различные файлы сценариев, имитирующие внутренний сервер, используемый для предоставления классов и объектов прохода. Вы отредактируете их, включив кнопку «Добавить в Google Кошелек» на экране сведений о продукте.

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.

Если вы введете свой адрес электронной почты и выберите «Создать пропуск» , ничего не произойдет. На следующих шагах вы настроите приложение для создания нового класса и объекта пропуска.

4. Создайте общий класс пропуска

На этом этапе вы создадите базовый класс для своего пропуска. Каждый раз, когда для пользователя создается новый проход, он наследует свойства, определенные в классе прохода.

Класс пропуска, который вы создадите в ходе этой лабораторной работы, использует гибкость универсальных проходов для создания объекта, который работает как идентификационный значок, так и средство отслеживания очков испытаний. Когда объект прохода будет создан из этого класса, он будет выглядеть, как показано на следующем рисунке.

На этом рисунке показано небольшое подмножество свойств, которые можно задать на проходе. Обратитесь к шаблону общего пропуска , чтобы узнать, как различные свойства пропуска влияют на взаимодействие с пользователем.

Классы Pass можно создавать непосредственно в консоли Google Pay & Wallet или с помощью API Google Wallet. В этой лаборатории кода вы создадите класс Generic pass с помощью API. Это соответствует процессу, который частный серверный сервер будет использовать для создания проходных классов.

1. Откройте файл web/app.js
2. Замените значение issuerId на свой идентификатор эмитента из консоли Google Pay и Wallet.

   // TODO: Define Issuer ID
   const issuerId = 'ISSUER_ID';
   

3. Найдите функцию createPassClass
4. В этой функции создайте аутентифицированный HTTP-клиент и используйте API Google Кошелька для создания нового класса пропуска.

   // 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 ). Выходные журналы также будут включать ответ от API Google Кошелька.

5. Создайте объект общего прохода

На этом этапе вы настроите свое приложение Node.js для создания объекта универсального прохода с использованием созданного ранее класса. Существует два потока создания объектов пропуска для пользователей.

Создайте объект pass на внутреннем сервере.

При таком подходе объект pass создается на внутреннем сервере и возвращается клиентскому приложению как подписанный JWT. Это лучше всего подходит для случаев, когда уровень принятия пользователями высок, поскольку гарантирует, что объект существует до того, как пользователь попытается добавить его в свой кошелек.

Создайте объект pass, когда пользователь добавляет его в свой кошелек.

В этом подходе объект пропуска определяется и кодируется в подписанный JWT на внутреннем сервере. Кнопка «Добавить в Google Кошелек» затем отображается в клиентском приложении, которое ссылается на JWT. Когда пользователь нажимает кнопку, JWT используется для создания объекта пропуска. Это лучше всего подходит для случаев, когда принятие пользователем является переменным или неизвестным, поскольку это предотвращает создание и неиспользование объектов прохода. Этот подход будет использоваться в кодовой лаборатории.

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://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 определяется серверным приложением, но выходные данные не возвращаются. Затем вы превратите пропуск в ссылку «Добавить в Google Кошелек» .

6. Создайте кнопку «Добавить в Google Кошелек»

На последнем этапе вы создадите подписанный JWT и вернете ссылку, которую можно будет использовать в кнопке «Добавить в Google Кошелек» . Когда пользователь нажимает кнопку, ему будет предложено сохранить пропуск в свой кошелек.

1. Создайте утверждения JWT, закодируйте их с помощью закрытого ключа сервисного аккаунта и верните кнопку «Добавить в Google Кошелек» со встроенной ссылкой.

   // 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. Когда он появится, нажмите кнопку «Добавить в Google Кошелек».

Если ваша учетная запись эмитента находится в демонстрационном режиме, вы сможете выдавать пропуска только для своих тестовых пользователей. Если вы введете другой адрес электронной почты, вы не сможете добавить пропуск в свой кошелек.

7. Поздравления

Поздравляем, вы успешно интегрировали API Google Кошелька в Интернет!

Узнать больше

Ознакомьтесь с полной интеграцией в репозитории google-pay/wallet-web-codelab на GitHub.

Создавайте пропуска и запрашивайте доступ к производству

Когда вы будете готовы выпустить собственные пропуска в рабочей среде, перейдите в консоль Google Pay & Wallet и запросите доступ к рабочей версии.

Дополнительные сведения см. в разделе «Предварительные требования к веб-API» .