Casos de uso

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

A API Google Pay for Passes permite se engajar com usuários por meio de cartões de embarque para voos. Os conceitos abordados neste guia ajudam a entender melhor os recursos dos cartões de embarque salvos.

Para implementar cartões de embarque, use o método de solicitação JWT POST ou os links JWT "skinny", que inserem classes e objetos previamente.

FlightClasses e FlightObjects

Assim como outras indústrias na API Google Pay for Passes, os dados para passagens de transporte público são armazenados em duas estruturas de dados: FlightObject e FlightClass. Neste guia, explicaremos como essas estruturas podem ser usadas com cartões de embarque.

FlightClass

A FlightClass mantém dados que todos os passageiros ou um subconjunto de passageiros têm em comum para um voo específico em uma data e hora determinadas. Por exemplo, esses dados comuns podem ser a operadora, a origem, o destino, o número do voo e a hora de partida. Todos os passageiros no voo teriam os mesmos dados nos cartões de embarque.

Uma FlightClass também pode manter dados comuns para um subconjunto de passageiros no mesmo avião. Por exemplo, crie três estruturas FlightClass diferentes para primeira classe, classe executiva e classe econômica. Isso permitiria usar campos diferentes para cada subconjunto, se isso fosse necessário. Nesse caso, todas as três classes ainda representariam o mesmo avião, voando na mesma rota, em uma data e hora específicas.

FlightObject

Um FlightObject representa cada passageiro que voa em um determinado avião em um momento específico. Por exemplo, o FlightObject contém o nome do passageiro, o número do assento e o código de barras do embarque. Eles são diferentes no cartão de embarque de cada passageiro.

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

Países compatíveis

Para saber quais países aceitam cartões de embarque para voos, consulte a lista de países compatíveis. É recomendável limitar a exibição do botão Salvar no Google Pay com base no local em que o usuário está comprando o cartão de embarque.

Casos de uso

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

Atualizar cartões
Salvar uma jornada de voo com vários trechos
Criar um botão para salvar vários cartões
Agrupar vários cartões de embarque.
Receber notificações sobre próximos voos
Receber notificações de atualização de voos
Gerenciar cartões expirados
Direcionar para um cartão salvo.
Incluir link em um cartão salvo.

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 os campos de todos os cartões de embarque de um voo específico, por exemplo, quando o horário de partida estimado mudar, você só precisa aplicar update ou patch ao FlightClass ou usar o Google Pay Merchant Center. O Google propaga essas informações para todos os FlightObjects associados à FlightClass atualizada. Esse é o caso de todos os campos definidos no nível da FlightClass.

Para atualizar um único cartão, como quando o número do assento do passageiro é alterado, você precisa aplicar update ou patch a um único FlightObject. Esse é o caso de todos os campos definidos no nível da FlightObject.

Observação: Consulte FlightClass e FlightObject para mais informações sobre essas estruturas de dados.

À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 FlightClass list. É possível encontrar todos os objetos de uma classe específica ao chamar o método FlightObject list.

Fontes de dados para atualizações de voo

Se a hora fornecida por class.localScheduledDepartureDateTime estiver entre as últimas 24 horas ou as próximas 48 horas, um cartão de status de voo será exibido para os usuários. Quando isso acontece, o Google Pay pode exibir dados do Google Voos ou das informações fornecidas no cartão do Google Pay. A fonte a ser usada depende do seguinte:

Se class.localEstimatedOrActualDepartureDateTime não for fornecido, o Google Voos será usado. Nesse caso, qualquer class.flightStatus definido será ignorado.

Por exemplo, se um voo estiver atrasado, os usuários verão um cartão na guia "Página inicial" do aplicativo do Google Pay que exibirá o novo horário de partida. Um cartão de atraso semelhante também será exibido para os usuários na guia "Cartões".
Se você tiver fornecido o class.localEstimatedOrActualDepartureDateTime, mas não o class.flightStatus, a hora fornecida será usada para determinar se um voo está atrasado. O status do voo no cartão é exibido aos usuários com base na seguinte lógica:
- Se class.localEstimatedOrActualDepartureDateTime for maior que class.localScheduledDepartureDateTime, os usuários veem um cartão com o voo listado como atrasado.
- Se class.localEstimatedOrActualDepartureDateTime não for maior que class.localScheduledDepartureDateTime, os usuários veem o cartão com as informações de voo, mas sem nenhuma mensagem de status.

