Как настроить карты и билеты в Google Кошельке

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

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

• Лояльность
• Специальное предложение
• Подарочная карта
• Билет на мероприятие
• Посадочный талон
• QR Tickets

Фонд: cardTemplateOverride

Основной инструмент для настройки макета карты – объект classTemplateInfo.cardTemplateOverride, который вы определяете в ресурсе Class карты (например, EventTicketClass, LoyaltyClass). Этот объект позволяет структурировать карту, определяя строки и элементы внутри них, что дает вам контроль над тем, как представлена информация.

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

1. Как настроить стандартные поля Кошелька

Стандартные поля – это стандартные свойства, доступные в Google Wallet API для определенного типа карты. Эти поля имеют определенные названия и отображаются в Кошельке одинаково. Например, это может быть штрихкод, название мероприятия, номер рейса или баланс подарочной карты.

Вы можете разместить их в любом месте карты, указав fieldPath.

Пример. Показ штрихкода и сведений о карте

В этом примере у карты есть верхняя строка и три поля данных во второй строке. В первом элементе показываются значения пользователя из Object, например количество баллов или номер места. Второй элемент содержит сведения из Class, например название мероприятия или уровень в программе лояльности. Третий элемент содержит значения пользователя из Object, например дополнительную точку или номер сектора / вагона.

Определение класса:

...
"classTemplateInfo": {
      "cardTemplateOverride": {
        "cardRowTemplateInfos": [
          {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                    "fieldPath": "object.accountName",
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.secondaryLoyaltyPoints.label"
                    },
                    {
                      "fieldPath": "object.secondaryLoyaltyPoints.balance"
                    }
                  ]
                }
              }
            }
          },
          {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.loyaltyPoints.label"
                    },
                    {
                      "fieldPath": "object.loyaltyPoints.balance"
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "class.rewardsTierLabel"
                    },
                    {
                      "fieldPath": "class.rewardsTier"
                    }
                  ]
                }
              }
            }
          },
        ]
      }
    }
...
"rewardsTier": "Gold",
"rewardsTierLabel": "Tier",
...

Определение объекта

...
"accountName": "Camille Walsh",
"loyaltyPoints": {
    "balance": {
        "string": "1500"
    },
    "label": "Points"
},
"secondaryLoyaltyPoints" : {
    "balance": {
        "money": {
            "micros" : "35050000",
            "currencyCode": "USD",
        }
    },
    "label": "Balance"
}
...

Примечание. Значение fieldPath зависит от типа карты. Например, чтобы показать название события, используйте "fieldPath": "class.eventName.defaultValue.value". Полный список доступных полей приведен в справочной документации по Class и Object.

Форматирование полей даты и времени

Для любого поля даты или времени в поддерживаемых картах можно указать собственный формат с помощью свойства dateFormat. Это позволяет управлять тем, как дата отображается на карте, например показывать только время, полную дату и время или только дату. Если параметр dateFormat не указан, будет использоваться формат по умолчанию.

"fields": [
  {
    "fieldPath": "object.validTimeInterval.start.date",
    "dateFormat": "DATE_ONLY"
  }
]

Полный список доступных форматов приведен в документации по DateFormat.

2. Настройка с помощью полей, определенных разработчиком

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

Важно! Прежде чем создавать настраиваемое поле, ознакомьтесь со списком стандартных полей в справочной документации для вашего типа карты. Для вашего случая может уже существовать стандартное поле. Использование стандартных полей может значительно повысить удобство для пользователей, поскольку позволяет использовать интеллектуальные функции в сервисах Google, например умные уведомления, обновления на главном экране Pixel и возможность легко найти информацию в Поиске (если пользователи предоставили необходимые разрешения).

Вы определяете элемент textModulesData с уникальным id в Object или Class, а затем ссылаетесь на этот id в cardTemplateOverride.

Строки карточки структуры

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

• Совет. Дополнительную информацию можно разместить в нижней части карты или использовать другие функции Кошелька, например messages, linksModuleData или linkedOfferIds. Это позволяет не загромождать основной вид карты.

