Para que serve

Uma classe de cartões define um conjunto de propriedades comuns em vários cartões, semelhante a um modelo. Por exemplo, se você estivesse emitindo ingressos de um evento, a classe de cartões definiria campos que são iguais em todos os ingressos, como o nome, a data e a hora do evento.

Todos os cartões emitidos precisam referenciar uma classe de cartão. Também é necessário atribuir um ID exclusivo a cada classe de cartão criada, que será usado como referência na criação de cartões.

Como isso acontece

Uma classe de cartões é definida no formato JSON e pode ser criada com a API REST da Carteira do Google, o SDK do Android ou no Console Business da Carteira do Google.

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "logo": {
    "sourceUri": {
      "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660"
    },
    "contentDescription": {
      "defaultValue": {
        "language": "en-US",
        "value": "LOGO_IMAGE_DESCRIPTION"
      }
    }
  },
  "eventName": {
    "defaultValue": {
      "language": "en-US",
      "value": "Google Live"
    }
  },
  "venue": {
    "name": {
      "defaultValue": {
        "language": "en-US",
        "value": "Shoreline Amphitheater"
      }
    },
    "address": {
      "defaultValue": {
        "language": "en-US",
        "value": "ADDRESS_OF_THE_VENUE"
      }
    }
  },
  "dateTime": {
    "start": "2023-04-12T11:30"
  },
  "reviewStatus": "UNDER_REVIEW",
  "hexBackgroundColor": "#264750",
  "heroImage": {
    "sourceUri": {
      "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336"
    },
    "contentDescription": {
      "defaultValue": {
        "language": "en-US",
        "value": "HERO_IMAGE_DESCRIPTION"
      }
    }
  }
}
    

Para que serve

Um objeto de cartões define as propriedades de um cartão exclusivo que será emitido para um usuário específico. Por exemplo, o objeto de cartões de um ingresso de evento define campos exclusivos de um ingresso específico, como o número do assento ou um QR code desse ingresso.

Quando um objeto de cartão é criado, a API Google Wallet armazena um novo cartão e o associa à sua conta de emissor. Esse cartão armazenado é uma combinação das propriedades exclusivas do objeto de cartões e das propriedades do modelo da classe de cartões associada.

Você também precisa atribuir a cada objeto de cartão um ID exclusivo, que será usado como referência ao emitir um cartão.

Como isso acontece

Um objeto de cartões é definido no formato JSON e pode ser criado com a API REST da Carteira do Google ou o SDK do Android.

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "5"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "G"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "40"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "3A"
      }
    }
  },
  "barcode": {
    "type": "QR_CODE",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}
    

Para que serve

Para emitir um cartão para um usuário, uma classe de cartões e um objeto de cartões precisam ser codificados em um JSON Web Token (JWT). O formato JWT é um padrão comum e aberto para representar declarações entre duas partes. No caso de emissão de cartões com a API Google Wallet, os JWTs são usados para enviar uma declaração de que um usuário tem o direito de acessar um cartão específico associado à sua conta de emissor.

Quando um JWT é enviado à API Google Wallet, os dados codificados são usados para identificar um cartão específico e emiti-lo ao usuário. Se o cartão já foi emitido, esses dados também permitem que a API Google Wallet identifique que o cartão é uma cópia, para que ele não seja adicionado à Carteira do Google do usuário mais de uma vez.

Como isso acontece

Os JWTs são definidos no formato JSON com base na especificação JWT. Para definir um JWT para emitir um cartão com a API Google Wallet, forneça as informações sobre o cartão que você quer emitir na propriedade payload do JWT.

{
  "iss": "issuer@example.com",
  "aud": "google",
  "typ": "savetowallet",
  "iat": 1696877738,
  "origins": [
    "www.example.com"
  ],
  "payload": {
    "eventTicketObjects": [
      {
        "id": "ISSUER_ID.LOYALTY_OBJECT_SUFFIX"
      }
    ]
  }
}
    

Para que serve

