Crea pases en la Web con la API de la Billetera de Google

1. Introducción

Descripción general

La API de la Billetera de Google te permite interactuar con los usuarios a través de varios tipos de pases: tarjetas de lealtad, ofertas, tarjetas de regalo, entradas para eventos, boletos de transporte público, tarjetas de embarque y mucho más. Cada tipo de pase, o clase de pase, incluye campos y funciones específicos para el caso de uso que mejoran la experiencia del usuario.

Sin embargo, es posible que no se adapten a todos los casos de uso. Para crear una experiencia más personalizada, puedes usar el tipo de pase genérico. Estos son algunos ejemplos de casos de uso para el tipo de pase genérico:

  • Pases de estacionamiento
  • Tarjetas de membresía de biblioteca
  • Cupones de saldo
  • Tarjetas de membresía de gimnasio
  • Reservas

Puedes usar pases genéricos para cualquier caso de uso que se pueda presentar con lo siguiente:

  • Hasta tres filas de información
  • Gráfico de código de barras (opcional)
  • (Opcional) Sección de detalles

Un ejemplo de pase de la Billetera de Google para un evento de conferencia

Para obtener más información sobre la API de la Billetera de Google o sobre cómo agregar un botón Agregar a la Billetera de Google a una página web, consulta la documentación para desarrolladores de la Billetera de Google.

Clases y objetos de pases

La API de la Billetera de Google expone métodos para crear lo siguiente:

Tipo

Descripción

Clase de pase

Es una plantilla para un objeto de pase individual. Contiene información común a todos los objetos de pase que pertenecen a esta clase.

Objeto de pase

Es una instancia de una clase de pase que es única para un ID de usuario.

Acerca de este codelab

En este codelab, completarás las siguientes tareas.

  1. Crea una nueva cuenta de entidad emisora en el modo de demostración
  2. Crea una cuenta de servicio para emitir pases
  3. Crea una nueva clase de pase genérico
  4. Crea un objeto de pase nuevo
  5. Crea un botón Agregar a la Billetera de Google para guardar un pase
  6. Muestra el botón en tu página web
  7. Cómo controlar el resultado del guardado del pase

Requisitos previos

Objetivos

Después de completar este codelab, podrás hacer lo siguiente:

  • Crea objetos de pases con la Billetera de Google
  • Crea un botón de Agregar a la Billetera de Google

Asistencia

Si te quedas atascado en algún punto del codelab, el repositorio de GitHub google-pay/wallet-web-codelab contiene una solución completa para que la consultes.

2. Configuración

En este paso, crearás una cuenta de entidad emisora en modo de demostración. Esto te permitirá crear clases y objetos de pases que se pueden agregar a las billeteras de los usuarios. A continuación, crearás un proyecto y una cuenta de servicio de Google Cloud. Se usarán para crear de forma programática clases y objetos de pases de la misma manera que un servidor de backend. Por último, autorizarás a la cuenta de servicio de Google Cloud para administrar pases en tu cuenta de emisor de la Billetera de Google.

Regístrate para obtener una cuenta de entidad emisora de la Billetera de Google

Se necesita una cuenta de emisor para crear y distribuir pases para la Billetera de Google. Puedes registrarte en la Consola de Google Pay y la Billetera. Inicialmente, tendrás acceso para crear pases en modo de demostración. Esto significa que solo los usuarios de prueba específicos podrán agregar los pases que crees. Los usuarios de prueba se pueden administrar en la Consola de Google Pay y la Billetera.

Para obtener más información sobre el modo de demostración, consulta los requisitos previos de pases genéricos.

  1. Abre la Consola de Google Pay y la Billetera de Google.
  2. Sigue las instrucciones en pantalla para crear una cuenta de emisor.
  3. Selecciona Google Wallet API.
  4. Confirma que comprendes las condiciones del servicio y la política de privacidad
  5. Copia el valor del ID del emisor en un editor de texto o en otra ubicación.
  6. En la pestaña Administrar, selecciona Configurar cuentas de prueba.
  7. Agrega las direcciones de correo electrónico que usarás en este codelab

