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, viene con campos y funciones específicos de casos de uso para mejorar 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 en el que se pueda presentar lo siguiente:

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

Ejemplo de un pase de la Billetera de Google para un evento de una conferencia

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

Pasa clases y objetos

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

Tipo

Descripción

Clase de pase

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

Pasar objeto

Una instancia de una clase de pase exclusiva 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. Cómo crear una nueva clase de pase genérico
  4. Crea un nuevo objeto Pass
  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 de guardar el 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 Agregar a la Billetera de Google

Asistencia

Si en algún momento del codelab no puedes avanzar, el repositorio de GitHub google-pay/wallet-web-codelab contiene una solución completa a modo de referencia.

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 de Google Cloud y una cuenta de servicio. Estos se usarán para crear de manera 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 que administre pases en la cuenta de la entidad emisora de la Billetera de Google.

Regístrate para obtener una cuenta de entidad emisora de Google Wallet

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

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

  1. Abre la tarjeta Google Pay & Consola de la Billetera
  2. Sigue las instrucciones en pantalla para crear una cuenta de entidad emisora
  3. Selecciona API de la Billetera de Google.
  4. Confirma que comprendes las Condiciones del Servicio y la Política de Privacidad
  5. Copia el valor del ID de entidad emisora 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. Habilitar la API de la Billetera de Google (también conocida como API de Google Pay for Passes) en 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 la Billetera de Google. La cuenta de servicio es la identidad que llama a la API de la Billetera de Google. Esta 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 claves 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 para un proyecto de Google Cloud.

  1. Sigue las instrucciones en la documentación de claves de cuenta de servicio de Google Cloud para configurar 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 línea de comandos (Windows) (es posible que debas iniciar una nueva sesión si ya tienes una abierta).
    echo $GOOGLE_APPLICATION_CREDENTIALS

Autoriza la cuenta de servicio

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

  1. Abre la tarjeta Google Pay & Consola de la Billetera
  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. En el menú desplegable Nivel de acceso, selecciona Desarrollador o Administrador.
  6. Selecciona Invitar.

3. Inicia la app de Node.js de muestra

Duración 10:00

En este paso, ejecutarás una aplicación de muestra de Node.js 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 objetos y clases de pases. Las editarás para incluir el 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 tu terminal o ventana de línea de comandos
  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 clase y un objeto de pase nuevos.

4. Cómo crear 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.

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

Las clases de pases pueden crearse directamente en las Cuentas de Google Pay y Consola de la Billetera o la API de la Billetera de Google. En este codelab, crearás la clase de pase genérico con la API. Esto sigue el proceso que usaría un servidor de backend privado para crear clases de pases.

  1. Abre el archivo web/app.js.
  2. Reemplaza el valor de issuerId por el ID de entidad emisora de la tarjeta de Google Pay. Consola de la Billetera
    // 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 la Billetera de Google 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 clase. El ID de clase se compone del ID de la entidad emisora seguido de un sufijo definido por el desarrollador. En este caso, el sufijo se establece en codelab_class (el ID de clase sería similar a 1234123412341234123.codelab_class). Los registros de salida también incluirán la respuesta de la API de la Billetera de Google.

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 pase para usuarios.

Crea el objeto pass en el servidor de backend

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

Crea el objeto Pass cuando el usuario lo agregue a su billetera

En este enfoque, el objeto pass se define y codifica en un JWT firmado en el servidor de backend. Luego, se renderiza un botón Add to Google Wallet en la app cliente que hace referencia al JWT. Cuando el usuario selecciona el botón, el JWT se usa para crear el objeto Pass. Esto es más adecuado para los casos en los que la adopción del usuario es variable o desconocida, ya que evita que se creen y no se usen objetos de pase. 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 define el objeto pass, pero no se muestran resultados. A continuación, convertirás el pase en un vínculo de Agregar a la Billetera de Google.

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

Para el paso final, 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 reclamaciones de JWT, codifícalas con la clave privada de la cuenta de servicio y muestra el 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 el botón, 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

Consulta 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 la página Google Pay y Consola de la Billetera para solicitar acceso a producción.

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