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 vales-presente:

Atualizar saldo monetário

A atualização do saldo do vale-presente é uma maneira importante de se engajar com o cliente.

Toda atualização deve começar com uma solicitação GET para recuperar o GiftCardObject. 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, faça uma solicitação PUT.

Os seguintes URIs REST são usados para GET (receber) e UPDATE (atualizar) um objeto:

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

Os seguintes trechos de código fornecem exemplos de como atualizar um objeto em linguagens diferentes. Anote a propriedade do saldo:

Recurso

{
  "kind" : "walletobjects#giftCardObject",
  "classId" : "1234567890.ExampleGCClass",
  "id" : "1234567890.ExampleGCObject",
  "cardNumber" : "123jkl4889",
  "pin" : "1111",
  "eventNumber" : "123456",
  "balance" : {
    "kind" : "walletobjects#money",
    "micros" : 20000000,
    "currencyCode" : "USD"
  },
  "balanceUpdateTime" : {
    "date" : '2014-01-12T23:20:50.52Z'
  },
  "barcode" : {
    "alternateText" : "12345",
    "type" : "qrCode",
    "value" : "28343E3"
  },
  "textModulesData" : [{
    "header" : "Earn double points",
    "body" : "Jane, don't forget to use your Baconrista Rewards when " +
              "paying with this gift card to earn additional points"
  }],
  "linksModuleData" : {
    "uris" : [
      {
        "kind" : "walletobjects#uri",
        "uri" : "https://www.baconrista.com/mybalance?id=1234567890",
        "description" : "My Baconrista Gift Card Purchases"
      }]
  },
  "state" : "active"
}

Java

Barcode barcode = new Barcode().setType("qrCode")
    .setValue("28343E3")
    .setAlternateText("12345")

Money balance = new Money();
balance.setCurrencyCode("USD");
balance.setMicros(20000000L);

DateTime balanceUpdateTime = new DateTime();
balanceUpdateTime.setDate(new com.google.api.client.util.DateTime(new Date()));

// Define Text Module Data
List<TextModuleData> textModulesData = new ArrayList<TextModuleData>();
TextModuleData textModuleData = new TextModuleData()
    .setHeader("Earn double points")
    .setBody("Jane, don't forget to use your Baconrista Rewards when " +
                "paying with this gift card to earn additional points");
textModulesData.add(textModuleData);

// Define Links Module Data
List<Uri> uris = new ArrayList<Uri>();
Uri uri1 = new Uri().setDescription("My Baconrista Gift Card Purchases")
    .setUri("http://www.baconrista.com/mybalance?id=1234567890");
uris.add(uri1);
LinksModuleData linksModuleData = new LinksModuleData().setUris(uris);

// Define Wallet Instance
GiftCardObject object = new GiftCardObject()
    .setClassId("1234567890.ExampleGCClass").setId("1234567890.ExampleGCObject")
    .setState("active").setBarcode(barcode)
    .setTextModulesData(textModulesData)
    .setLinksModuleData(linksModuleData)
    .setBalance(balance)
    .setBalanceUpdateTime(balanceUpdateTime)
    .setEventNumber("123456").setCardNumber("123jkl4889").setPin("1111");

PHP

// Define barcode type and value.
$barcode = new Google_Service_Walletobjects_Barcode();
$barcode->setAlternateText('12345');
$barcode->setType('qrCode');
$barcode->setValue('28343E3');
// Define text module data.
$textModulesData = array(
    array(
        'header' => 'Earn double points',
        'body' => 'Jane, don\'t forget to use your Baconrista Rewards when '.
                  'paying with this gift card to earn additional points'
    )
);
// Define links module data.
$linksModuleData = new Google_Service_Walletobjects_LinksModuleData();
$uris = array (
    array(
        'uri' => 'http://www.baconrista.com/mybalance?id=1234567890',
        'kind' => 'walletobjecs#uri',
        'description' => 'My Baconrista Gift Card Purchases'
    )
);
$linksModuleData->setUris($uris);

$balance = new Google_Service_Walletobjects_Money();
$balance->setKind('walletobjects#money');
$balance->setMicros(20000000);
$balance->setCurrencyCode('USD');

$balanceUpdateTime = new Google_Service_Walletobjects_DateTime();
date_default_timezone_set('UTC');
$balanceUpdateTime->setDate(date("Y-m-d\TH:i:s.u\Z"));

// Create wallet object.
$giftCardObject = new Google_Service_Walletobjects_GiftCardObject();
$giftCardObject->setClassId("1234567890.ExampleGCClass");
$giftCardObject->setId("1234567890.ExampleGCObject");
$giftCardObject->setState('active');
$giftCardObject->setBarcode($barcode);
$giftCardObject->setLinksModuleData($linksModuleData);
$giftCardObject->setTextModulesData($textModulesData);
$giftCardObject->setBalance($balance);
$giftCardObject->setBalanceUpdateTime($balanceUpdateTime);
$giftCardObject->setCardNumber('123jkl4889');
$giftCardObject->setEventNumber('123456');
$giftCardObject->setPin('1111');

Python

giftcard_object = {
    'kind' : 'walletobjects#giftCardObject',
    'classId' : '1234567890.ExampleGCClass',
    'id' : '1234567890.ExampleGCObject',
    'cardNumber' : '123jkl4889',
    'pin' : '1111',
    'eventNumber' : '123456',
    'balance' : {
      'kind' : 'walletobjects#money',
      'micros' : 20000000,
      'currencyCode' : 'USD'
    },
    'balanceUpdateTime' : {
      'date' : datetime.datetime.utcnow().isoformat("T") + "Z"
    },
    'barcode' : {
        'alternateText' : '12345',
        'type' : 'qrCode',
        'value' : '28343E3'
    },
    'textModulesData': [{
      'header': 'Earn double points',
      'body': 'Jane, don\'t forget to use your Baconrista Rewards when  ' +
              'paying with this gift card to earn additional points. '
    }],
    'linksModuleData': {
      'uris': [
        {
          'kind': 'walletobjects#uri',
          'uri': 'http://www.baconrista.com/mybalance?id=1234567890',
          'description': 'My Baconrista Gift Card Purchases'
        }]
    },
    'state': 'active'
}

Salvar no app Google Pay

Os usuários têm a opção de adicionar um vale-presente ao app Google Pay. Para isso, verificam ou adicionam manualmente os detalhes do cartão de fidelidade. A API do Google Pay for Passes cria um GiftCardObject que não se refere a um GiftCardClass definido anteriormente. Nenhuma ação é obrigatória de sua parte para criar o novo objeto ou classe.

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 quando é criada uma conta do Merchant Center da API Google Pay for Passes.
  2. É possível adicionar as 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 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 vale-presente 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 vale-presente terminou. O cartão pode ser movido para "Passes expirados" a qualquer momento até 24 horas após object.validTimeInterval.end.date.
  • O campo state de GiftCardObject está marcado como Expired, Inactive ou Completed.

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.