Se você não quiser usar o Google Voos como fonte de informações sobre voos, forneça flightStatus, localScheduledDepartureDateTime e localEstimatedOrActualDepartureDateTime da FlightClass. Somente seus dados serão usados no cartão. Como alternativa, se você usar um código de transportadora ICAO em vez de um código IATA na FlightClass, o Google Voos não será usado como fonte de informações de voo.

Quando determinados campos são alterados, o usuário recebe notificações push sobre as alterações. Para mais detalhes, consulte Receber notificações de atualização de voo.

Salvar uma jornada de voo com vários trechos

É comum que uma jornada de voo inclua vários trechos, em vez de ser uma viagem direta para o destino de uma pessoa. Durante essa jornada, as companhias aéreas emitem um cartão de embarque por trecho da viagem. A API Google Pay for Passes imita esse funcionamento, com um FlightObject por trecho.

Isso significa que, se houver dois passageiros voando de SFO para LAX e, depois, para TPE, haverá duas estruturas FlightClass e quatro objetos FlightObject:

	`FlightClass` A (SFO para LAX: companhia aérea, número do voo, hora de partida)	`FlightClass` B (LAX para TPE: companhia aérea, número do voo, hora de partida)
Passageiro Q	`FlightObject: id_01`	`FlightObject: id_02`
Passageiro Z	`FlightObject: id_03`	`FlightObject: id_04`

Esses campos refletem os cartões de embarque físicos. Os passageiros Q e Z teriam dois cartões de embarque impressos.

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 ver um exemplo de como criar um botão para vários cartões, consulte Botão para salvar vários passageiros.

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

Agrupar vários cartões de embarque

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 FlightObject só serão considerados um grupo se todas as propriedades a seguir forem as mesmas em cada objeto:

Código do emissor (da API Google Pay for Passes Merchant Center)
class.flightHeader.carrier.carrierIataCode
class.flightHeader.flightNumber
class.localScheduledDepartureDateTime
object.reservationInfo.confirmationCode

Se dois objetos FlightObject forem diferentes em qualquer uma das propriedades acima, eles não serão considerados como agrupados.

Observação: algumas são propriedades de classe e outras são propriedades de objeto. Isso permite agrupar objetos FlightObject de classes diferentes.

Receber notificações sobre próximos voos

O Google Pay envia uma notificação ao usuário três horas antes do voo. O tempo de voo é definido por class.localScheduledDepartureDateTime.

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:

Boarding pass for your flight to class.destination.airportIataCode
Expand for more options

Se ele 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ários cartões de embarque, a notificação mostrará apenas um dos cartões 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 um usuário a abrir. Isso ocorrerá 60 minutos após class.localScheduledDepartureDateTime.

Receber notificações de atualização de voos

Quando determinados campos de um voo são alterados, os usuários com um ou mais cartões de embarque salvos recebem uma notificação push no dispositivo. Isso acontece somente se condições específicas forem atendidas.

Terminal de origem e portão

Se você alterar class.origin.terminal ou class.origin.gate e a condição a seguir for atendida, uma notificação será enviada informando que o campo foi alterado.

Faltam menos de três horas para class.localScheduledDepartureDateTime.

A notificação é exibida no seguinte formato: “A companhia aérea X atualizou o seu portão para A1.” O formato não pode ser alterado.

Horário de embarque e de partida

Se você alterar class.localBoardingDateTime ou class.localEstimatedOrActualDepartureDateTime, e as condições abaixo forem atendidas, uma notificação será enviada informando que o campo foi alterado.

Faltam menos de 24 horas para class.localScheduledDepartureDateTime.
O horário em questão é alterado em pelo menos 10 minutos.

A notificação é exibida no seguinte formato: "A companhia aérea X atualizou o horário de embarque para 18:00." Não é possível alterar o formato.

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á se passaram pelo menos 24 horas desde que class.localScheduledDepartureDateTime ou class.localEstimatedOrActualDepartureDateTime expirou. O cartão é transferido para "Cartões expirados" a qualquer momento entre 24 e 48 horas depois de class.localScheduledDepartureDateTime ou class.localEstimatedOrActualDepartureDateTime 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.

Direcionar para um cartão salvo

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.

Incluir link em um cartão salvo do Google Pay

É 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.

Definir o link do app no seu cartão do Google Pay

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
              }
            }
    }
  }
  …
  …
  …
}