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 ofertas. Os conceitos abordados neste guia ajudam a entender melhor os recursos dos ingressos de ofertas salvas.
Os seguintes casos de uso estão disponíveis apenas para a indústria de ofertas:
- Atualizar cartões
- Notificação de expiração da oferta
- 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.
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 OfferClass
ou usar o Merchant Center do Google Pay.
O Google propaga essas informações para todos os OfferObject
s associados à OfferClass
atualizada. Esse é o caso de todos os campos definidos no nível da OfferClass
.
Para atualizar um único cartão, como quando a expiração da oferta é modificada, você precisa alterar ou aplicar patch usando update
ou patch
, respectivamente, a um único OfferObject
. Esse é o caso de todos os campos definidos no
nível do OfferObject
.
À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 OfferClass
list
.
É possível encontrar todos os objetos de uma classe específica ao chamar o método OfferObject
list
.
Notificação de expiração da oferta
Para lembrar usuários de usar ofertas antes que elas expirem, uma notificação padrão é acionada 48 horas antes da validade. Para acionar uma notificação, uma oferta precisa atender aos seguintes critérios:
- Ela não pode ter acionado uma notificação de expiração no dispositivo do usuário.
- Ela precisa ter uma validade
datetime
válida no futuro, definida emvalidTimeInterval.end.date
. - Ela precisa ter sido salva no dispositivo do usuário há mais de 12 horas.
- Ela não pode ter o campo gravável
disableExpirationNotification
definido comoTrue
. Por padrão, esse campo é determinado comofalse
.
A seguinte captura de tela mostra um exemplo da notificação padrão não modificável:
![](https://developers-dot-devsite-v2-prod.appspot.com/static/pay/passes/images/offer-expiration-notification.png?authuser=9&hl=pt)
- A oferta expira (hoje, amanhã, em [x] dias)
class.title
class.titleImage
O cabeçalho na notificação de expiração da oferta não pode ser personalizado.
Horas de indisponibilidade
Se a notificação de expiração da oferta estiver configurada para ser exibida entre 22h e 6h na hora local do usuário, a oferta aparecerá antes ou depois desse período.
Hora personalizada de notificação de expiração da oferta
Você pode personalizar quando a notificação de expiração da Offer
aparece usando o campo message.displayInterval.start.date
em OfferObjects
ou OfferClasses
. Se uma hora personalizada de notificação for definida, a notificação de expiração será acionada de acordo com a message.displayInterval.start.date
, em vez da lógica padrão calculada de validTimeInterval.end.date
. Este é um exemplo de hora personalizada para uma notificação de expiração:
{ “message”: { “messageType”: “expirationNotification”, “displayInterval”: { “start”: { “date”: datetime } } } }
A displayInterval.start.date
define a hora em que a notificação é exibida. Ela pode ser configurada até 30 dias antes da data de expiração. Se um período maior que esse for especificado, a notificação será acionada na marca de 30 dias. Essa mensagem não requer um campo de cabeçalho e corpo. Se estiverem incluídos, eles não serão usados.
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:
- 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.
- É 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:
![](https://developers-dot-devsite-v2-prod.appspot.com/static/pay/passes/images/geofenced-notification-example.png?authuser=9&hl=pt)
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 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ósobject.validTimeInterval.end.date
expirar. - O campo
object.state
está marcado comoExpired
,Inactive
ouCompleted
.
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 } } } } … … … }