Creare tessere sul web utilizzando l'API Google Wallet

1. Introduzione

Panoramica

L'API Google Wallet ti consente di interagire con gli utenti tramite vari tipi di tessere: carte fedeltà, offerte, carte regalo, biglietti per eventi, biglietti del trasporto pubblico, carte d'imbarco e altro ancora. Ogni tipo di tessera o classe di superamento include funzionalità e campi specifici per i casi d'uso che migliorano l'esperienza utente.

Tuttavia, potrebbero non essere adatti a tutti i casi d'uso. Per creare un'esperienza più personalizzata, puoi utilizzare il tipo di tessera generica. Ecco alcuni casi d'uso di esempio per il tipo di tessera generica:

  • Tessere per il parcheggio
  • Tessere della biblioteca
  • Coupon con valore memorizzato
  • Tessere della palestra
  • Prenotazioni

Puoi utilizzare tessere generiche per qualsiasi caso d'uso che possa essere presentato con:

  • Fino a tre righe di informazioni
  • (Facoltativo) Immagine del codice a barre
  • (Facoltativo) Sezione dei dettagli

Un pass di Google Wallet di esempio per una conferenza

Per ulteriori informazioni sull'API Google Wallet o sull'aggiunta di un pulsante Aggiungi a Google Wallet a una pagina web, consulta la documentazione per gli sviluppatori di Google Wallet.

Classi e oggetti di superamento

L'API Google Wallet espone i metodi per creare quanto segue:

Tipo

Descrizione

Classe pass

Un modello per un singolo oggetto pass. Contiene informazioni comuni a tutti gli oggetti pass che appartengono a questa classe.

Oggetto pass

Un'istanza di una classe pass univoca per un ID utente.

Informazioni su questo codelab

In questo codelab, completerai le attività seguenti.

  1. Crea un nuovo account emittente in modalità demo
  2. Crea un account di servizio per l'emissione delle tessere
  3. Crea una nuova classe pass generica
  4. Crea un nuovo oggetto pass
  5. Crea un pulsante Aggiungi a Google Wallet per salvare una tessera
  6. Visualizza il pulsante nella pagina web
  7. Gestire il risultato del salvataggio della tessera

Prerequisiti

Obiettivi

Dopo aver completato questo codelab, sarai in grado di:

  • Creare oggetti tessere utilizzando Google Wallet
  • Crea un pulsante Aggiungi a Google Wallet

Assistenza

Se ti blocchi in qualsiasi momento del codelab, il repository GitHub di google-pay/wallet-web-codelab contiene una soluzione completa come riferimento.

2. Configurazione

In questo passaggio, creerai un account emittente in modalità demo. In questo modo potrai creare classi di tessere e oggetti che possono essere aggiunti ai portafogli degli utenti. Ora creerai un progetto Google Cloud e un account di servizio. Verranno utilizzati per creare in modo programmatico classi di passaggio e oggetti, come per un server di backend. Infine, autorizzerai l'account di servizio Google Cloud a gestire le tessere nel tuo account emittente Google Wallet.

Creare un account emittente Google Wallet

Per creare e distribuire le tessere per Google Wallet è necessario un account emittente. Puoi registrarti utilizzando la funzionalità Google Pay & Console Wallet. Inizialmente, potrai creare tessere in modalità demo. Ciò significa che solo specifici utenti di test potranno aggiungere le tessere che crei. Gli utenti di prova possono essere gestiti in Google Pay e Console Wallet.

Per ulteriori informazioni sulla modalità demo, consulta i prerequisiti per il superamento generico.

  1. Apri l'app Google Pay e Console di Wallet
  2. Segui le istruzioni sullo schermo per creare un account emittente
  3. Seleziona API Google Wallet
  4. Conferma di aver compreso i Termini di servizio e le Norme sulla privacy
  5. Copia il valore Issuer ID (ID emittente) in un editor di testo o in un'altra posizione.
  6. Nella scheda Gestisci, seleziona Configura account di prova.
  7. Aggiungi gli indirizzi email che utilizzerai in questo codelab

