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

1. Введение

Обзор

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

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

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

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

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

Образец пропуска Google Wallet на конференцию

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

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

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

Тип

Описание

Сдать класс

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

Передать объект

Экземпляр класса пропуска, уникальный для идентификатора пользователя.

Об этой лабораторной работе

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

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

Предпосылки

Цели

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

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

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

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

2. Настройка

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

Зарегистрируйте учетную запись эмитента Google Wallet

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Следуйте инструкциям в документации по ключам учетной записи Google Cloud Service , чтобы настроить переменную среды 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. Выбрать Пригласить

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

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

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

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

Репозиторий google-pay/wallet-web-codelab содержит пример проекта на базе Node.js и различные файлы скриптов, имитирующие внутренний сервер, используемый для подготовки классов и объектов пропусков. Вам нужно будет отредактировать их, чтобы добавить кнопку «Добавить в 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.

Пример веб-приложения с полем для ввода адреса электронной почты и кнопкой «Создать пропуск»

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

4. Создайте универсальный класс пропуска

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

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

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

  1. Откройте файл web/app.js
  2. Замените значение issuerId на ваш идентификатор эмитента из консоли Google Pay & Wallet. 
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. Найдите функцию createPassClass
  4. В функции создайте аутентифицированный HTTP-клиент и используйте API Google Wallet для создания нового класса пропуска. 
    // 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 Wallet.

5. Создайте объект универсального пропуска

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

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

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

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

При таком подходе объект пропуска определяется и кодируется в подписанный JWT на внутреннем сервере. Затем в клиентском приложении, ссылающемся на JWT, отображается кнопка « Добавить в Google Wallet» . Когда пользователь нажимает кнопку, 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!");

Если вы перезагрузите приложение, введёте свой адрес электронной почты и отправите форму, вы не увидите никаких результатов. Объект купона определяется бэкенд-приложением, но никаких результатов не возвращается. Далее вам нужно преобразовать купон в ссылку «Добавить в Google Wallet» .

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

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

  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. Когда появится кнопка «Добавить в Google Wallet».

Кнопка «Добавить в Google Wallet» успешно отображается на внешнем интерфейсе приложения.

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

Пример объекта Generic Pass

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

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

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

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

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

Более подробную информацию см. в разделе Предварительные требования к веб-API .