Criar cartões na Web usando a API Google Wallet

1. Introdução

Visão geral

A API Google Wallet permite interagir com usuários usando vários tipos de cartões: cartões de fidelidade, ofertas, vales-presente, ingressos de eventos, bilhetes de transporte público, cartões de embarque e muito mais. Cada tipo de cartão, ou classe de cartão, vem com campos e recursos específicos ao caso de uso para melhorar a experiência do usuário.

No entanto, eles podem não se adequar a todos os casos de uso. Para criar uma experiência mais personalizada, use o tipo de cartão genérico. Veja alguns exemplos de casos de uso para o tipo de cartão genérico:

  • Bilhetes de estacionamento
  • Cartões de inscrição em bibliotecas
  • Cupons de valor armazenado
  • Cartões de inscrição em academias
  • Reservas

Você pode usar cartões genéricos para qualquer caso de uso que possa ser apresentado:

  • Até três linhas de informações
  • (Opcional) Gráfico de código de barras
  • (Opcional) Seção "Detalhes"

Um exemplo de cartão da Carteira do Google para um evento de conferência

Para mais informações sobre a API Google Wallet ou como adicionar um botão Adicionar à Carteira do Google a uma página da Web, consulte a documentação do desenvolvedor da Carteira do Google.

Classes e objetos de cartão

A API Google Wallet apresenta métodos para criar o seguinte:

Tipo

Descrição

Classe de cartão

Um modelo para um objeto de cartão individual. Ela contém informações comuns a todos os objetos de cartão que pertencem a essa classe.

Objeto do cartão

Uma instância de uma classe de cartão exclusiva para um ID de usuário.

Sobre este codelab

Neste codelab, você concluirá as tarefas a seguir.

  1. Criar uma nova conta de emissor no modo de demonstração
  2. Criar uma conta de serviço para emitir cartões
  3. Criar uma nova classe de cartão genérico
  4. Criar um novo objeto de cartão
  5. Criar um botão Adicionar à Carteira do Google para salvar um cartão
  6. Exibir o botão na sua página da Web
  7. Processar o resultado do salvamento de cartão

Pré-requisitos

Objetivos

Após concluir este codelab, você vai conseguir fazer o seguinte:

  • Criar objetos de cartão usando a Carteira do Google
  • Criar um botão Adicionar à Carteira do Google

Suporte

Se você tiver dúvidas no codelab, o repositório do GitHub google-pay/wallet-web-codelab terá uma solução completa para referência.

2. Configuração

Nesta etapa, você vai criar uma conta de emissor no modo de demonstração. Assim, será possível criar classes e objetos de cartão que podem ser adicionados às carteiras dos usuários. Em seguida, crie um projeto e uma conta de serviço do Google Cloud. Eles serão usados para criar classes e objetos de cartão de forma programática da mesma maneira que um servidor de back-end. Por fim, você autorizará a conta de serviço do Google Cloud a gerenciar cartões na sua conta do emissor da Carteira do Google.

Criar uma conta de emissor da Carteira do Google

É necessário ter uma conta de emissor para criar e distribuir cartões para a Carteira do Google. Você pode se inscrever usando o Google Pay e Console da Carteira. Inicialmente, você terá acesso para criar cartões no modo de demonstração. Isso significa que apenas usuários de teste específicos vão poder adicionar os cartões criados por você. Os usuários de teste podem ser gerenciados no Google Pay e Console da Carteira.

Para mais informações sobre o modo de demonstração, consulte os Pré-requisitos do cartão genéricos.

  1. Abra a página do Google Pay e Console da Carteira
  2. Siga as instruções na tela para criar uma conta de emissor
  3. Selecione API Google Wallet.
  4. Confirme que você entende os Termos de Serviço e a Política de Privacidade
  5. Copie o valor de Código do emissor em um editor de texto ou outro local.
  6. Na guia Gerenciar, selecione Configurar contas de teste.
  7. Adicione os endereços de e-mail que você vai usar neste codelab