Abilitare l'API Google Wallet

  1. Accedi alla console Google Cloud.
  2. Se non hai ancora un progetto Google Cloud, creane uno ora. Per saperne di più, consulta Creazione e gestione dei progetti.
  3. Attiva l'API Google Wallet (nota anche come API Google Pay for Passes) per il tuo progetto

Crea un account di servizio e una chiave

Per chiamare l'API Google Wallet sono necessari un account di servizio e una chiave dell'account di servizio. L'account di servizio è l'identità che chiama l'API Google Wallet. La chiave dell'account di servizio contiene una chiave privata che identifica l'applicazione come account di servizio. Questa chiave è sensibile, quindi mantienila riservata.

Crea un account di servizio

  1. Nella console Google Cloud, apri Account di servizio
  2. Inserisci un nome, un ID e una descrizione per il tuo account di servizio
  3. Seleziona CREA E CONTINUA.
  4. Seleziona FINE

Crea una chiave dell'account di servizio

  1. Seleziona il tuo account di servizio
  2. Seleziona il menu KEYS.
  3. Seleziona AGGIUNGI CHIAVE, quindi Crea nuova chiave.
  4. Seleziona il tipo di chiave JSON
  5. Seleziona CREA

Ti verrà chiesto di salvare il file della chiave sulla workstation locale. Assicurati di memorizzarne la posizione.

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS

La variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS viene utilizzata dagli SDK Google per eseguire l'autenticazione come account di servizio e accedere a diverse API per un progetto Google Cloud.

  1. Segui le istruzioni nella documentazione relativa alle chiavi dell'account di servizio Google Cloud per impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.
  2. Verifica che la variabile di ambiente sia impostata in una nuova sessione di terminale (MacOS/Linux) o della riga di comando (Windows) (potrebbe essere necessario avviare una nuova sessione se ne hai già aperta una)
    echo $GOOGLE_APPLICATION_CREDENTIALS

Autorizza l'account di servizio

Infine, dovrai autorizzare l'account di servizio a gestire le tessere di Google Wallet.

  1. Apri l'app Google Pay e Console di Wallet
  2. Seleziona Utenti.
  3. Seleziona Invita un utente.
  4. Inserisci l'indirizzo email dell'account di servizio (ad es. test-svc@myproject.iam.gserviceaccount.com)
  5. Seleziona Sviluppatore o Amministratore dal menu a discesa Livello di accesso.
  6. Seleziona Invita

3. avvia l'app Node.js di esempio

Durata 10:00

In questo passaggio, eseguirai un'applicazione Node.js di esempio che funge da sito web per gli acquisti e server di backend.

clona il repository di esempio

Il repository google-pay/wallet-web-codelab contiene un progetto di esempio basato su Node.js e diversi file di script che imitano un server di backend utilizzato per il provisioning di classi delle tessere e oggetti. Li modificherai in modo da includere un pulsante Aggiungi a Google Wallet nella schermata dei dettagli del prodotto.

  1. Clona il repository sulla workstation locale
    git clone https://github.com/google-pay/wallet-web-codelab.git

