Creare tessere sul web utilizzando l'API Google Wallet

Creare tessere sul web utilizzando l'API Google Wallet

Informazioni su questo codelab

subjectUltimo aggiornamento: gen 19, 2023
account_circleScritto da: Nick Alteen

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 per il trasporto pubblico, carte d'imbarco e altro ancora. Ogni tipo di tessera, o classe di tessera, è dotato di campi e funzionalità specifici per i casi d'uso per migliorare 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 generico. Ecco alcuni casi d'uso di esempio per il tipo di documento generico:

  • Tessere per il parcheggio
  • Tessere della biblioteca
  • Buoni con valore memorizzato
  • Tessere di abbonamento a palestre
  • Prenotazioni

Puoi utilizzare documenti generici per qualsiasi caso d'uso che può essere presentato con:

  • Fino a tre righe di informazioni
  • (Facoltativo) Grafica del codice a barre
  • (Facoltativo) Sezione Dettagli

Una tessera Google Wallet di esempio per un evento di una conferenza

Per saperne di più 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.

Passare classi e oggetti

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

Tipo

Descrizione

Passare il corso

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

Passa oggetto

Un'istanza di una classe di documenti che è univoca per un ID utente.

Informazioni su questo codelab

In questo codelab completerai le seguenti attività.

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

Prerequisiti

Obiettivi

Dopo aver completato questo codelab, potrai:

  • Creare oggetti pass utilizzando Google Wallet
  • Creare un pulsante Aggiungi a Google Wallet

Assistenza

Se non riesci a procedere in un determinato punto del codelab, il repository GitHub google-pay/wallet-web-codelab contiene una soluzione completa da utilizzare come riferimento.

2. Configurazione

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

Registrati per un account emittente Google Wallet

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

Per ulteriori informazioni sulla modalità demo, consulta i prerequisiti per i permessi generici.

  1. Apri la Console di Google Pay e 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

Abilita l'API Google Wallet

  1. Accedi alla console Google Cloud.
  2. Se non hai ancora un progetto Google Cloud, creane uno ora (per ulteriori informazioni, consulta Creare e gestire i progetti).
  3. Abilita l'API Google Wallet (indicata anche come API Google Pay for Passes) per il tuo progetto

Creare 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 del service account contiene una chiave privata che identifica la tua applicazione come service account. 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 l'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 nella tua workstation locale. Assicurati di ricordare la posizione.

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS

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

  1. Segui le istruzioni riportate 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 riga di comando (Windows) (potrebbe essere necessario avviare una nuova sessione se ne hai già una aperta).
    echo $GOOGLE_APPLICATION_CREDENTIALS

Autorizza l'account di servizio

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

  1. Apri la Console di Google Pay e 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 di shopping 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 simulano un server di backend utilizzato per il provisioning di classi e oggetti delle tessere. Dovrai modificarli in modo da includere un pulsante Aggiungi a Google Wallet in una schermata dei dettagli del prodotto.

  1. Clona il repository nella tua 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 dei comandi
  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 pass

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

4. Crea una classe di documenti generici

In questo passaggio creerai la classe di base per la tessera. Ogni volta che viene creato un nuovo pass per un utente, questo eredita le proprietà definite nella classe pass.

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

Le classi di pass possono essere create direttamente nella Console di Google Pay e Wallet o utilizzando l'API Google Wallet. In questo codelab, creerai la classe Generic pass utilizzando l'API. Questo segue la procedura utilizzata da un server di backend privato per creare classi di pass.

  1. Apri il file web/app.js
  2. Sostituisci il valore di issuerId con il tuo ID emittente da Google Pay & Wallet Console
    // TODO: Define Issuer ID
    const issuerId = 'ISSUER_ID';
  3. Individua la funzione createPassClass
  4. Nella funzione, crea un client HTTP autenticato e utilizza l'API Google Wallet per creare una nuova classe di documenti
    // 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 il codice viene eseguito, viene creato un nuovo gruppo di pass e viene visualizzato l'ID gruppo. L'ID classe è costituito 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 Generic pass

In questo passaggio, configurerai l'app Node.js per creare un oggetto Generic pass utilizzando la classe creata in precedenza. Esistono due flussi per creare 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 JWT firmato. Questa opzione è più adatta per i casi in cui l'adozione da parte degli utenti è elevata, in quanto garantisce che l'oggetto esista prima che l'utente provi ad aggiungerlo al proprio portafoglio.

Crea l'oggetto tessera quando l'utente la aggiunge al proprio portafoglio

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 degli utenti sia variabile o sconosciuta, in quanto impedisce la creazione di oggetti pass e il loro mancato utilizzo. Questo approccio verrà utilizzato nel codelab.

  1. Apri il file web/app.js
  2. Individua 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 vedrai alcun output. L'oggetto pass viene definito dall'applicazione di backend, ma non viene restituito alcun output. Successivamente, trasformerai la tessera in un link Aggiungi a Google Wallet.

6. Creare 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 viene chiesto di salvare la tessera nel suo portafoglio.

  1. Crea i claim JWT, codificali utilizzando la chiave privata dell'account di servizio e restituisci 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 pass.
  4. Quando viene visualizzato, seleziona il pulsante Aggiungi a Google Wallet.

Il pulsante Aggiungi a Google Wallet viene visualizzato correttamente nella parte anteriore dell&#39;app

7. Complimenti

Un esempio di oggetto Generic pass

Complimenti, hai integrato correttamente l'API Google Wallet sul web.

Scopri di più

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

Creare pass e richiedere l'accesso in produzione

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

Per saperne di più, consulta i prerequisiti dell'API web.

bug_report Segnala un errore