Visão geral

Com a API Google Pay Passes, os parceiros podem especificar um endpoint parar ativar um cartão de transporte público. Quando a ativação é necessária, o botão "Ativar" aparece para o usuário. Quando a pessoa toca nele, o endpoint especificado é chamado com os parâmetros descritos abaixo. O endpoint precisa garantir que o cartão tenha informações de resgate válidas (código de barras ou inspeção visual) antes de retornar. O cartão na Carteira do usuário vai ser atualizado para mostrar as informações de resgate. Antes da ativação, as informações de resgate não aparecem

API Activation

O endpoint de ativação é especificado na API usando activationOptions na classe de transporte público. O parceiro é responsável por manter um endpoint de ativação funcional com latência razoável.

  activationOptions: {
    activationUrl: string
  }
Campo Descrição
activationUrl

string

URL do endpoint do parceiro que seria chamado para solicitações de ativação. O URL precisa estar hospedado em HTTPS, e o robots.txt tem que permitir que o caminho do URL seja acessível por UserAgent:Google-Valuables.

O estado de ativação é armazenado no objeto usando o campo activationStatus. Os status válidos incluem NOT_ACTIVATED e ACTIVATED. O endpoint de ativação precisa atualizar o objeto com o status ACTIVATED, além de garantir que o objeto tenha informações de resgate válidas, como um código de barras ou parâmetros de inspeção visual. O campo deviceContext pode ser usado para fixar dispositivos.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Campo Descrição
activationStatus

enum (ActivationStatus)

Status de ativação para este objeto de transporte público. Esse status muda a representação do cartão e permite que os usuários realizem ações. Por exemplo: um botão "Ativar" vai ser renderizado nos detalhes do cartão se ele estiver definido como NOT_ACTIVATED.

Estes são os valores aceitáveis:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

Um contexto de dispositivo para associar ao objeto. Se este campo for definido, as informações de resgate vão ser retornadas apenas para o dispositivo especificado.
hasLinkedDevice

boolean

Se este objeto está atualmente vinculado a um único dispositivo.
DeviceContext
Campo Descrição
deviceToken

string

Se este campo for definido, as informações de resgate só vão ser retornadas para o dispositivo especificado depois da ativação do objeto. Ele não pode ser usado como um identificador estável para rastrear o dispositivo de um usuário. Ele pode mudar em diferentes cartões para o mesmo dispositivo ou até mesmo em diferentes ativações para o mesmo dispositivo. Ao definir este campo, os autores das chamadas também precisam definir hasLinkedDevice no objeto que está sendo ativado.

O deviceToken é recebido do campo deviceContext de parâmetros de ativação.

Fixação no dispositivo

Com esse recurso, o usuário pode ativar o cartão e ver as informações de resgate apenas em um dispositivo. Como isso é separado de multipleDevicesAndHoldersAllowedStatus de ONE_USER_ONE_DEVICE, o cartão só aparece em um dispositivo. É recomendável usar o status ONE_USER_ALL_DEVICES com a fixação no dispositivo.

Antes da ativação, o usuário pode ver o cartão e o botão "Ativar" em todos os dispositivos dele. As informações de resgate parecem no dispositivo em que o cartão foi ativado e fixado. O botão "Ativar" aparece nos outros dispositivos para que o usuário possa mover o cartão. Se um usuário não quiser mover o cartão, mas a ativação em qualquer dispositivo for útil, ele poderá atualizar o cartão durante a ativação para ONE_USER_ONE_DEVICE em vez de usar a fixação no dispositivo.

Para implementar a fixação no dispositivo, o objeto precisa ser atualizado com o campo deviceToken, que é recebido com os parâmetros de ativação. Também é preciso definir hasLinkedDevice como verdadeiro na mesma chamada de API. É possível desvincular o cartão de um dispositivo definindo hasLinkedDevice como falso em uma chamada de API futura.

diagrama da sequência para fixação no dispositivo

Parâmetros de ativação

A solicitação para o endpoint de ativação vai conter os parâmetros a seguir.

Exemplo de JSON: 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

Identifier Descrição
classId

ID de classe totalmente qualificado. Usa o seguinte formato:

<issuer_id.class_id>
objectIds

Matriz totalmente qualificada de IDs de objetos com o seguinte formato:

<issuer_id.object_id>
expTimeMillis Tempo de expiração em milissegundos desde época. Depois do tempo de expiração, a mensagem precisa ser considerada inválida.
eventType Always "activate".
nonce Valor de uso único para rastrear as entregas duplicadas.
deviceContext

Um ID exclusivo gerado pelo Google que representa o dispositivo em que o usuário está realizando ações. Esse ID é usado ao fazer atualizações que vinculam um objeto a um dispositivo.

Ele talvez não seja constante nas solicitações futuras de um determinado dispositivo.