Design

Transit passes support template rendering. If no template is defined, the default one will be used.

Template

A pass template is defined at the class level and it is used to display any object that's associated with the class. The template defines which fields to display in different sections of the pass.

The template is divided into the following sections:

Card title

The card title section displays the logo and name of the transit operator and the journey summary in the top row. All of these three elements are required and neither the field references used to populate them nor their position can be changed.

However, the rendering logic allows for some flexibility for the top row. The top row of the pass, which represents a journey summary, is controlled by the following fields in the TransitObject for a single-leg journey:

  • object.tripType
  • object.ticketLeg.originName
  • object.ticketLeg.destinationName
  • object.ticketLeg.originStationCode
  • object.ticketLeg.destinationStationCode

How the pass is rendered depends on which fields are non-empty. It can be rendered in the following ways:

  • Origin name only: The origin name is the only information displayed. This is particularly useful for tickets that cover an area instead of a specific journey.
  • Origin and destination: The origin is on the left-hand side and the destination is on the right-hand side. The symbol in between the two depends on the type of the trip. Origin and destination are shown as one of the following:
    • Names and station codes: We show the station codes with the names as smaller text on top.
    • Names only: We show the names.
    • Station codes only: We show the station codes.

Multi-leg TransitObject objects work very similarly. In this case, do not use object.ticketLeg. Instead, you have to use the object.ticketLegs[] list. Both origins and destinations must be defined. Names or station codes, or both must be used consistently in each leg. The origin displayed is the origin of the first element in the array, while the destination displayed is the destination of the last element in the array.

The background color of the pass isn't a required field and can be defined at both the class level and the object level. The object field has higher priority and can be used to override the class field.

Card template

The card template section is used to display extra rows to the journey summary in the top row. These rows can contain text-based structured data fields or text module fields.

You can specify the number of rows that define the number of objects in the class.classTemplateInfo.cardTemplateOverride.cardRowTemplateInfos[] list. The list requires at least one element and accepts at most two elements. Each element must be of one of the following types:

  • oneItem, which accepts one item:
    • item
  • twoItems, which accepts two items:
    • startItem
    • endItem
  • threeItems, which accepts three items:
    • startItem
    • midItem
    • endItem

Each item can be defined as either a single field selector (.firstValue), two field selectors (.firstValue and .secondValue), or a predefined item (.predefinedItem). Both the selected field’s values and their respective labels are displayed. When you define two field selectors, the values of the selected fields are displayed with a "/" separator. The same goes for the labels of the selected fields. Predefined items are used to define more complex rendering.

If an item is empty, it isn't displayed. For more details, see Field References. If all items in a row are empty, the row isn't displayed. If some but not all items in a row are empty, the non-empty items are re-arranged and displayed as a row with fewer items.

If you don't override the card template, the default number of rows, the default number of items, and the default field references are used. For more details, see Default template.

If a Hero Image is defined, it will appear after the first row if multiple rows are included the cardRowTemplateInfos list. If there is only one row, the hero image appears above the row.

Card barcode

The card barcode section is used to display extra text or images above and below the barcode. None of the fields in this section are required.

The barcode is defined by a type and a value. For a list of supported barcode types, see Reference. Furthermore, a text can be shown right underneath the barcode. This text is meant to facilitate the barcode scanning but can be repurposed for other uses.

There are then three field selectors that can be used to define two side-by-side fields above and one below the barcode. These are displayed with no label and can either be text-based structured data fields, text module fields, or image module fields. If you use images, these should follow the Brand Guidelines.

If you don't override the card barcode section, you are only able to use the barcode and the barcode alternate text. For more information, see Default template.

Details template

The details template section is a list of items class.classTemplateInfo.detailsTemplateOverride.detailsItemInfos[]. The items can contain any kind of structured data fields, text module fields, link module fields, image module fields, or messages.

Each item can be defined as either a single field selector (.firstValue), two field selectors (.firstValue and .secondValue), or a predefined item (.predefinedItem). Both the selected field’s values and their respective labels are displayed. When you define two field selectors, the values of the selected fields are displayed with a "/" separator. The same goes for the labels of the selected fields. Predefined items are used to define more complex rendering. Image module fields are rendered at full-width without a label.

If an item is empty, it isn't displayed. For more details, see Field References.

If you don't override the details template, the default list of reference fields in the default order is displayed. For more information, see Default template.

If the journey includes multiple legs, a simple itinerary is displayed at the top of the section and can't be moved. If the journey only includes a single leg, a simple itinerary can be shown by setting class.enableSingleLegItinerary.

List template

The list template section is used to select what field to display in the "Passes" view of the Google Pay app. The pass is represented in the list with the logo, background color, and three rows.

The first row shows the journey summary. The format of the summary can be one of the following:

  • originAndDestinationCodes
  • originAndDestinationNames
  • originName

The second and third row can be defined with a field selector. The fields are displayed with no label. For grouped passes, the second row always shows the departure date and the third row always shows the number of grouped passes.

Labels

All structured data fields have a label provided by Google. Google is responsible for providing a translation for each of these labels in all the supported languages.

You can customize some of these labels using one of the class.custom<name_of_the_field>Label fields. When you customize a label, you become responsible for providing translations for that specific label in all the languages that you wish to support.

Field references

Field references are used in different parts of the template with the form class.classTemplateInfo.*.fields[]. A field reference contains a list of paths to structured data fields, text module fields, link module fields, image module fields, or messages.

Not all types of paths are allowed in every field reference. For example, some field references only allow paths to text-based structured data fields or text module fields. Text-based structured fields are structured data fields of type string, localized string, date, or money.

The list can be used to implement a fallback logic. This means that if the first path in the list resolves to an empty field, the next path is evaluated. The fallback logic is mainly targeted at text-based structured data fields or text module fields. Do not mix different types of fields in the same list. Use the fallback logic with caution and only in specific situations when you expect a consistent pattern of fields that exist in some objects but not others. Most of the time, it's easier to create separate classes for separate use cases.

If all paths in a field reference list resolve to empty fields, the item that uses the field reference isn't displayed. If you want the item that uses the field reference to always be present, make sure that at least one path isn't empty. We recommend that you set a field to a special character, such as ‘-’, to represent a null value, even if some fields allow strings with just a space.

In order to reference a field contained in a list, you need to use reference IDs. All items of a list that can be referenced have a .id field. Use the same ID as a list index in the field reference string, like in the following example:

  • object.imageModulesData[0].id = my-id
  • class.detailsTemplateOverride.detailsItemInfos[0].item.firstValue.fields[0].fieldPath = object.imageModulesData[‘my-id’]

In this case, the first item in the details section of the pass is the first image declared in the object.

Default template

For image module fields, we show one and only one image module field from the class and one and only one image module field from the object. If you need more than one image module field at either level, override the default template.

For text module fields, we only show a maximum of 10 text module fields from the class and 10 text module fields from the object. The fields are displayed in the same order in which they are defined in the array. If you need more than 10 text module fields at either level, override the default template.

For messages, we only show a maximum of 10 messages from the class and 10 messages from the the object. The order of the messages is not guaranteed. If you need more than 10 messages at either level or if you need a guaranteed ordering, override the default template.

For the links module field, there is no limit on the number of uris you can define. Uris are diplayed grouped in the following order for each level (class or object):

  1. map coordinates,
  2. telephone numbers,
  3. email addresses,
  4. web pages.
For each group, uris are displayed in the same order in which they are defined in the array. If you need a different ordering, override the default template.

Envoyer des commentaires concernant…

Google Pay for Passes