Casos de uso

Neste guia, descrevemos as seguintes maneiras específicas de usar a API Google Pay for Passes a fim de engajar os clientes na indústria de Loyalty:

Atualizar o saldo monetário ou de pontos

A atualização do saldo de pontos do cartão de fidelidade é uma maneira importante de se engajar com o cliente.

Há formas diferentes de saldos de fidelidade:

  • String
  • Int
  • Double
  • Money

As propriedades loyaltyPoints.balance e secondaryLoyaltyPoints.balance só precisam preencher um dos formulários acima.

Toda atualização precisa começar com uma solicitação GET para recuperar o LoyaltyObject. Isso garante que a versão mais recente do objeto seja usada. Para salvar o objeto atualizado, faça uma solicitação PUT.

Os seguintes URIs REST são usados para GET de um objeto e para UPDATE (atualização) de um objeto:

GET https://www.googleapis.com/walletobjects/v1/loyaltyObject/resourceId
PUT https://www.googleapis.com/walletobjects/v1/loyaltyObject/resourceId

Os seguintes exemplos de código fornecem exemplos de como atualizar um objeto em linguagens diferentes:

Java

// Get the specific Loyalty Object
LoyaltyObject obj = client.loyaltyobject().get("2945482443380251551.ExampleObject1").execute();
// Update points
obj.setPoints(points);
// Update the Loyalty Object
LoyaltyObject returnObj = client.loyaltyobject().update(obj.getId(), obj).execute();

PHP

// Get the specific Loyalty Object
Google_LoyaltyObject loyaltyObj = $service->loyaltyobject->get('2945482443380251551.ExampleObject1');
// Update the points
loyaltyObj.setLoyaltyPoints(points);
// Update the Loyalty Object
Google_LoyaltyObject loyaltyObj = $service->loyaltyobject->update('2945482443380251551.ExampleObject1',loyaltyObj);

Python

# Get the specific Loyalty Object
loyalty_object = service.loyaltyobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the points
loyalty_object['points'] = points
# Update the Loyalty Object
api_request = service.loyaltyobject().update(resourceId='2945482443380251551.ExampleObject1',body=loyalty_object)
api_response = api_request.execute()

Salvar no app Google Pay

Os usuários podem adicionar um cartão de fidelidade ao app Google Pay verificando ou adicionando manualmente os detalhes do cartão de fidelidade. A API Google Pay for Passes cria um LoyaltyObject que não referencia uma LoyaltyClass definida anteriormente. Nenhuma ação é obrigatória de sua parte para criar o novo objeto ou classe.

Ofertas vinculadas ao Loyalty

As ofertas vinculadas ao Loyalty permitem que ofertas atuais sejam exibidas dentro da visualização do cartão de fidelidade, facilitando a descoberta de conteúdo relevante pelo usuário. O campo de lista gravável linkedOfferIds em um LoyaltyObject indica quais ofertas estão associadas ao cartão de fidelidade. As ofertas atuais podem ser vinculadas a um cartão de fidelidade usando-se o insert das chamadas REST, a atualização ou modifyLinkedOfferObjects.

Como criar a oferta antes de vincular

Para criar uma oferta vinculada à fidelidade, as classes e os objetos da oferta vinculados ao cartão de fidelidade já precisam ter sido criados. Para saber mais sobre como criar ofertas, consulte Ofertas. Diferentemente das ofertas independentes, as vinculadas à fidelidade não exigem que um usuário salve explicitamente a oferta. O campo id encontrado no objeto da oferta é usado a fim de apontar para o objeto do cartão de fidelidade.

Vincular ofertas a um cartão de fidelidade

Um cartão de fidelidade pode ter ofertas vinculadas a ele na criação usando-se a chamada de insert, bem como quando é atualizado. Uma nova chamada REST também está disponível especificamente para alterar as ofertas vinculadas a um cartão de fidelidade.

Como vincular uma oferta quando um cartão de fidelidade é criado

As ofertas poderão ser vinculadas a um cartão de fidelidade depois que ele for criado. LoyaltyObjects são inseridos fazendo-se uma solicitação POST para o seguinte URI REST:

https://www.googleapis.com/walletobjects/v1/loyaltyClass

O campo linkedOfferIds pode ser escrito com o resto do LoyaltyObject, usando-se o formato estabelecido:

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

