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 ingressos de eventos. Os conceitos abordados neste guia ajudam a entender melhor os recursos dos ingressos de eventos salvos.

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

Os seguintes casos de uso estão disponíveis apenas para a indústria de ingressos para eventos:

• Atualize os cartões
• Criar um botão para salvar vários cartões
• Ingressos de eventos para grupos
• Receber notificação de eventos futuros.
• Ofertas vinculadas
• 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 ingressos de um evento específico, como quando o endereço do local muda, você só precisa update [atualizar] ou aplicar o patch à EventTicketClass ou usar o Merchant Center do Google Pay. O Google propaga essas informações para todos os EventTicketObjects associados à EventTicketClass atualizada. Esse é o caso de todos os campos definidos no nível da EventTicketClass.

Para atualizar um único cartão, como quando o número do assento do titular do ingresso é alterado, você precisa update [atualizar] ou aplicar o patch a um único EventTicketObject. Este é o caso de todos os campos definidos no nível do EventTicketObject.

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

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 Salvar vários participantes com um botão.

Para mais informações sobre a representação da IU de cartões, consulte Ingressos de eventos para grupos.

Ingressos de eventos para grupos

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.

As condições em que EventTicketObject é considerado um grupo dependem da propriedade class.eventID ter sido definida ou não.

Grupo com class.eventId

A propriedade class.eventId pode agrupar ingressos, independentemente de outras propriedades. Por exemplo, se dois objetos EventTicketObject tiverem class.eventId = "foo", mesmo que tenham class.eventName e class.dateTime.start diferentes, os dois objetos serão considerados como parte de um grupo.

Quando class.eventID é usado, os objetos só exigem que as propriedades a seguir sejam consistentes para serem considerados como um grupo.

• Código do emissor (da API Google Pay for Passes Merchant Center)
• class.eventId

Grupo sem class.eventId

Se class.eventId não estiver definido para objetos EventTicketObject, eles serão considerados um grupo apenas se todas as propriedades listadas abaixo forem as mesmas:

• Código do emissor (da API Google Pay for Passes Merchant Center)
• class.eventName
• class.dateTime.start

Receber notificações de eventos futuros

O Google Pay envia uma notificação ao usuário três horas antes do evento. O horário do evento é definido por class.dateTime.start.

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:

class.eventName
Expand for more options

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

Se ele tiver vários cartões, somente aquele que for usado mais rapidamente será mostrado. Se ele tiver salvo cartões agrupados de acordo com a seção Ingressos de evento para grupos, a notificação mostrará apenas um dos cartões no 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.dateTime.end. Se nenhum horário for fornecido em class.dateTime.end, class.dateTime.start será usado.

Ofertas vinculadas

Ele permite que ofertas atuais apareçam na visualização de ingressos de eventos, o que facilita a descoberta de conteúdo relevante. O campo de lista gravável linkedOfferIds em um EventTicketObject indica quais ofertas estão associadas ao ingresso de evento.

Como criar a oferta antes de vincular

Para vincular uma oferta vinculada, os objetos e as classes da oferta vinculados ao ingresso de evento precisam ter sido criados. Para saber mais sobre como criar ofertas, consulte Ofertas. Ao contrário das ofertas independentes, as ofertas vinculadas não exigem que o usuário salve explicitamente a oferta. O campo id encontrado no OfferObject é usado a fim de apontar para EventTicketObject.

Vincular ofertas a um ingresso de evento

As ofertas existentes podem ser vinculadas a um ingresso de evento usando as seguintes chamadas da API REST: insert, update, patch ou modifyLinkedOfferObjects.

Quando ofertas são vinculadas por meio da chamada insert a um ingresso de evento na criação dele, ou quando ofertas são vinculadas e desvinculadas de um ingresso de evento atual usando a chamada update, nesses casos, o campo linkedOfferIds poderá ser escrito no formato estabelecido com o restante do EventTicketObject:

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

Quando as ofertas são vinculadas e desvinculadas de um ingresso de evento atual por meio da chamada patch, o campo linkedOfferIds poderá ser o único campo na solicitação:

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

No entanto, para evitar erros ao lidar com matrizes, especifique quais ofertas vinculadas precisam ser adicionadas e quais precisam ser removidas, e, para poder omitir as ofertas vinculadas que precisam permanecer intocadas, recomendamos usar o método modifyLinkedOfferObjects como no exemplo a seguir:

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

Como criar ingressos de eventos com ofertas vinculadas

As ofertas vinculadas serão exibidas em uma visualização do ingresso de evento entre a seção do cartão e a seção de detalhes, conforme mostrado abaixo. Somente um máximo de cinco ofertas vinculadas é exibido no carrossel. Se mais ofertas forem vinculadas ao ingresso de evento, o usuário poderá clicar no botão “Mais” no final do carrossel para exibir todas elas.

Ao receber um clique, a oferta vinculada usa um design simplificado, conforme mostrado abaixo.

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 72 horas desde que class.dateTime.end expirou. Se class.dateTime.end não for especificado, class.dateTime.start será usado. O cartão é transferido para "Cartões expirados" a qualquer momento entre 72 e 96 horas após class.dateTime.end ou class.dateTime.start 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
              }
            }
    }
  }
  …
  …
  …
}