Ativar a API Google Wallet

  1. Faça login no console do Google Cloud.
  2. Se você ainda não tiver um projeto do Google Cloud, crie um agora. Consulte Como criar e gerenciar projetos para mais informações.
  3. Ative a API Google Wallet (também conhecida como API Google Pay for Passes) no projeto.

Crie uma conta de serviço e uma chave

Uma conta de serviço e uma chave da conta de serviço são necessárias para chamar a API Google Wallet. A conta de serviço é a identidade que chama a API Google Wallet. A chave da conta de serviço contém uma chave privada que identifica seu aplicativo como a conta de serviço. Como essa chave é confidencial, ela precisa ser mantida em sigilo.

Criar uma conta de serviço

  1. No console do Google Cloud, abra Contas de serviço
  2. Digite um nome, um ID e uma descrição para a conta de serviço
  3. Selecione CRIAR E CONTINUAR.
  4. Selecione CONCLUÍDO.

Criar uma chave de conta de serviço

  1. Selecione sua conta de serviço
  2. Selecione o menu KEYS.
  3. Selecione ADICIONAR CHAVE e escolha Criar chave
  4. Selecione o tipo de chave JSON.
  5. Selecione CRIAR.

Será solicitado que você salve o arquivo de chave na estação de trabalho local. Não se esqueça da localização dele.

Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

A variável de ambiente GOOGLE_APPLICATION_CREDENTIALS é usada pelos SDKs do Google para fazer a autenticação como uma conta de serviço e acessar diferentes APIs em um projeto do Google Cloud.

  1. Siga as instruções na documentação das chaves de conta de serviço do Google Cloud para definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.
  2. Verifique se a variável de ambiente está definida em um novo terminal (MacOS/Linux) ou sessão de linha de comando (Windows). Talvez seja necessário iniciar uma nova sessão se você já tiver uma aberta.
    echo $GOOGLE_APPLICATION_CREDENTIALS

Autorizar a conta de serviço

Por fim, você precisa autorizar a conta de serviço a gerenciar os cartões da Carteira do Google.

  1. Abra a página do Google Pay e Console da Carteira
  2. Selecione Usuários.
  3. Selecione Convidar um usuário.
  4. Insira o endereço de e-mail da conta de serviço (por exemplo, test-svc@myproject.iam.gserviceaccount.com)
  5. Selecione Desenvolvedor ou Administrador no menu suspenso Nível de acesso.
  6. Selecione Convidar.

3. Iniciar o app de amostra em Node.js

Duração:10h00

Nesta etapa, você vai executar um aplicativo de amostra em Node.js que atua como um site de compras e um servidor de back-end.

clone o repositório de exemplo

O repositório google-pay/wallet-web-codelab contém um projeto de amostra baseado em Node.js e diferentes arquivos de script que imitam um servidor de back-end usado para provisionar classes e objetos de cartão. Edite esses dados para incluir o botão Adicionar à Carteira do Google na tela de detalhes do produto.

  1. Clone o repositório na estação de trabalho local
    git clone https://github.com/google-pay/wallet-web-codelab.git

Instalar dependências do projeto

  1. Abra o repositório clonado no seu terminal ou prompt de linha de comando.
  2. Navegue até o diretório web. Esse é o app que você modificará no restante deste codelab.
    cd web
  3. Instale as dependências do Node.js
    npm install .
  4. Inicie o app
    node app.js
  5. Abra o aplicativo em execução em http://localhost:3000

Um exemplo de app da Web com um campo para inserir um endereço de e-mail e um botão "Criar cartão"

Se você inserir seu endereço de e-mail e selecionar Criar cartão, nada acontecerá. Nas próximas etapas, você vai configurar o app para criar uma nova classe e um objeto de cartão.

4. Criar uma classe de cartão genérico

Nesta etapa, você criará a classe de base do cartão. Sempre que um novo cartão é criado para um usuário, ele herda as propriedades definidas na classe de cartão.

