Casos de uso

Selecione uma das seguintes indústrias de cartão para saber mais sobre como ele pode ser usado.

Com a API Google Pay for Passes, você pode interagir com usuários por meio de cartões de transporte para ônibus, balsas, trens e muito mais. Os conceitos abordados neste guia ajudam a entender melhor os recursos dos cartões de transporte.

Para implementar passagens de transporte público, use o método de solicitação JWT POST ou links JWT "skinny", que são métodos que inserem as classes e os objetos previamente.

TransitClasses e TransitObjects

Assim como outras indústrias na API Google Pay for Pass, os dados para passagens de transporte público são armazenados em duas estruturas de dados: TransitClass e TransitObject. Neste guia, explicamos como essas estruturas de dados são usadas para aceitar os cartões de transporte público.

TransitClass

TransitClass define o modelo usado para exibir qualquer objeto que esteja associado à classe. O modelo define quais campos serão exibidos em diferentes seções do cartão Além disso, indica o logotipo e o nome do emissor, que são compartilhados entre os objetos.

Se dois tipos de cartão exigirem que dados diferentes sejam exibidos em uma ou mais seções, talvez seja útil criar dois TransitClasses separados. Por exemplo, um TransitClass para usar em qualquer cartão de uso único de ponto a ponto e outro TransitClass para usar em passaportes para a temporada.

TransitObject

Um TransitObject contém todos os dados que representam a viagem, a transportadora e os passageiros. Por exemplo, TransitObject contém a origem e o destino da viagem, o horário de partida, o número da transportadora, o nome do passageiro, o número do assento e muito mais. Alguns desses valores são compartilhados entre vários TransitObjects.

Os recursos contidos em um TransitObject são salvos no aplicativo Google Pay do usuário.

Países compatíveis

Para saber quais países aceitam o app Google Pay, consulte a lista de países compatíveis. Recomendamos limitar a exibição do botão Salvar no Google Pay de acordo com o local em que o usuário compra o bilhete.

Casos de uso

Os seguintes casos de uso estão disponíveis apenas para a indústria de cartões de transporte público:

Atualizar cartões

Se houver alterações em um cartão após a criação dele, use a REST API para informar essas alterações aos usuários. Se as mudanças afetarem somente as classes, você também poderá usar o Merchant Center do Google Pay. As atualizações de cartão são uma maneira importante de interagir com seus usuários.

Para atualizar a maneira como os cartões são exibidos, como quando o logotipo muda, você só precisa aplicar update ou patch ao TransitClass ou usar o Merchant Center do Google Pay. O Google propaga essas informações para todos os TransitObjects associados à TransitClass atualizada. Esse é o caso de todos os campos definidos no nível da TransitClass.

Para atualizar um único cartão, por exemplo, caso haja uma mudança na hora de partida, é necessário update ou patch um único TransitObject. Esse é o caso de todos os campos definidos no nível do TransitObject.

Às vezes, você pode não saber quando uma alteração ocorre ou quando acionar uma solicitação update ou patch. Em casos como esse, programe periodicamente solicitações update ou patch para cada classe e objeto. Para encontrar todas as classes de uma determinada conta emissora, chame o método TransitClass list. É possível encontrar todos os objetos de uma classe específica ao chamar o método TransitObject list.

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 para vários trechos.

É muito simples usar um TransitObject por trecho. É possível usar object.ticketLeg para definir o trecho. É possível 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 público. Essa é a maneira mais recomendável de criar viagens com vários trechos.

Objetos TransitObject referentes a vários trechos devem ser usados somente se esse tipo de cartão agregado for aceito em cada trecho e somente se as informações no cartão, por exemplo, o código QR, forem as mesmas para todos os trechos. É possível usar a lista object.ticketLegs[] para definir os trechos. 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.

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

Para usuários que compram vários cartões e querem salvar todos eles no Google Pay, é útil que eles possam salvar muitos objetos com um clique do botão ou link Salvar no Google Pay. Você pode definir vários objetos ou classes ao assinar o JSON Web Token (JWT).

