Casos de uso

Neste guia, descrevemos maneiras específicas de usar a API Google Pay for Passes para interagir com seus clientes na vertical de cartões de transporte. Com a API, você pode oferecer as seguintes opções aos seus clientes:

Atualizar cartões de transporte

Se um cartão de transporte for alterado depois de salvo, você poderá usar a API REST update ou patch para informar essas alterações aos passageiros.

Para atualizar a maneira como os cartões de transporte são exibidos, você só precisa usar update ou patch para TransitClass. As mudanças em uma TransitClass são propagadas para todos os objetos associados a essa classe. Essa é uma maneira rápida e fácil de atualizar a aparência de muitos cartões de transporte com algumas chamadas.

Para atualizar um único cartão de transporte, como alterar o horário de partida estimado, use update ou patch em um único TransitObject. Isso se aplica a todos os campos definidos no nível do TransitObject, mesmo se o valor do campo for compartilhado entre um subconjunto de objetos TransitObject. É possível encontrar todos os objetos de uma determinada classe chamando o método TransitObject list (link em inglês).

Se você não souber quando ocorre uma alteração ou quando acionar uma chamada API REST patch, agende periodicamente as chamadas API REST update ou patch para cada TransitObject.

Definir viagens com vários trechos

É comum que uma viagem inclua vários trechos em vez de ser direta até o destino. Para lidar com uma viagem desse tipo, os operadores de transporte podem emitir um cartão de transporte para cada etapa da viagem ou um cartão único. A API Google Pay for Passes imita esse comportamento, com um TransitObject por trecho ou um único TransitObject com vários trechos.

É muito simples usar um TransitObject por trecho. Você pode usar object.ticketLeg para definir o trecho e criar e atualizar cada cartão de transporte como se fossem independentes. No entanto, talvez seja melhor definir uma maneira de agrupar esses cartões. Para mais detalhes, consulte Agrupar vários cartões de transporte. Essa é a maneira mais recomendável de criar viagens com vários trechos.

Os objetos TransitObject de vários trechos devem ser usados apenas se esse tipo de cartão agregado for aceito em cada trecho e as informações no cartão (por exemplo, o código QR) forem iguais para todos eles. É possível defini-los usando a lista object.ticketLegs[]. O cartão mostra apenas a origem do primeiro trecho e o destino do último, enquanto um itinerário completo é exibido na seção de detalhes do cartão.

Exibir um botão para salvar vários cartões

Se um usuário compra vários cartões e vai, potencialmente, salvar todos no Google Pay, é útil oferecer a opção de salvar vários objetos de uma só vez com um clique no botão ou link Salvar no Google Pay. Vários objetos ou classes podem ser definidos no JSON Web Token (JWT).

O JWT precisa ter um dos seguintes formatos:

  • Usando apenas classes e objetos pré-inseridos.
  • São usados somente recursos de objeto e classe totalmente definidos dentro do JWT.

Para mais informações sobre a representação da interface do usuário de cartões, consulte Agrupar vários cartões de transporte público.

Agrupar vários cartões de transporte público

Alguns recursos funcionam de maneira diferente se usados em um grupo em vez de objetos individuais, como notificações de status ou organização de vários cartões salvos para muitos passageiros na interface do usuário.

Os objetos TransitObject só serão considerados um grupo se compartilharem as mesmas object.classId, object.ticketLeg.departureDateTime e uma das propriedades a seguir, listadas por ordem de prioridade:

  1. object.tripId
  2. object.purchaseDetails.confirmationCode

O própósito disso é agrupar cartões que sejam para a mesma viagem, mas passageiros diferentes.

Se você quiser que os cartões sejam agrupados, recomendamos defini-los de maneira consistente, mesmo que um determinado TransitObject não esteja agrupado com outro.

Gerenciar cartões expirados

A seção Cartões expirados contém todos os cartões arquivados ou inativos na guia Cartões do app do Google Pay. Um cartão de transporte público será movido para a seção "Cartões expirados" se pelo menos uma das seguintes condições for verdadeira:

  • Passaram-se 24 horas desde o object.ticketLeg.arrivalDateTime ou a última object.ticketLegs[].arrivalDateTime ou object.validTimeInterval.end.date.
  • Se object.state tiver o status expired, inactive ou completed.

Receber as próximas notificações

O Google Pay envia uma notificação ao usuário três horas antes do horário de partida. Ela tem um formato não modificável.

Para receber essa notificação de status sobre a próxima viagem, um usuário precisa acessar Configurações > Notificações e ativar Atualizações sobre seus cartões.

Se o usuário tiver vários cartões agrupados, somente uma notificação será mostrada, e ela não será dispensada automaticamente depois de aberta. Isso ocorrerá 60 minutos depois do horário de partida programado.

Depois que o usuário salvar um cartão, faça referência ao atributo objectId dele para definir um direcionamento para o cartão.

Use o link a seguir para fazer referência ao cartão:

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

O cartão pode ser exibido no app Google Pay ou em um navegador da Web.