Habilita la API de la Billetera de Google

  1. Accede a la consola de Google Cloud.
  2. Si aún no tienes un proyecto de Google Cloud, crea uno ahora (consulta Crea y administra proyectos para obtener más información).
  3. Habilita la API de Google Wallet (también conocida como API de Google Pay para Passes) para tu proyecto.

Cree una cuenta de servicio y una clave

Se necesitan una cuenta de servicio y una clave de cuenta de servicio para llamar a la API de Google Wallet. La cuenta de servicio es la identidad que llama a la API de Google Wallet. La clave de la cuenta de servicio contiene una clave privada que identifica tu aplicación como la cuenta de servicio. Esta clave es sensible, por lo que debes mantenerla confidencial.

Crea una cuenta de servicio

  1. En la consola de Google Cloud, abre Cuentas de servicio.
  2. Ingresa un nombre, un ID y una descripción para tu cuenta de servicio.
  3. Selecciona CREAR Y CONTINUAR.
  4. Selecciona LISTO.

Crea una clave de cuenta de servicio

  1. Selecciona tu cuenta de servicio
  2. Selecciona el menú KEYS.
  3. Selecciona AGREGAR CLAVE y, luego, Crear clave nueva.
  4. Selecciona el tipo de clave JSON.
  5. Selecciona CREAR.

Se te solicitará que guardes el archivo de clave en tu estación de trabajo local. Asegúrate de recordar su ubicación.

Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

Los SDKs de Google usan la variable de entorno GOOGLE_APPLICATION_CREDENTIALS para autenticarse como una cuenta de servicio y acceder a diferentes APIs de un proyecto de Google Cloud.

  1. Sigue las instrucciones de la documentación sobre las claves de cuentas de servicio de Google Cloud para establecer la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.
  2. Verifica que la variable de entorno esté configurada en una nueva sesión de terminal (macOS/Linux) o de línea de comandos (Windows) (es posible que debas iniciar una sesión nueva si ya tienes una abierta).
    echo $GOOGLE_APPLICATION_CREDENTIALS

Autoriza la cuenta de servicio

Por último, deberás autorizar a la cuenta de servicio para que administre los pases de la Billetera de Google.

  1. Abre la Consola de Google Pay y la Billetera de Google.
  2. Selecciona Usuarios.
  3. Selecciona Invitar a un usuario.
  4. Ingresa la dirección de correo electrónico de la cuenta de servicio (p. ej., test-svc@myproject.iam.gserviceaccount.com).
  5. Selecciona Desarrollador o Administrador en el menú desplegable Nivel de acceso.
  6. Selecciona Invitar.

3. Inicia la app de muestra de Node.js

Duración: 10:00

En este paso, ejecutarás una aplicación de Node.js de ejemplo que actúa como un sitio web de compras y un servidor de backend.

Clona el repositorio de muestra

El repositorio google-pay/wallet-web-codelab contiene un proyecto de muestra basado en Node.js y diferentes archivos de secuencia de comandos que imitan un servidor de backend que se usa para aprovisionar clases y objetos de pases. Editarás estos elementos para incluir un botón Agregar a la Billetera de Google en la pantalla de detalles del producto.

  1. Clona el repositorio en tu estación de trabajo local
    git clone https://github.com/google-pay/wallet-web-codelab.git

Instala las dependencias del proyecto

  1. Abre el repositorio clonado en la terminal o el símbolo del sistema.
  2. Navega al directorio web (esta es la app que modificarás en el resto de este codelab).
    cd web
  3. Instala las dependencias de Node.js
    npm install .
  4. Inicia la app
    node app.js
  5. Abre la app que se ejecuta en http://localhost:3000.

Una app web de ejemplo con un campo para ingresar una dirección de correo electrónico y un botón Crear pase

Si ingresas tu dirección de correo electrónico y seleccionas Crear pase, no sucederá nada. En los próximos pasos, configurarás la app para crear una nueva clase y un nuevo objeto de pase.

4. Crea una clase de pase genérico

En este paso, crearás la clase base para tu pase. Cada vez que se cree un pase nuevo para un usuario, este heredará las propiedades definidas en la clase de pase.

