Immagini private sicure

Sfondo

La funzionalità Immagini private sicure ti consente di definire immagini sulle tessere che non devono essere accessibili da un URL pubblico (un requisito per le immagini normali per visualizzarle correttamente sulle tessere). Utilizzi l'API Wallet per caricare un'immagine e ricevere un identificatore che può essere utilizzato per fare riferimento a questa immagine in un oggetto tessera Wallet.

Sono supportati i seguenti tipi di tessera:

  • Biglietto per un evento
  • Carta d'imbarco
  • Tessera per il trasporto pubblico
  • Scheda dell'offerta
  • Buono omaggio
  • Carta fedeltà
  • Tessera generica

Esempio di funzionalità

Esempio di immagine privata protetta
Tessera associativa che utilizza un'immagine privata sicura

Casi d'uso

Le immagini private sicure consentono l'utilizzo di immagini che non devono essere accessibili pubblicamente e che possono quindi essere utilizzate per scopi come una foto del profilo. Ciò consente casi d'uso quali, a titolo esemplificativo:

  • Pass abbonamento annuale
  • Biglietto da visita
  • Tessera per il trasporto pubblico

Nota: le immagini private sicure non sono destinate a essere utilizzate per rappresentare tessere come documenti di identità ufficiali insieme alle linee guida aggiuntive definite nelle norme di utilizzo accettabile.

Alcune considerazioni sull'utilizzo di immagini private sicure

  • Non può essere utilizzato con i documenti personali generici
  • Possono essere aggiunti solo a oggetti tessera (non a classi)
  • Può essere utilizzato solo con un singolo oggetto
  • Può essere utilizzato solo con ImageModuleData (le immagini private non possono essere assegnate ad altri campi immagine, ad esempio heroImage, logo o wideLogo)
  • Le tessere che utilizzano immagini private sicure in ImageModuleData possono comunque mostrare contemporaneamente immagini standard dell'eroe e del logo (ospitate su URL accessibili pubblicamente). L'aggiunta di un'immagine privata non limita né blocca la visualizzazione delle immagini standard dell'eroe o del logo sulla tessera.

Funzionalità in fase di sviluppo

  • Assistenza web
  • Supporto per le immagini private nel campo heroImage (utilizzo di un'immagine promozionale privateImageId)

Passaggi per l'integrazione

  1. Carica la tua immagine privata utilizzando l'API Google Wallet per ricevere un privateImageId.
  2. Aggiungi un'immagine all'oggetto tessera (ad esempio, ImageModuleData). Invece di impostare il campo sourceUri nell'immagine, imposta il campo privateImageId con il valore ottenuto dal passaggio precedente.

Diagramma di sequenza

Diagramma della sequenza di immagini sicura
Sequenza di immagini privata sicura

Codice di esempio

Carica l'immagine

String issuerId = "12345";
String keyFilePath = "/path/to/key.json";
GoogleCredential credential =
    GoogleCredential.fromStream(new FileInputStream(keyFilePath))
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/wallet_object.issuer"));
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();

// Prepare request to upload image
String contentType = "image/jpeg";  // MIME type of image
String imageFilePath = "/path/to/image.jpg";
HttpContent content =
    new ByteArrayContent(
        contentType, ByteStreams.toByteArray(new FileInputStream(imageFilePath)));

String url =
    String.format(
        "https://walletobjects.googleapis.com/upload/walletobjects/v1/privateContent/%s/uploadPrivateImage",
        issuerId);

// Make request to upload image
HttpResponse response =
    httpTransport
        .createRequestFactory(credential)
        .buildPostRequest(new GenericUrl(url), content)
        .execute();

// Get privateImageId from response
Gson gson = new Gson();
JsonObject jsonObject = gson.fromJson(response.parseAsString(), JsonObject.class);
String privateImageId = jsonObject.get("privateImageId").getAsString();

Utilizzare l'immagine privata nell'oggetto della tessera

// Build GenericObject with privateImageId in ImageModuleData (also adding an optional TextModuleData)
Image image = new Image().setPrivateImageId(privateImageId);
ImageModuleData imageModuleData = new ImageModuleData().setId("imageId").setMainImage(image);
TextModuleData textModuleData =
    new TextModuleData().setId("textId").setHeader("Card holder").setBody("John Doe");
GenericObject genericObject =
    new GenericObject()
        .setId(issuerId + ".objectId")
        // class must be inserted before inserting object
        .setClassId(issuerId + ".classId")
        .setCardTitle("Business name")
        .setHeader("My membership card")
        .setImageModulesData(Arrays.asList(imageModuleData))
        .setTextModulesData(Arrays.asList(textModuleData));

// Insert GenericObject (or can use in JWT without inserting ahead of time)
Walletobjects service =
    new Walletobjects.Builder(httpTransport, GsonFactory.getDefaultInstance(), credential)
        .setApplicationName("My Application")
        .build();

service.genericobject().insert(genericObject).execute();

Aggiorna la tessera per mostrare l'immagine sul fronte

Puoi utilizzare l'immagine privata protetta in qualsiasi imageModulesDatafield. Di seguito è riportato un esempio di come utilizzare un campo imageModulesData per posizionare l'immagine sulla parte anteriore della scheda utilizzando l'override di un modello. Ecco un esempio di inserimento di una classe con l'override di un modello:

CardTemplateOverride cardTemplateOverride =
    new CardTemplateOverride()
        .setCardRowTemplateInfos(
            Arrays.asList(
                new CardRowTemplateInfo()
                    .setTwoItems(
                        new CardRowTwoItems()
                            // The ids chosen here must be set on the object's TextModuleData and ImageModuleData
                            .setStartItem(
                                createTemplateItem("object.textModulesData['textId']"))
                            .setEndItem(
                                createTemplateItem("object.imageModulesData['imageId']")))));
GenericClass genericClass =
    new GenericClass()
        .setId(issuerId + ".classId")
        .setClassTemplateInfo(
            new ClassTemplateInfo().setCardTemplateOverride(cardTemplateOverride));

service.genericclass().insert(genericClass);


...


private static TemplateItem createTemplateItem(String fieldPath) {
  return new TemplateItem()
      .setFirstValue(
          new FieldSelector()
              .setFields(Arrays.asList(new FieldReference().setFieldPath(fieldPath))));
}

Gestione delle eccezioni

Potrebbero verificarsi potenziali errori con l'utilizzo errato dell'API Google Wallet, tra cui:

Messaggio Motivo
L'immagine non può avere sia source_uri che private_image_id L'emittente ha tentato di impostare un source_uri e un private_image_id su una singola immagine, operazione non consentita
Impossibile trovare l'immagine privata con ID %s per l'emittente %s Impostazione di un ID immagine privata inesistente su un oggetto
Impossibile aggiungere l'immagine privata con ID %s per l'emittente %s all'oggetto %s perché è già utilizzata con l'oggetto %s. Un'immagine privata può essere utilizzata solo con un oggetto. Tentativo di utilizzare la stessa immagine privata su più oggetti. Per utilizzare la stessa immagine privata con più di un oggetto, è necessario caricarla di nuovo e otterrai un nuovo ID immagine privata, che può essere utilizzato con il secondo oggetto