A classe de cartão que você vai criar neste codelab usa a flexibilidade dos cartões genéricos para criar um objeto que funciona como um selo de identidade e um rastreador de pontos de desafio. Quando um objeto de cartão é criado com base nessa classe, ele se parece com o gráfico a seguir.

As classes de cartão podem ser criadas diretamente na página do Google Pay e Console da Carteira ou usando a API Google Wallet. Neste codelab, você vai criar a classe de cartão genérico usando a API. Isso segue o processo que um servidor de back-end privado usaria para criar classes de cartão.

  1. Abra o arquivo web/app.js.
  2. Substitua o valor de issuerId pelo seu ID de emissor do Google Pay e Console da Carteira
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. Localize a função createPassClass
  4. Na função, crie um cliente HTTP autenticado e use a API Google Wallet para criar uma nova classe de cartão
    // TODO: Create a Generic pass class
let genericClass = {
  'id': `${classId}`,
  'classTemplateInfo': {
    'cardTemplateOverride': {
      'cardRowTemplateInfos': [
        {
          'twoItems': {
            'startItem': {
              'firstValue': {
                'fields': [
                  {
                    'fieldPath': 'object.textModulesData["points"]'
                  }
                ]
              }
            },
            'endItem': {
              'firstValue': {
                'fields': [
                  {
                    'fieldPath': 'object.textModulesData["contacts"]'
                  }
                ]
              }
            }
          }
        }
      ]
    },
    'detailsTemplateOverride': {
      'detailsItemInfos': [
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': 'class.imageModulesData["event_banner"]'
                }
              ]
            }
          }
        },
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': 'class.textModulesData["game_overview"]'
                }
              ]
            }
          }
        },
        {
          'item': {
            'firstValue': {
              'fields': [
                {
                  'fieldPath': 'class.linksModuleData.uris["official_site"]'
                }
              ]
            }
          }
        }
      ]
    }
  },
  'imageModulesData': [
    {
      'mainImage': {
        'sourceUri': {
          'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-2021-card.png'
        },
        'contentDescription': {
          'defaultValue': {
            'language': 'en-US',
            'value': 'Google I/O 2022 Banner'
          }
        }
      },
      'id': 'event_banner'
    }
  ],
  'textModulesData': [
    {
      'header': 'Gather points meeting new people at Google I/O',
      'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.',
      'id': 'game_overview'
    }
  ],
  'linksModuleData': {
    'uris': [
      {
        'uri': 'https://io.google/2022/',
        'description': 'Official I/O \'22 Site',
        'id': 'official_site'
      }
    ]
  }
};

let response;
try {
  // Check if the class exists already
  response = await httpClient.request({
    url: `${baseUrl}/genericClass/${classId}`,
    method: 'GET'
  });

  console.log('Class already exists');
  console.log(response);
} catch (err) {
  if (err.response && err.response.status === 404) {
    // Class does not exist
    // Create it now
    response = await httpClient.request({
      url: `${baseUrl}/genericClass`,
      method: 'POST',
      data: genericClass
    });

    console.log('Class insert response');
    console.log(response);
  } else {
    // Something else went wrong
    console.log(err);
    res.send('Something went wrong...check the console logs!');
  }
}

Quando seu código é executado, ele cria uma nova classe de cartão e gera o ID da classe. O ID da classe é composto pelo ID do emissor seguido por um sufixo definido pelo desenvolvedor. Nesse caso, o sufixo está definido como codelab_class (o ID da classe seria semelhante a 1234123412341234123.codelab_class). Os registros de saída também incluem a resposta da API Google Wallet.

5. Criar um objeto de cartão genérico

Nesta etapa, você vai configurar seu app Node.js para criar um objeto de cartão genérico usando a classe criada anteriormente. Existem dois fluxos para criar objetos de cartão para os usuários.

Criar o objeto de cartão no servidor de back-end

