Создавайте пропуска на Android с помощью API Google Wallet.

1. Введение

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

Предпосылки

• Android Studio
• Гит
• Учетная запись Google с доступом к консоли Google Cloud
• Node.js версии 10 или выше

Цели

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

• Добавьте Google Wallet SDK в свое приложение Android
• Проверьте, доступен ли API Google Wallet на устройстве Android.
• Создайте кнопку «Добавить в Google Кошелек»

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

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

2. Настройка

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

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

Зарегистрируйте учетную запись эмитента API 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. Введите адрес электронной почты учетной записи службы (например, [e-mail] )
5. В раскрывающемся меню «Уровень доступа» выберите «Разработчик» или «Администратор».
6. Выбрать Пригласить

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

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

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

На этом рисунке показан небольшой набор свойств, которые можно задать для пропуска. Чтобы узнать, как различные свойства пропуска влияют на взаимодействие с пользователем, обратитесь к шаблону «Универсальный пропуск» .

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

1. Клонируйте репозиторий GitHub google-pay/wallet-android-codelab на локальную рабочую станцию.

   git clone https://github.com/google-pay/wallet-android-codelab.git
   

2. Откройте клонированный репозиторий в терминале или командной строке.
3. Перейдите в каталог backend (эти скрипты имитируют действия бэкэнд-сервера)

   cd backend
   

4. Установка зависимостей Node.js

   npm install .
   

5. В каталоге backend откройте generic_class.js
6. Замените значение issuerId на ваш идентификатор эмитента из консоли Google Pay & Wallet.

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

7. В терминале или командной строке запустите скрипт generic_class.js

   node generic_class.js
   

При запуске вашего кода будет создан новый класс пропуска и выведен его идентификатор. Идентификатор класса состоит из идентификатора эмитента и суффикса, заданного разработчиком. В данном случае суффиксом будет codelab_class (идентификатор класса будет выглядеть примерно так: 1234123412341234123.codelab_class ). В журналах вывода также будет содержаться ответ от API Google Wallet.

4. Откройте проект в Android Studio.

Клонированный вами репозиторий GitHub содержит проект Android с пустой активностью. На этом этапе вам нужно будет отредактировать эту активность, добавив кнопку «Добавить в Google Wallet» на страницу товара.

1. Открыть Android Studio
2. Выберите Файл , затем Открыть.
3. Выберите каталог android в репозитории.
4. Выберите «Открыть»

Добавьте Google Wallet SDK в свое приложение

1. Откройте файл сборки Gradle на уровне модуля ( android/app/build.gradle )
2. Добавьте Google Wallet SDK в раздел dependencies

   // TODO: Add the "com.google.android.gms:play-services-pay" dependency to
   //       use the Google Wallet API
   implementation "com.google.android.gms:play-services-pay:16.0.3"
   

3. Сохранить файл
4. Выберите Файл , затем Синхронизировать проект с файлами Gradle.

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

На этом этапе вы создадите кнопку « Добавить в Google Wallet» и добавите её в существующую активность. Ресурсы для кнопки уже включены в проект. Чтобы добавить кнопку, создайте отдельный файл макета. После добавления кнопка будет выглядеть следующим образом.

Если вы добавляете кнопку в своё приложение, ознакомьтесь с рекомендациями по брендингу , чтобы загрузить SVG-файлы для кнопки на нужном вам языке (языках). Убедитесь, что вы добавляете только графику для поддерживаемых конфигураций. Векторные ресурсы можно импортировать в Android Studio, выбрав Файл > Создать > Векторный ресурс . Выберите «Локальный файл» в мастере, введите имя (например, add_to_google_wallet_button ) и разместите файл на своей рабочей станции.

1. Создайте новый файл макета: app/src/main/res/layout/add_to_google_wallet_button.xml
2. Добавьте следующий контент в новый файл макета

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="48sp"
       android:background="@drawable/add_to_google_wallet_button_background_shape"
       android:clickable="true"
       android:contentDescription="@string/add_to_google_wallet_button_content_description"
       android:focusable="true">
     <ImageView
         android:layout_width="227dp"
         android:layout_height="26dp"
         android:layout_gravity="center"
         android:duplicateParentState="true"
         android:src="@drawable/add_to_google_wallet_button_foreground" />
   </FrameLayout>
   

3. Включите макет add_to_google_wallet_button.xml в файл макета действия оформления заказа ( app/src/main/res/layout/activity_checkout.xml )

   <!--
       TODO: Create the button under `add_to_google_wallet_button.xml`
             and include it in your UI
   -->
   <include
       android:id="@+id/addToGoogleWalletButton"
       layout="@layout/add_to_google_wallet_button"
       android:layout_width="match_parent"
       android:layout_height="48dp"
       android:layout_marginTop="10dp" />
   

6. Проверьте, доступен ли API Google Wallet.

Если пользователь открывает ваше приложение на устройстве, не поддерживающем API Google Wallet, это может вызвать у него негативные эмоции при попытке добавить карту. Если устройство пользователя не поддерживает API Google Wallet, скрытие кнопки « Добавить в Google Wallet» поможет избежать возможных недоразумений. API может быть недоступен по разным причинам, например, из-за устаревших версий Android или сервисов Google Play или из-за недоступности Google Wallet в стране пользователя.

