A cosa serve

Una classe Passes definisce un insieme di proprietà comuni in più passaggi, in modo simile a un modello. Ad esempio, se emetti biglietti per un evento, la classe Pass definirà i campi uguali in tutti i biglietti, come nome, data e ora dell'evento.

Ogni pass emesso deve fare riferimento a una Classe dei pass. Devi inoltre assegnare un ID univoco a ogni classe dei pass che crei, da utilizzare come riferimento durante la creazione dei pass.

Come si fa

Una classe Passes viene definita in formato JSON e può essere creata con l'API REST di Google Wallet, l'SDK Android o la Business Console di Google Wallet.

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "logo": {
    "sourceUri": {
      "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660"
    },
    "contentDescription": {
      "defaultValue": {
        "language": "en-US",
        "value": "LOGO_IMAGE_DESCRIPTION"
      }
    }
  },
  "eventName": {
    "defaultValue": {
      "language": "en-US",
      "value": "Google Live"
    }
  },
  "venue": {
    "name": {
      "defaultValue": {
        "language": "en-US",
        "value": "Shoreline Amphitheater"
      }
    },
    "address": {
      "defaultValue": {
        "language": "en-US",
        "value": "ADDRESS_OF_THE_VENUE"
      }
    }
  },
  "dateTime": {
    "start": "2023-04-12T11:30"
  },
  "reviewStatus": "UNDER_REVIEW",
  "hexBackgroundColor": "#264750",
  "heroImage": {
    "sourceUri": {
      "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336"
    },
    "contentDescription": {
      "defaultValue": {
        "language": "en-US",
        "value": "HERO_IMAGE_DESCRIPTION"
      }
    }
  }
}
    

A cosa serve

Un oggetto Passes definisce le proprietà di un pass univoco che verrà emesso a un utente specifico. Ad esempio, l'oggetto Pass per un biglietto per un evento definisce i campi univoci per un biglietto specifico, come il numero di posto o un codice QR per quel biglietto.

Quando viene creato un oggetto Passes, l'API Google Wallet archivia una nuova tessera e la associa al tuo account emittente. Questo pass archiviato è una combinazione delle proprietà univoche dell'oggetto Passes e delle proprietà del modello della classe Passes associata.

Devi inoltre assegnare a ciascun oggetto dei pass un ID univoco, che verrà utilizzato come riferimento quando emetti una tessera.

Come si fa

Un oggetto Passes è un formato JSON definito e può essere creato con l'API REST di Google Wallet o l'SDK Android.

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "5"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "G"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "40"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "3A"
      }
    }
  },
  "barcode": {
    "type": "QR_CODE",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}
    

A cosa serve

Per emettere un pass per un utente, le classi e gli oggetti Passes devono essere codificati in un token JWT (JSON Web Token). Il formato JWT è uno standard comune e aperto per la rappresentazione delle rivendicazioni tra due parti. Nel caso di emissione di tessere con l'API Google Wallet, i JWT vengono utilizzati per inviare un reclamo secondo cui un utente ha il diritto di accedere a una tessera specifica associata al tuo account emittente.

Quando un JWT viene inviato all'API Google Wallet, i dati codificati vengono utilizzati per identificare un pass specifico e rilasciarlo all'utente. Se la tessera è già stata emesso, questi dati consentono inoltre all'API Google Wallet di identificare che la tessera è un duplicato, in modo che non venga aggiunta più volte al Google Wallet dell'utente.

Come si fa

I JWT vengono definiti in formato JSON in base alla specifica JWT. Per definire un JWT per l'emissione di una tessera con l'API Google Wallet, devi fornire le informazioni sulla tessera che vuoi emettere nella proprietà payload del JWT.

{
  "iss": "issuer@example.com",
  "aud": "google",
  "typ": "savetowallet",
  "iat": 1696877738,
  "origins": [
    "www.example.com"
  ],
  "payload": {
    "eventTicketObjects": [
      {
        "id": "ISSUER_ID.LOYALTY_OBJECT_SUFFIX"
      }
    ]
  }
}
    

A cosa serve