Installa le dipendenze del progetto

  1. Apri il repository clonato nel terminale o nel prompt della riga di comando.
  2. Vai alla directory web (questa è l'app che modificherai nel resto di questo codelab)
    cd web
  3. Installa le dipendenze Node.js
    npm install .
  4. Avvia l'app
    node app.js
  5. Apri l'app in esecuzione su http://localhost:3000

Un'app web di esempio con un campo per inserire un indirizzo email e un pulsante Crea tessera

Se inserisci il tuo indirizzo email e selezioni Crea tessera, non succederà nulla. Nei passaggi successivi, configurerai l'app per creare una nuova classe pass e un nuovo oggetto.

4. Creare una classe pass generica

In questo passaggio creerai la classe base per la tua tessera. Ogni volta che viene creata una nuova tessera per un utente, quest'ultima erediterà le proprietà definite nella classe della tessera.

La classe della tessera che creerai durante questo codelab utilizza la flessibilità delle tessere generiche per creare un oggetto che funge sia da badge d'identità sia da tracker dei punti sfida. Quando viene creato un oggetto pass da questa classe, l'oggetto avrà l'aspetto seguente.

Le classi di pass possono essere create direttamente in Google Pay e Console Wallet o utilizzando l'API Google Wallet. In questo codelab, creerai la classe pass generico utilizzando l'API. Questa operazione segue il processo che un server di backend privato utilizzerebbe per creare classi di accesso.

  1. Apri il file web/app.js
  2. Sostituisci il valore issuerId con il tuo ID emittente indicato in Google Pay e Console di Wallet
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. Individuare la funzione createPassClass
  4. Nella funzione, crea un client HTTP autenticato e utilizza l'API Google Wallet per creare una nuova classe di tessera
    // 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 viene eseguito, il codice crea una nuova classe pass e restituisce l'ID classe. L'ID classe è composto dall'ID emittente seguito da un suffisso definito dallo sviluppatore. In questo caso, il suffisso è impostato su codelab_class (l'ID classe sarà simile a 1234123412341234123.codelab_class). I log di output includeranno anche la risposta dell'API Google Wallet.

5. Creare un oggetto pass generico

In questo passaggio configurerai l'app Node.js per creare un oggetto pass generico utilizzando la classe creata in precedenza. Esistono due flussi per la creazione di oggetti pass per gli utenti.

Crea l'oggetto pass sul server di backend

In questo approccio, l'oggetto pass viene creato su un server di backend e restituito all'app client come un JWT firmato. Questa opzione è più adatta nei casi in cui l'adozione da parte dell'utente è elevata, in quanto garantisce l'esistenza dell'oggetto prima che l'utente provi ad aggiungerlo al proprio portafoglio.

Crea l'oggetto pass quando l'utente lo aggiunge al proprio Wallet

In questo approccio, l'oggetto pass viene definito e codificato in un JWT firmato sul server di backend. Nell'app client viene visualizzato un pulsante Aggiungi a Google Wallet che fa riferimento al JWT. Quando l'utente seleziona il pulsante, il JWT viene utilizzato per creare l'oggetto pass. Questa opzione è più adatta nei casi in cui l'adozione da parte dell'utente è variabile o sconosciuta, in quanto impedisce la creazione e il mancato utilizzo di oggetti Trasmetti. Questo approccio verrà utilizzato nel codelab.

  1. Apri il file web/app.js
  2. Individuare la funzione createPassObject
  3. Nella funzione, definisci un nuovo oggetto pass per l'utente
    // 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 ricarichi l'app, inserisci il tuo indirizzo email e invii il modulo, non verrà visualizzato alcun output. L'oggetto pass è in fase di definizione dall'applicazione di backend, ma non viene restituito alcun output. Successivamente, trasforma la tessera in un link Aggiungi a Google Wallet.

6. Crea un Pulsante Aggiungi a Google Wallet

Per il passaggio finale, dovrai creare un JWT firmato e restituire un link che può essere utilizzato nel pulsante Aggiungi a Google Wallet. Quando l'utente seleziona il pulsante, gli verrà chiesto di salvare la tessera nel portafoglio.

  1. Creare le rivendicazioni JWT, codificarle utilizzando la chiave privata dell'account di servizio e restituire un pulsante Aggiungi a Google Wallet con il link incorporato
    // 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. Ricarica l'app in esecuzione nel browser
  3. Inserisci il tuo indirizzo email nel modulo e seleziona Crea tessera
  4. Quando viene visualizzato, seleziona il pulsante Aggiungi a Google Wallet.

Il pulsante Aggiungi a Google Wallet è stato visualizzato correttamente sul frontend dell&#39;app

7. Complimenti

Esempio di oggetto pass generico

Congratulazioni, hai completato l'integrazione dell'API Google Wallet sul Web.

Scopri di più

Dai un'occhiata a un'integrazione completa nel repository GitHub google-pay/wallet-web-codelab.

Crea tessere e richiedi l'accesso in produzione

Quando è tutto pronto per emettere i tuoi pass in produzione, vai alla sezione Google Pay e Console Wallet per richiedere l'accesso in produzione.

Per scoprire di più, consulta la pagina Prerequisiti delle API web.