На этом этапе вы добавите в приложение логику, которая проверяет, доступен ли API Google Wallet на устройстве. Если да, кнопка будет отображена в активности. В противном случае кнопка будет скрыта.

Рассмотрите возможность размещения предметно-ориентированной бизнес-логики соответствующим образом, если вы используете другие шаблоны проектирования. Например, если вы используете шаблон Model-View-ViewModel (MVVM), разместите бизнес-логику, связанную с пользовательским интерфейсом, в Activity или Fragment (например, элементы пользовательского интерфейса и результаты действий), а операционную логику — в ViewModel (например, создание клиентских экземпляров и триггеры сетевых вызовов).

1. Откройте файл CheckoutActivity.kt в app/src/main/java/com/google/android/gms/samples/wallet/activity/
2. Создайте свойство класса для экземпляра PayClient

   // TODO: Create a client to interact with the Google Wallet API
   private lateinit var walletClient: PayClient
   

3. Создайте свойство PayClient в методе onCreate

   // TODO: Instantiate the client
   walletClient = Pay.getClient(this)
   

4. Создайте метод, который проверяет, доступны ли SDK и API Google Wallet на устройстве, и обрабатывайте результат.

   // TODO: Create a method to check for the Google Wallet SDK and API
   private fun fetchCanUseGoogleWalletApi() {
     walletClient
       .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
       .addOnSuccessListener { status ->
         if (status == PayApiAvailabilityStatus.AVAILABLE)
           layout.passContainer.visibility = View.VISIBLE
       }
       .addOnFailureListener {
         // Hide the button and optionally show an error message
       }
   }
   

5. Вызовите метод fetchCanUseGoogleWalletApi в методе onCreate , чтобы проверить, доступен ли API Google Wallet.

   // TODO: Check if the Google Wallet API is available
   fetchCanUseGoogleWalletApi()
   

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

Если кнопка «Добавить в Google Wallet» не отображается, проверьте ошибку, возвращаемую методом getPayApiAvailabilityStatus , и журналы, чтобы узнать больше. Возможно, пользователь, о котором идёт речь, получит право использовать API в будущем.

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

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

Теперь, когда вы убедились в доступности API Google Wallet, вы можете создать пропуск и предложить пользователю добавить его в свой кошелёк. Существует два способа создания объектов пропусков для пользователей.

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

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

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

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

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

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

3. В терминале или командной строке запустите файл generic_pass.js

   node generic_pass.js
   

4. Скопируйте выходной токен в буфер обмена или текстовый редактор.

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

В рабочей среде ваша бэкенд-система будет отвечать за создание JWT и их возврат клиентам. В этой лабораторной работе скрипт generic_pass.js эмулирует это поведение и «возвращает» токен для использования в клиентском приложении.

8. Добавьте пропуск в Google Wallet.

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

1. Откройте файл app/src/main/CheckoutActivity.kt
2. Замените значение token на JWT, который вы создали ранее.

   // TODO: Save the JWT from the backend "response"
   private val token = "TOKEN"
   

3. Создайте свойство класса для хранения кода запроса.

   // TODO: Add a request code for the save operation
   private val addToGoogleWalletRequestCode = 1000
   

4. Установите прослушиватель для кнопки «Добавить в Google Wallet»

   // TODO: Set an on-click listener on the "Add to Google Wallet" button
   addToGoogleWalletButton = layout.addToGoogleWalletButton.root
   
   addToGoogleWalletButton.setOnClickListener {
     walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
   }
   

Когда пользователь нажимает кнопку «Добавить в Google Wallet» , вызывается метод walletClient.savePassesJwt . Этот метод предлагает пользователю добавить новый объект купона в свой Google Wallet.

9. Обработайте результат savePassesJwt

На последнем этапе этой лабораторной работы вы настроите свое приложение для обработки результата операции walletClient.savePassesJwt .

1. Откройте файл app/src/main/CheckoutActivity.kt
2. Переопределите метод onActivityResult , чтобы он содержал следующий код

   // TODO: Handle the result
   override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
     super.onActivityResult(requestCode, resultCode, data)
   
     if (requestCode == addToGoogleWalletRequestCode) {
       when (resultCode) {
         RESULT_OK -> {
           // Pass saved successfully. Consider informing the user.
         }
   
         RESULT_CANCELED -> {
           // Save canceled
         }
   
         PayClient.SavePassesResult.SAVE_ERROR ->
           data?.let { intentData ->
             val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
             // Handle error. Consider informing the user.
             Log.e("SavePassesResult", errorMessage.toString())
           }
   
         else -> {
           // Handle unexpected (non-API) exception
         }
       }
     }
   }
   

Теперь ваше приложение способно обрабатывать следующие сценарии:

• Успешное добавление пропуска
• Отмена пользователя
• Неожиданные ошибки

Запустите приложение, чтобы убедиться, что вы можете добавить проход и обработать результат ожидаемым образом.

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

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

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

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

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

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

Более подробную информацию см. в разделе «Предварительные требования Android SDK» .