Пример. Строка из трех элементов со специальными данными

Создайте строку, чтобы показывать нужные сведения. Для карты постоянного клиента это могут быть баллы, уровень и баланс. Для билета на мероприятие это могут быть "Сектор", "Ряд" и "Место".

Определение класса Объект cardTemplateOverride ссылается на три уникальных идентификатора: detail1, detail2 и detail3.

...
"classTemplateInfo": {
      "cardTemplateOverride": {
        "cardRowTemplateInfos": [
        {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                    "fieldPath": "object.accountName",
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                     "fieldPath": "object.textModulesData['mem_since']",
                    }
                  ]
                }
              }
            }
          },
          {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.loyaltyPoints.label"
                    },
                    {
                      "fieldPath": "object.loyaltyPoints.balance"
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "class.rewardsTierLabel"
                    },
                    {
                      "fieldPath": "class.rewardsTier"
                    }
                  ]
                }
              }
            }
          },
          {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.secondaryLoyaltyPoints.label"
                    },
                    {
                      "fieldPath": "object.secondaryLoyaltyPoints.balance"
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.textModulesData['visits']",
                    }
                  ]
                }
              }
            }
          },
        ]
      }
    }
...
"rewardsTier": "Gold",
"rewardsTierLabel": "Tier",

Определение объекта Объект Object содержит данные и соответствующие идентификаторы для каждого поля.

...
"accountName": "Camille Walsh",
"loyaltyPoints": {
    "balance": {
        "string": "1500"
    },
    "label": "Points"
},
"secondaryLoyaltyPoints" : {
    "balance": {
        "money": {
            "micros" : "28250000",
            "currencyCode": "USD",
        }
    },
    "label": "Balance"
},
"textModulesData": [
{
    "header": "Visits",
    "body": "17",
    "id": "visits"
  },
  {
    "header": "Member since",
    "body": "Mar 01, 2024",
    "id": "mem_since"
  },
]
...

Данные о классах и объектах для вариантов

Вы можете объединить данные на уровне класса и объекта, чтобы создать динамические персонализированные карты. Это удобно, если вы хотите создать несколько версий одной карты.

• Уровень класса textModulesData. Используйте его для информации, которая одинакова для группы пользователей (например, сообщение "Добро пожаловать в VIP-зону" для всех владельцев VIP-билетов).
• На уровне объекта (textModulesData). Используйте этот вариант, чтобы указать информацию, относящуюся к одному пользователю (например, "Иван, у вашего места ограниченный обзор").

Пример. Показ карт в зависимости от уровня

Вы можете создать разные ресурсы Class для разных вариантов билетов, например "Общий вход" и "VIP" для мероприятия или "Эконом" и "Бизнес" для рейса. У каждого класса может быть уникальный дизайн (главное изображение, цвет) и текст по умолчанию.

Участник с серебряным уровнем	Участник перешел на Золотой уровень	Другой участник с Бриллиантовым уровнем

Контент в нижней части карты

Поля из linksModuleData, imageModulesData не отображаются, если на них есть ссылка в cardTemplateOverride. Этот контент автоматически показывается в нижней части карты, чтобы пользователям было проще найти ссылки на службу поддержки, рекламные изображения, условия использования и другую дополнительную информацию.

3. Другие переопределения шаблона

Объект classTemplateInfo предлагает больше, чем просто cardTemplateOverride. Вы можете настроить другие элементы Google Кошелька, чтобы сделать его более удобным и информативным.

Полный список доступных переопределений приведен в справочной документации по ClassTemplateInfo.

• listTemplateOverride – позволяет настроить макет строки в основном списке приложения "Google Кошелек", чтобы выделить наиболее важные поля до того, как пользователь откроет карту.
• detailsTemplateOverride – определяет структуру строк и макет нижней части карты, предоставляя гибкое пространство для дополнительной информации, ссылок и текста.
• cardBarcodeSectionDetails позволяет настроить раздел со штрихкодом на карте.