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 il rendering corretto delle immagini normali 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 tessere:

  • 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 sicura
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 quindi potrebbero 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 della funzionalità Wallet

  • Non può essere utilizzato con i pass privati 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 (non con altre immagini, ad es. logo e logo dell'intestazione larga)

Funzionalità in fase di sviluppo

  • Assistenza web
  • Immagini private nelle immagini hero

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 sulla parte anteriore

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'uso errato dell'API funzionalità 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, il che non è consentito
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 con un solo 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