Interagir com os usuários pelo Google Pay

Adicionar mensagens durante a atualização de informações importantes

Todas as indústrias têm uma seção de mensagens. Use essa seção para dar destaque a todas as informações importantes, como alterações feitas nos programas de vales-presente, ofertas, ingressos para eventos e cartões de fidelidade, de embarque para voos e de transporte público. Para mais informações, consulte as páginas de modelo para seu tipo de cartão:

Cartões de embarque Ingressos de eventos Vales-presente Fidelidade Ofertas Cartões de transporte público

Para adicionar as mensagens a uma classe ou a um objeto que use métodos insert, update ou patch, basta preencher a propriedade da matriz messages[]. Também é possível adicionar às mensagens atuais (até um máximo de 10) pelo método addMessage. Para mais informações, consulte a Referência.

O código a seguir recebe a data de validade da oferta atual ( validTimeInterval.end), atualiza a data de validade e adiciona à matriz messages[]. Assim, o usuário pode perceber que as informações foram alteradas quando visualizar o Object salvo no app Google Pay:

Java

// Get the specific Offer Object
OfferObject obj = client.offerobject().get("2945482443380251551.ExampleObject1").execute();

// Update the version, validTimeInterval.end, and add a message
obj.setVersion(obj.getVersion() + 1L);
obj.setValidTimeInterval(new TimeInterval().setEnd(new DateTime().setDate(new com.google.api.client.util.DateTime(new Date().getTime() + 263000000000L))));

// Get the current messages
List messages = obj.getMessages();

// Define new message
WalletObjectMessage message = new WalletObjectMessage()
  .setHeader("Important Notice")
  .setBody("Your offer has been extended!");

// Add the new message about updates to the Offer Object
messages.add(message);
obj.setMessages(messages);

// Update the Offer Object
OfferObject returnObj = client.offerobject().patch(obj.getId(), obj).execute();

PHP

// Get the specific Offer Object
Google_OfferObject $offerObj = $service->offerobject->get('2945482443380251551.ExampleObject1');

// Update the version, validTimeInterval.end, and add a message
$offerObj->setVersion($offerObj->getVersion() + 1);
$validTimeInterval = new Google_TimeInterval();
$startDateTime = new Google_DateTime();
$startDateTime->setDate('2013-06-12T23:20:50.52Z');
$validTimeInterval->setStart($startDateTime);
$endDateTime = new Google_DateTime();
$endDateTime->setDate('2013-12-12T23:20:50.52Z');
$validTimeInterval->setEnd($endDateTime);
$offerObj->setValidTimeInterval($validTimeInterval)

// Get the current messages
$messages = $offerObj->getMessages();

// Define new message
$newMessage = array(
  'header' => 'Important Notice',
  'body' => 'Your offer has been extended!',
  'kind' => 'walletobjects#walletObjectMessage'
);

// Add the new message about updates to the Offer Object
array_push($messages, $newMessage);
$offerObj->setMessages($messages);

// Update the Offer Object
Google_OfferObject offerObj = $service->offerobject->update('2945482443380251551.ExampleObject1',offerObj);

Python

# Get the specific Offer Object
offer_object = service.offerobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the version, validTimeInterval.end, and add a message
offer_object['version'] = str(int(offer_object['version']) + 1)
offer_object['validTimeInterval'] = {
     'start' : {'date':'2018-01-20T23:20:50.520Z'}
     ,'end' : {'date':'2018-01-24T23:20:50.520Z'}
    }

// Get the current messages
messages = offer_object['messages']

// Define new message
message = {
   'header': 'Important Notice',
   'body': 'Your offer has been extended!',
   'kind': 'walletobjects#walletObjectMessage'
 }

// Add the new message about updates to the Offer Object
messages.append(message)
offer_object['messages'] = messages

# Update the Offer Object
api_request = service.offerobject().update(resourceId='2945482443380251551.ExampleObject1',body=offer_object)
api_response = api_request.execute()

Observação: você verá uma mensagem imediatamente após a inserção de um Object, exceto se um startTime for definido. A mensagem será exibida em uma lista de mensagens indefinidamente, se endTime não for fornecido. Para mais informações, consulte a propriedade messages[].

Estado de atualização

Independentemente da indústria, todos os objetos têm uma propriedade state. A atualização do estado do objeto é uma maneira importante de informar ao cliente que o cartão foi resgatado ou expirou.

Toda atualização deve começar com uma solicitação GET para recuperar o Object. Isso garante que a versão mais recente do objeto seja usada. A versão do objeto precisa ser incrementada quando o saldo é alterado. Para salvar o objeto atualizado Object, faça uma solicitação PUT.