É preciso criar o JWT em um dos seguintes formatos:

  • Com apenas classes e objetos pré-inseridos.
  • Com apenas recursos de classe e de objeto que são totalmente definidos no 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

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

Os objetos TransitObject são considerados como um grupo se compartilharem o mesmo object.classId, object.ticketLeg.departureDateTime e uma das propriedades a seguir, listadas por prioridade:

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

O propósito disso é agrupar cartões que sejam para a mesma viagem, mas com 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.

Receber notificações de viagens futuras

O Google Pay envia uma notificação ao usuário uma hora antes da viagem. O horário da viagem é definido por object.ticketLeg.departureDateTime ou pelo primeiro object.ticketLegs[].departureDateTime.

Para receber essa mensagem, o usuário precisa ter as notificações ativadas. Ele pode verificar isso ao navegar até Configurações > Notificações para ver se a opção Atualizações sobre seus cartões está ativada.

A mensagem será exibida na área de notificações e também na tela de bloqueio se o usuário tiver ativado notificações nessa tela.

A notificação tem o seguinte formato não modificável: 

Ticket fot your upcoming trip to object.ticketLeg.destinationName
Expand for more options

Se o usuário tocar na notificação e desbloquear o dispositivo, o cartão será exibido no app Google Pay.

Se houver vários cartões, somente aquele que for usado mais rapidamente será mostrado. Se os cartões agrupados tiverem sido salvos de acordo com as instruções em Agrupar várias passagens de transporte público, a notificação mostrará apenas uma das passagens do grupo. No entanto, depois de tocar na notificação, o usuário pode ver os outros cartões nesse grupo ao deslizar para a esquerda ou direita.

A notificação é fixada e não será dispensada automaticamente depois que o usuário a abrir. Ela será dispensada automaticamente 60 minutos após object.ticketLeg.departureDateTime ou o primeiro object.ticketLegs[].departureDateTime.

Gerenciar cartões expirados

Na guia "Cartões" do app Google Pay, há uma seção "Cartões expirados" que contém todos os cartões arquivados ou inativos. Um cartão é movido para essa seção se pelo menos uma das seguintes condições for verdadeira:

  • Já passaram pelo menos 24 horas desde object.ticketLeg.arrivalDateTime ou do último object.ticketLegs[].arrivalDateTime expirado. O cartão é transferido para "Cartões expirados" entre 24 e 48 horas após object.ticketLeg.arrivalDateTime ou o último object.ticketLegs[].arrivalDateTime expirar.
  • object.validTimeInterval.end.date expirou. O cartão é transferido para "Cartões expirados" até 24 horas após object.validTimeInterval.end.date expirar.
  • O campo object.state está marcado como Expired, Inactive ou Completed.

Depois que um usuário salvar um cartão, referencie o objectId para vincular ao cartão.

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

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

É possível exibir o cartão no app Google Pay ou em um navegador da Web.

É possível vincular-se ao seu app ou site abaixo do cabeçalho de um cartão salvo do Google Pay. Este recurso está disponível para todos os tipos de cartões do Google Pay.

Solicitar acesso

Solicite acesso com o formulário de suporte para comerciantes em loja. Lembre-se do seguinte:

  • Você precisa informar seu código de emissor no formulário.
  • Em Issue type, selecione "Technical/API Integration".
  • Selecione Link your app or website below the Google Pay pass.

Para um determinado cartão do Google Pay, configure appLinkData para definir o URI do seu aplicativo ou site. O URI pode ter qualquer formato, mas recomendamos o uso de um link dinâmico.

Veja o formato e o contexto do campo appLinkData no seguinte código-fonte:

{
  "id": string,
  "classId": string,
  …
  …
  …
  "appLinkData": {
    "androidAppLinkInfo": {
      "appLogoImage": {
        "sourceUri": {
          "uri": string
        }
      },
        "title": {
          "defaultValue": {
            "language": string,
              "value": string
          }
        },
          "description": {
            "defaultValue": {
              "language": string,
                "value": string
            }
          },
            "appTarget": {
              "targetUri": {
                "uri": string,
                  "description": string
              }
            }
    }
  }
  …
  …
  …
}