La clase de pase que crearás durante este codelab utiliza la flexibilidad de los pases genéricos para crear un objeto que funcione como una insignia de identidad y un registro de puntos de desafío. Cuando se cree un objeto de pase a partir de esta clase, se verá como el siguiente gráfico.

Las clases de pases se pueden crear directamente en Google Pay & Wallet Console o con la API de Google Wallet. En este codelab, crearás la clase de pase genérico con la API. Esto sigue el proceso que usaría un servidor backend privado para crear clases de pases.

  1. Abre el archivo web/app.js.
  2. Reemplaza el valor de issuerId por el ID del emisor de la Consola de Google Pay y la Billetera de Google.
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. Ubica la función createPassClass
  4. En la función, crea un cliente HTTP autenticado y usa la API de Google Wallet para crear una nueva clase de pase.
    // 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!');
  }
}

Cuando se ejecute tu código, se creará una nueva clase de pase y se mostrará el ID de la clase. El ID de clase se compone del ID del emisor seguido de un sufijo definido por el desarrollador. En este caso, el sufijo se establece en codelab_class (el ID de la clase se vería similar a 1234123412341234123.codelab_class). Los registros de salida también incluirán la respuesta de la API de Google Wallet.

5. Crea un objeto de pase genérico

En este paso, configurarás tu app de Node.js para crear un objeto de pase genérico con la clase que creaste anteriormente. Existen dos flujos para crear objetos de pases para los usuarios.

Crea el objeto de pase en el servidor de backend

En este enfoque, el objeto de pase se crea en un servidor de backend y se devuelve a la app cliente como un JWT firmado. Esto es más adecuado para los casos en los que la adopción por parte del usuario es alta, ya que garantiza que el objeto exista antes de que el usuario intente agregarlo a su billetera.

Crea el objeto de pase cuando el usuario lo agregue a su billetera

En este enfoque, el objeto de pase se define y codifica en un JWT firmado en el servidor de backend. Luego, se renderiza un botón Agregar a la Billetera de Google en la app de cliente que hace referencia al JWT. Cuando el usuario selecciona el botón, se usa el JWT para crear el objeto de pase. Esto es más adecuado para los casos en los que la adopción por parte del usuario es variable o desconocida, ya que evita que se creen objetos de pase que no se usen. Este enfoque se usará en el codelab.

  1. Abre el archivo web/app.js.
  2. Ubica la función createPassObject
  3. En la función, define un nuevo objeto de pase para tu usuario.
    // 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!");

Si vuelves a cargar la app, ingresas tu dirección de correo electrónico y envías el formulario, no verás ningún resultado. La aplicación de backend está definiendo el objeto de pase, pero no se devuelve ningún resultado. A continuación, convertirás el pase en un vínculo de Agregar a la Billetera de Google.

6. Crea un botón de Agregar a la Billetera de Google

En el último paso, crearás un JWT firmado y devolverás un vínculo que se puede usar en el botón Agregar a la Billetera de Google. Cuando el usuario seleccione el botón, se le pedirá que guarde el pase en su billetera.

  1. Crea las declaraciones del JWT, codifícalas con la clave privada de la cuenta de servicio y devuelve un botón Agregar a la Billetera de Google con el vínculo 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. Vuelve a cargar la app que se ejecuta en tu navegador.
  3. Ingresa tu dirección de correo electrónico en el formulario y selecciona Crear pase.
  4. Cuando aparezca, selecciona el botón Agregar a la Billetera de Google.

El botón Agregar a la Billetera de Google se renderiza correctamente en el frontend de la app.

7. Felicitaciones

Ejemplo de un objeto de pase genérico

Felicitaciones, integraste correctamente la API de la Billetera de Google en la Web.

Más información

Observa una integración completa en el repositorio de GitHub google-pay/wallet-web-codelab.

Crea pases y solicita acceso de producción

Cuando tengas todo listo para emitir tus propios pases en producción, ve a Google Pay & Wallet Console para solicitar acceso a producción.

Consulta los requisitos previos de la API web para obtener más información.