Panoramica: configurazione Google Wallet Issuer gestita vs. personalizzata
A differenza dell'obbligo di certificato per singolo merchant richiesto da Apple Wallet, Passinstance offre fin da subito un'Infrastruttura gestita di Google Wallet Issuer, consentendo di pubblicare e distribuire pass Android immediatamente durante l'onboarding (PUT /api/v1/onboarding/wallet-setup). Per i brand enterprise che necessitano della titolarità diretta del proprio Issuer ID della Google Pay & Wallet Console o di chiavi contactless Google Smart Tap dedicate, Passinstance supporta inoltre il collegamento di un Google Cloud Service Account dedicato (POST /api/v1/google-wallet/setup).
Prerequisiti: Quando si configura un Google Wallet Issuer ID personalizzato, è obbligatorio invitare il
client_emaildel Google Cloud Service Account nella Google Pay & Wallet Business Console -> Users con permessi di Developer. Senza questa associazione IAM, l'APIwalletobjectsdi Google restituisce403 Forbiddenquando Passinstance tenta di creare Class o Object.
Confronto tra modalità Google Issuer gestita e personalizzata
| Funzionalità | Issuer Passinstance gestito | Issuer ID Enterprise personalizzato |
|---|---|---|
| Tempo di configurazione | Istantaneo (0 minuti) | ~15 minuti (Google Cloud + Business Console) |
| Nome brand e logo sulla tessera | Completamente personalizzabili per modello (issuerName, programLogo) | Completamente personalizzabili per modello (issuerName, programLogo) |
| Accesso Google Pay & Wallet Console | Gestito da Passinstance | Accesso diretto alla propria Google Business Console |
Google Smart Tap NFC (NFC_SMART_TAP) | Utilizza la configurazione workspace/lettore | Supporta i propri smartTapMerchantId e collectorId personalizzati |
Webhook di callback (/api/v1/wallet/callback) | Preconfigurato automaticamente | Configurato automaticamente alla creazione della classe |
API di configurazione Google Wallet e attivazione modelli (Google Wallet Setup API)
Tutti gli endpoint per l'emittente Google Wallet e il provisioning dei modelli si trovano sotto /api/v1/google-wallet:
| Metodo | Percorso endpoint | Permesso richiesto | Descrizione |
|---|---|---|---|
| POST | /api/v1/google-wallet/setup | wallet:manage, certificates:manage | Predispone un account emittente Google Wallet e l'eventuale Smart Tap collector ID usando i dati aziendali del workspace. |
| GET | /api/v1/google-wallet/status | wallet:read / wallet:manage | Restituisce { isConfigured, collectorId } indicando se Google Wallet e Smart Tap sono stati predisposti. |
| POST | /api/v1/google-wallet/repair-callbacks | wallet:manage, certificates:manage | Risincronizza eventuali URL webhook /api/v1/wallet/callback mancanti sulle classi Google Wallet pubblicate. |
| POST | /api/v1/google-wallet/templates/:templateId/activate | wallet:manage, certificates:manage | Attiva il provisioning della classe Google Wallet per uno specifico modello. |
| POST | /api/v1/google-wallet/templates/:templateId/deactivate | wallet:manage, certificates:manage | Disattiva il supporto Google Wallet per uno specifico modello. |
| GET | /api/v1/google-wallet/templates/:templateId/status | wallet:manage, certificates:read | Restituisce { isEnabled, issuerId } per il modello di destinazione. |
Esempio: inizializzare la configurazione Google Wallet Issuer
POST /api/v1/google-wallet/setup
X-API-Key: <API_KEY>
Risposta (201 Created):
{
"issuerId": "3388000000022194812",
"googlePayAccount": {
"accountIdentifier": "3388000000022194812",
"collectorId": "50992104"
},
"smartTapMerchantData": {
"smartTapMerchantId": "50992104"
}
}
La verifica successiva tramite GET /api/v1/google-wallet/status restituisce { "isConfigured": true, "collectorId": "50992104" }, e i singoli pass espongono googleWalletTypeSource (Google Wallet source type: INITIAL_CREATION | MIGRATION | MANUAL_REGENERATION).
Best practice durante la configurazione del modello
-
1
Scegliere la categoria di pass Google corrispondente: Dentro Modifica modello -> Tipi di pass, abbini il programma a Carta fedeltà (
LoyaltyClass), Offerta (OfferClass), Gift Card (GiftCardClass), Biglietto evento (EventTicketClass) o Pass generico (GenericClass) — le classi Google Wallet non possono cambiare tipo di risorsa dopo la pubblicazione. -
2
Testare esplicitamente le anteprime Android: Alterni tra Apple Wallet e Google Wallet nel pannello di anteprima live poiché rapporti d'aspetto delle immagini (
androidBackgroundbanner ampio vs ritaglio quadratogooglePayLogo) e regole di troncamento testo differiscono tra le due piattaforme. -
3
Utilizzare gli Override Android: Imposti etichette e valori dedicati per Android tramite l'Ispettore quando uno slot di layout Apple non corrisponde 1:1 su Android.
Consulti Google Wallet e Google Smart Tap per le specifiche di Class/Object e NFC.