Nessa abordagem, o objeto de cartão é criado em um servidor de back-end e retornado ao app cliente como um JWT assinado. Isso é mais adequado para casos em que a adoção pelo usuário é alta, porque garante que o objeto exista antes de o usuário tentar adicioná-lo à carteira.

Criar o objeto do cartão quando o usuário o adiciona à carteira

Nessa abordagem, o objeto de cartão é definido e codificado como um JWT assinado no servidor de back-end. Um botão Adicionar à Carteira do Google é renderizado no app cliente que referencia o JWT. Quando o usuário seleciona o botão, o JWT é usado para criar o objeto de cartão. Isso é mais adequado para casos em que a adoção pelo usuário é variável ou desconhecida, porque impede que objetos de cartão sejam criados e não usados. Essa abordagem será usada no codelab.

  1. Abra o arquivo web/app.js.
  2. Localize a função createPassObject
  3. Na função, defina um novo objeto de cartão para o usuário
    // TODO: Create a new Generic pass for the user
let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`;
let objectId = `${issuerId}.${objectSuffix}`;

let genericObject = {
  'id': `${objectId}`,
  'classId': classId,
  'genericType': 'GENERIC_TYPE_UNSPECIFIED',
  'hexBackgroundColor': '#4285f4',
  'logo': {
    'sourceUri': {
      'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg'
    }
  },
  'cardTitle': {
    'defaultValue': {
      'language': 'en',
      'value': 'Google I/O \'22'
    }
  },
  'subheader': {
    'defaultValue': {
      'language': 'en',
      'value': 'Attendee'
    }
  },
  'header': {
    'defaultValue': {
      'language': 'en',
      'value': 'Alex McJacobs'
    }
  },
  'barcode': {
    'type': 'QR_CODE',
    'value': `${objectId}`
  },
  'heroImage': {
    'sourceUri': {
      'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg'
    }
  },
  'textModulesData': [
    {
      'header': 'POINTS',
      'body': '1234',
      'id': 'points'
    },
    {
      'header': 'CONTACTS',
      'body': '20',
      'id': 'contacts'
    }
  ]
};

// TODO: Create the signed JWT and link
res.send("Form submitted!");

Se você recarregar o app, inserir seu endereço de e-mail e enviar o formulário, nenhuma resposta será exibida. O objeto de cartão está sendo definido pelo aplicativo de back-end, mas nenhuma saída está sendo retornada. Em seguida, você vai transformar o cartão em um link Adicionar à Carteira do Google.

6. Crie um Botão "Adicionar à Carteira do Google"

Na etapa final, você vai criar um JWT assinado e retornar um link que pode ser usado no botão Adicionar à Carteira do Google. Quando o usuário selecionar o botão, ele vai receber uma solicitação para salvar o cartão na carteira.

  1. Crie as declarações JWT, codifique-as usando a chave privada da conta de serviço e retorne um botão Adicionar à Carteira do Google com o link incorporado
    // TODO: Create the signed JWT and link
const claims = {
  iss: credentials.client_email,
  aud: 'google',
  origins: [],
  typ: 'savetowallet',
  payload: {
    genericObjects: [
      genericObject
    ]
  }
};

const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' });
const saveUrl = `https://pay.google.com/gp/v/save/${token}`;

res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`);
  2. Atualize o app em execução no navegador
  3. Insira seu endereço de e-mail no formulário e selecione Criar cartão.
  4. Quando ele aparecer, selecione o botão Adicionar à Carteira do Google.

O botão &quot;Adicionar à Carteira do Google&quot; é renderizado no front-end do app.

7. Parabéns

Exemplo de objeto de cartão genérico

Parabéns! Você integrou a API Google Wallet na Web.

Saiba mais

Confira uma integração completa no repositório google-pay/wallet-web-codelab do GitHub.

Criar cartões e solicitar acesso de produção

Quando estiver tudo pronto para emitir seus próprios cartões em produção, acesse a página do Google Pay e Console da Carteira para solicitar o acesso de produção.

Consulte os Pré-requisitos da API Web para saber mais.