Este é um exemplo de URIs REST usados em GET de um objeto e em PUT (atualização) de um offerObject:

GET https://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId
PUT https://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId

Para saber mais sobre os diferentes métodos GET e de atualização por indústria, consulte a Referência.

Observação: os métodos PUT (atualização) substituem todo o objeto pela nova definição em PUT. Se você só quiser atualizar campos específicos e manter os dados Object atuais, use métodos PATCH conforme mostrado na Referência. Para ver as diferenças entre PUT e PATCH, consulte a semântica de patch (PUT e PATCH).

As amostras de código a seguir fornecem exemplos de como atualizar um offerObject em linguagens diferentes. O código seria semelhante para objetos em outras indústrias:

Java

// Get the specific Offer Object
OfferObject obj = client.offerobject().get("2945482443380251551.ExampleObject1").execute();
// Update the version and state
obj.setVersion(obj.getVersion() + 1L);
obj.setState("expired"); //see the Reference API for valid "state" options
// Update the Offer Object
OfferObject returnObj = client.offerobject().update(obj.getId(), obj).execute();

PHP

// Get the specific Offer Object
Google_OfferObject offerObj = $service->offerobject->get('2945482443380251551.ExampleObject1');
// Update the version and points
offerObj.setVersion(offerObj.getVersion() + 1);
offerObj.setState("state"); // see the Reference API for valid "state" options
// Update the Offer Object
Google_OfferObject offerObj = $service->offerobject->update('2945482443380251551.ExampleObject1',offerObj);

Python

# Get the specific Offer Object
offer_object = service.offerobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the version and state
offer_object['version'] = str(int(offer_object['version']) + 1)
offer_object['state'] = 'expired' # see the Reference API for valid "state" options
# Update the Offer Object
api_request = service.offerobject().update(resourceId='2945482443380251551.ExampleObject1',body=offer_object)
api_response = api_request.execute()

Localização

A API Google Pay for Passes permite que os comerciantes forneçam conteúdo localizado que será exibido ao usuário com base na localidade. Os campos extras na API são incluídos para fornecer esse recurso. Cada campo localizado é um objeto aninhado LocalizedString do formulário:

{
  "kind": "walletobjects#localizedString",
  "translatedValues": [
    {
      "kind": "walletobjects#translatedString",
      "language": string,
      "value": string
    }
  ],
  "defaultValue": [
    {
      "kind": "walletobjects#translatedString",
      "language": string,
      "value": string
    }
  ]
}

O campo defaultValue é obrigatório para todos os itens LocalizedStrings. O idioma e o valor são obrigatórios em todas as translatedStrings.

O campo de idioma precisa se referir a uma tag de idioma BCP 47. (por exemplo, "en-US", "pt-BR", "es-419" etc). O campo "value" apresenta o valor traduzido da string que será exibida ao usuário se houver conteúdo para a localidade dele.

As strings de localização exibidas terão como base a melhor correspondência da localidade do usuário. O valor DefaultValue será usado se nenhum translatedValue apropriado for fornecido. Os campos não localizados não serão usados se o campo localizado correspondente estiver definido.

Determinar se um usuário removeu o cartão

Para verificar se um usuário removeu o cartão (de fidelidade, por exemplo) do Google Pay, recupere o Object do usuário com a chamada get a seguir e verifique o atributo hasUsers.

Por exemplo, para verificar se há um loyaltyObject com GET:

GET https://walletobjects.googleapis.com/walletobjects/v1/loyaltyObject/objectId

Se todos os usuários tiverem excluído o cartão ou se o cartão de fidelidade tiver sido removido, o Google não excluirá o objeto. O atributo hasUsers no objeto é definido como "false".

A verificação do atributo hasUsers pode ser feita em tempo real quando o usuário faz login no site ou no app, ou em um processo em lote para um grande número de usuários de uma só vez.

Você definiu o ID do objeto usado para recuperar o LoyaltyObject quando criou o objeto. Para fornecer informações personalizadas aos usuários sobre os níveis e os saldos de pontos atuais, armazene os IDs no seu próprio repositório.

Para saber mais sobre os diferentes métodos GET, consulte a Referência. O Google não fornece notificações em tempo real quando um objeto é excluído. Para isso, seria necessário implementar um serviço listener e obedecer a um determinado contrato de nível de serviço.

Maneiras de interação específicas por indústria

Algumas maneiras de interagir são específicas de uma indústria de cartões. Consulte a página "Casos de uso" de cada indústria para ver detalhes da implementação:

Cartões de embarque Ingressos de eventos Vales-presente Fidelidade Ofertas Cartões de transporte público