Tutti i JWT inviati all'API Google Wallet per emettere una tessera devono essere firmati con le credenziali che hai fornito in precedenza in Google Wallet Business Console. La firma utilizza le tue credenziali per criptare il JWT in modo che i tuoi pass rimangano sicuri e per consentire all'API Google Wallet di autenticare che i dettagli del pass codificati al suo interno siano validi e associati al tuo account emittente.

Come si fa

Le librerie client di Google Wallet e l'SDK Android offrono metodi pratici per firmare i JWT. Sono inoltre disponibili numerose librerie open source che gestiscono la complessità della firma del codice tra cui scegliere.

Per chi utilizza l'API REST di Google Wallet per emettere le tessere, il JWT viene firmato con una chiave dell'account di servizio Google Cloud. Per chi utilizza l'SDK Google Wallet per Android, l'SDK gestisce automaticamente la firma del JWT con l'impronta SHA-1 del certificato di firma della tua app.

Per proteggere le tue credenziali, i JWT devono essere firmati solo sul tuo server o utilizzando l'SDK Google Wallet per Android nella tua app.

  // Create the JWT as a HashMap object
  HashMap claims = new HashMap();
  claims.put("iss", ((ServiceAccountCredentials) credentials).getClientEmail());
  claims.put("aud", "google");
  claims.put("origins", Arrays.asList("www.example.com"));
  claims.put("typ", "savetowallet");

  // Create the Google Wallet payload and add to the JWT
  HashMap payload = new HashMap();
  payload.put("eventTicketObjects", Arrays.asList(newObject));
  claims.put("payload", payload);

  // Google Cloud service account credentials are used to sign the JWT
  Algorithm algorithm =
      Algorithm.RSA256(
          null, (RSAPrivateKey) ((ServiceAccountCredentials) credentials).getPrivateKey());
  String token = JWT.create().withPayload(claims).sign(algorithm);
        

  // Create the JWT claims
  let claims = {
    iss: this.credentials.client_email,
    aud: 'google',
    origins: ['www.example.com'],
    typ: 'savetowallet',
    payload: {
      eventTicketObjects: [newObject]
    },
  };

  // The service account credentials are used to sign the JWT
  let token = jwt.sign(claims, this.credentials.private_key, { algorithm: 'RS256' });
        

  # Create the JWT claims
  claims = {
      'iss': self.credentials.service_account_email,
      'aud': 'google',
      'origins': ['www.example.com'],
      'typ': 'savetowallet',
      'payload': {
          # The listed classes and objects will be created
          'eventTicketObjects': [new_object]
      }
  }

  # The service account credentials are used to sign the JWT
  signer = crypt.RSASigner.from_service_account_file(self.key_file_path)
  token = jwt.encode(signer, claims).decode('utf-8')
        

A cosa serve

Dopo aver creato un JWT firmato, puoi emettere la tessera per un utente di Google Wallet. A tale scopo, presenta all'utente un pulsante o un link "Aggiungi a Google Wallet". Quando un utente fa clic sul pulsante o sul link ipertestuale, il JWT firmato viene inviato all'API Google Wallet, che quindi lo decripta utilizzando le tue credenziali salvate. Una volta autenticata la firma JWT, la tessera viene emessa all'utente per il salvataggio nel suo Google Wallet.

Come si fa

Per creare un pulsante "Aggiungi a Google Wallet" per un'app Android, utilizza l'SDK Android di Google Wallet, che fornisce i metodi per generare il pulsante. Per tutte le altre piattaforme, inclusi web, email e SMS, crea un link ipertestuale nel formato https://pay.google.com/gp/v/save/<signed_jwt>. Se possibile, ti consigliamo di inviare all'utente questo link sotto forma di pulsante "Aggiungi a Google Wallet".

Per ulteriori informazioni sull'utilizzo del pulsante "Aggiungi a Google Wallet", consulta le linee guida per il brand dell'API Google Wallet

  https://pay.google.com/gp/v/save/<signed_jwt>
        

  private lateinit var walletClient: PayClient
  private val addToGoogleWalletRequestCode = 1000
  private lateinit var addToGoogleWalletButton: View

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    walletClient = Pay.getClient(this)
    addToGoogleWalletButton.setOnClickListener {
      walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode)
    }
  }
        

Una volta che l'utente ha salvato la tessera rilasciata, questa verrà visualizzata nell'app Google Wallet insieme a tutti gli altri pass salvati.