Como vincular uma oferta a um cartão de fidelidade atual

Também é possível modificar as ofertas vinculadas a um cartão de fidelidade mesmo após a criação. Isso pode ser feito com uma chamada de atualização ou com um novo endpoint, modifyLinkedOfferObjects, criado especificamente para oferecer suporte à vinculação e à remoção de ofertas do cartão de fidelidade.

Atualize um LoyaltyObject atual fazendo uma solicitação PUT para o seguinte endereço:

https://www.googleapis.com/walletobjects/v1/loyaltyObject/resourceId

O método modifyLinkedOfferObjects é exclusivo da classe de fidelidade e envia uma solicitação POST para o seguinte endereço:

https://www.googleapis.com/walletobjects/v1/loyaltyObject/resourceId/modifyLinkedOfferObjects

Veja mais informações sobre como usar a chamada modifylinkedofferobjects neste link.

O corpo da solicitação tem o seguinte formato:

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

Remover ofertas vinculadas de um cartão de fidelidade

Se o campo linkedOfferIds for gravado durante uma chamada de atualização do LoyaltyObject, as novas ofertas incluídas nessa chamada substituirão as atuais. Além disso, uma oferta pode ser removida usando-se o campo removeLinkedOfferObjectIds na chamada modifylinkedofferobjects.

Além disso, as ofertas vinculadas são removidas da exibição do cartão de fidelidade com a atualização da propriedade object.state do objeto de oferta vinculada para completed. Por fim, as ofertas vinculadas são removidas automaticamente da exibição assim que a object.validTimeInterval.end.date definida na oferta vinculada passa. Consulte a API de referência.

Como projetar cartões de fidelidade com ofertas vinculadas à fidelidade

Um cartão de fidelidade com ofertas vinculadas tem um modelo diferente do cartão de fidelidade típico, conforme mostrado abaixo.

Modelo vinculado de cartão de fidelidade da API Google Pay for Passes
  1. class.programLogo
  2. class.issuerName
  3. class.programName
  4. class.heroImage
  5. object.loyaltyPoints.pointsLabel
  6. object.loyaltyPoints.balance
  7. object.barcode.type

    object.barcode.value

  8. object.accountId
  9. class.hexBackgroundColor
  10. offerClass.heroImage
  11. offerClass.title
  12. offerObject.validTimeInterval.end
  13. class.accountNameLabel
  14. object.accountName
  15. class.accountIdLabel
  16. object.accountId
  17. *.imageModulesData.mainImage
  18. *.messages[0].header
  19. *.messages[0].body
  20. *.textModulesData.header
  21. *.textModulesData.body
  22. *.infoModuleData.labelValueRows[0].columns[0].label
  23. *.infoModuleData.labelValueRows[0].columns[0].value
  24. *.linksModuleData.uris[2]
  25. *.linksModuleData.uris[0]
  26. *.linksModuleData.uris[1]

A oferta vinculada à fidelidade também utiliza um modelo diferente, conforme mostrado abaixo.

Modelo vinculado de cartão de fidelidade da API Google Pay for Passes
  1. class.heroImage
  2. object.barcode.type
    object.barcode.value
  3. object.barcode.alternateText
  4. class.title
  5. class.details
  6. object.validTimeInterval.end
  7. class.finePrint

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. As coordenadas podem ser adicionadas 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 no Object, a notificação por fronteira geográfica virtual será acionada quando estiver a 150 metros das coordenadas.

Frequência, limitação e desativação de notificações por fronteira geográfica virtual por 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:

Recurso

{
  ... //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
  }]
}

Java

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);

PHP

$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
  )
);

Python

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 aplicativo do Google Pay, há uma seção "Cartões expirados" que contém todos os cartões arquivados ou inativos. Um cartão de fidelidade será movido para a seção "Cartões expirados" se pelo menos uma das seguintes condições for verdadeira:

  • O object.validTimeInterval.end.date do cartão de fidelidade terminou. O cartão será movido para "Cartões expirados" a qualquer momento em até 24 horas após object.validTimeInterval.end.date .
  • O campo state do LoyaltyObject está marcado como Expired, Inactive ou Completed.

Depois que o usuário salvar um cartão, faça referência ao atributo objectId dele para definir um direcionamento para o cartão.

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

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

O cartão pode ser exibido no app Google Pay ou em um navegador da Web.