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 fidelidade. Os conceitos abordados neste guia ajudam a entender melhor os recursos dos cartões de fidelidade salvos.

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

• Atualizar cartões
• Ler no app Google Pay
• Ofertas vinculadas
• Notificações acionadas por fronteira geográfica virtual
• Gerenciar cartões expirados
• Direcionar para um cartão salvo.
• Incluir link em um cartão salvo.
• Inscrição e login.

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 LoyaltyClass ou usar o Merchant Center do Google Pay. O Google propaga essas informações para todos os LoyaltyObjects associados à LoyaltyClass atualizada. Esse é o caso de todos os campos definidos no nível da LoyaltyClass.

Para atualizar um único cartão, por exemplo, quando o saldo de pontos do cartão de fidelidade é alterado, você precisa aplicar update ou patch a um único LoyaltyObject. Esse é o caso de todos os campos definidos no nível do LoyaltyObject.

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

Ler no app Google Pay

Os usuários poderão adicionar cartões de fidelidade ao app Google Pay quando verificarem ou adicionarem manualmente os detalhes do cartão de fidelidade. A API Google Pay for Passes cria um LoyaltyObject que não se refere à LoyaltyClass definida anteriormente. Você não precisa realizar nenhuma ação para criar o novo objeto ou classe. No entanto, o LoyaltyObject criado pela API Google Pay for Passes não pode ser atualizado e se comporta como um cartão estático.

Ofertas vinculadas

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

Como criar a oferta antes de vincular

Para vincular uma oferta vinculada, as classes e os objetos da oferta vinculados ao cartão de fidelidade 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 LoyaltyObject.

Vincular ofertas a um cartão de fidelidade

As ofertas existentes podem ser vinculadas a um cartão de fidelidade usando as chamadas insert, ou update, ou patch, ou modifyLinkedOfferObjects.

Quando as ofertas são vinculadas a um cartão de fidelidade após a criação do cartão pela chamada insert ou quando as ofertas são vinculadas e desvinculadas de um cartão de fidelidade existente pela chamada update, o campo linkedOfferIds pode ser gravado com o restante do LoyaltyObject usando o formato estabelecido:

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

Quando as ofertas são vinculadas e desvinculadas de um cartão de fidelidade existente 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. Além disso, 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 cartões de fidelidade com ofertas vinculadas

As ofertas vinculadas serão exibidas na visualização do cartão de fidelidade 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 cartão de fidelidade, 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.

Notificações acionadas por fronteira geográfica virtual

O Google pode acionar notificações relacionadas a um Objeto salvo de um consumidor com base na proximidade do consumidor de um local definido.

Há duas maneiras de adicionar informações de geolocalização:

1. As informações de geolocalização do Google Maps são usadas no momento da criação de uma conta do Merchant Center da API Google Pay for Passes.
2. É possível adicionar coordenadas ao objeto ou à classe por meio da API REST.

Veja instruções sobre como adicionar coordenadas a objetos ou classes em Adicionar informações de geolocalização usando a API REST.

Conceitos de fronteira geográfica virtual

Usando informações de geolocalização no Google Maps, o Google determina, por meio de algoritmos, se o usuário está fisicamente na loja ou na área. Essa detecção se aplica a todas as classes e objetos desenvolvidos na conta da API Google Pay for Passes Merchant Center.

O algoritmo considera GPS, Wi-Fi, Bluetooth, movimento, tempo de permanência e outros fatores. Quando se determina que o usuário está fisicamente presente, é acionada uma notificação por fronteira geográfica virtual.

Se as coordenadas forem especificadas manualmente em Object, a notificação de fronteira geográfica virtual será acionada quando estiverem a 150 metros das coordenadas.

Frequência, limitação e desativação de notificações por fronteira geográfica virtual por parte do usuário

Um usuário recebe um máximo de quatro notificações por dia.

Quando há vários objetos salvos dentro da fronteira geográfica virtual, é exibida uma única notificação (por conta da API Google Pay for Passes Merchant Center). Essa notificação não é modificável e é exibida como um carrossel. Os objetos são cíclicos dentro do carrossel:

Para que as notificações por fronteira geográfica virtual funcionem, o usuário precisa ativar Atualizações sobre os itens nas configurações de notificação do app Google Pay e ter os serviços de localização ativados para o dispositivo.

Adicionar informações de geolocalização usando a API REST

Especifique uma matriz de locais (latitudes e longitudes) nas classes ou nos objetos. O Google verifica a geolocalização atual do usuário com relação à lista de locais associados a uma classe ou a um objeto e notifica o usuário caso ele esteja a 150 metros de um dos locais. Veja exemplos de códigos que mostram como especificar locais nas classes ou nos objetos:

{
  ... //Class or Object content

  "locations": [{
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.422087,
    "longitude": -161446
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.429379,
    "longitude": -121.12272999999999
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.333646,
    "longitude": -122.884853
  }]
}

List<LatLongPoint> locations = new ArrayList<LatLongPoint>();
locations.add(new LatLongPoint().setLatitude(37.422087).setLongitude(
    -122.161446));
locations.add(new LatLongPoint().setLatitude(37.429379).setLongitude(
    -121.12272999999999));
locations.add(new LatLongPoint().setLatitude(37.333646).setLongitude(
    -122.884853));

yourClassOrObject.setLocations(locations);

$locations = array(
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.442087,
    'longitude' => -122.161446
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.429379,
    'longitude' => -122.12272999999999
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.333646,
    'longitude' => -121.884853
  )
);

offer_class_object = {
  # class or object content
  'locations': [{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.442087,
    'longitude': -122.161446
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.429379,
    'longitude': -122.12272999999999
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.333646,
    'longitude': -121.884853
  }]
}

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:

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

Inscrição e login

O recurso de inscrição e login no programa de fidelidade permite que os usuários procurem seu programa e participem ou façam login na conta pelo Google Pay. Para mais detalhes, leia Inscrição e login.