Todos os JWTs enviados à API Google Wallet para emitir um cartão precisam ser assinados com as credenciais que você forneceu anteriormente no Console Business da Carteira do Google. A assinatura usa suas credenciais para criptografar o JWT. Assim, seus cartões permanecem seguros e a API Google Wallet pode autenticar se os detalhes do cartão codificados são válidos e associados à sua conta de emissor.

Como isso acontece

As bibliotecas de cliente da Carteira do Google e o SDK do Android oferecem métodos convenientes para assinar seus JWTs. Há também várias bibliotecas de código aberto disponíveis que lidam com a complexidade da assinatura de código para você escolher.

Para quem usa a API REST da Carteira do Google para emitir cartões, o JWT é assinado com uma chave de conta de serviço do Google Cloud. Para quem usa o SDK para Android da Carteira do Google, o SDK processa automaticamente a assinatura do JWT com a impressão digital SHA-1 do seu certificado de assinatura de apps.

Para proteger suas credenciais, os JWTs devem ser assinados apenas no seu servidor ou usando o SDK do Android da Carteira do Google no seu app.

  // Create the JWT as a HashMap object
  HashMap claims = new HashMap();
  claims.put("iss", ((ServiceAccountCredentials) credentials).getClientEmail());
  claims.put("aud", "google");
  claims.put("origins", Arrays.asList("www.example.com"));
  claims.put("typ", "savetowallet");

  // Create the Google Wallet payload and add to the JWT
  HashMap payload = new HashMap();
  payload.put("eventTicketObjects", Arrays.asList(newObject));
  claims.put("payload", payload);

  // Google Cloud service account credentials are used to sign the JWT
  Algorithm algorithm =
      Algorithm.RSA256(
          null, (RSAPrivateKey) ((ServiceAccountCredentials) credentials).getPrivateKey());
  String token = JWT.create().withPayload(claims).sign(algorithm);
        

  // Create the JWT claims
  let claims = {
    iss: this.credentials.client_email,
    aud: 'google',
    origins: ['www.example.com'],
    typ: 'savetowallet',
    payload: {
      eventTicketObjects: [newObject]
    },
  };

  // The service account credentials are used to sign the JWT
  let token = jwt.sign(claims, this.credentials.private_key, { algorithm: 'RS256' });
        

  # Create the JWT claims
  claims = {
      'iss': self.credentials.service_account_email,
      'aud': 'google',
      'origins': ['www.example.com'],
      'typ': 'savetowallet',
      'payload': {
          # The listed classes and objects will be created
          'eventTicketObjects': [new_object]
      }
  }

  # The service account credentials are used to sign the JWT
  signer = crypt.RSASigner.from_service_account_file(self.key_file_path)
  token = jwt.encode(signer, claims).decode('utf-8')
        

Para que serve

Depois de criar um JWT assinado, você vai poder emitir seu cartão para um usuário da Carteira do Google. Para fazer isso, apresente ao usuário um botão ou um link "Adicionar à Carteira do Google". Quando um usuário clica no botão ou no hiperlink, o JWT assinado é enviado para a API Google Wallet, que a descriptografa usando suas credenciais salvas. Depois que a assinatura JWT for autenticada, o cartão será emitido para que o usuário salve na Carteira do Google.

Como isso acontece

Para criar um botão "Adicionar à Carteira do Google" em um app Android, use o SDK da Carteira do Google para Android, que oferece métodos para gerar o botão. Para todas as outras plataformas, incluindo Web, e-mail e mensagens de texto, crie um hiperlink no formato https://pay.google.com/gp/v/save/<signed_jwt>. Sempre que possível, o melhor é entregar esse link ao usuário como um botão "Adicionar à Carteira do Google".

Para mais informações sobre como usar o botão "Adicionar à Carteira do Google", consulte as Diretrizes da promoção de marca da API Google Wallet.

  https://pay.google.com/gp/v/save/<signed_jwt>
        

  private lateinit var walletClient: PayClient
  private val addToGoogleWalletRequestCode = 1000
  private lateinit var addToGoogleWalletButton: View

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    walletClient = Pay.getClient(this)
    addToGoogleWalletButton.setOnClickListener {
      walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode)
    }
  }
        

Depois que o usuário salvar o cartão emitido, ele vai aparecer no app Carteira do Google com todos os outros cartões salvos.