비공개 이미지 보호

배경

보안 비공개 이미지 기능을 사용하면 공개 URL에서 액세스할 필요가 없는 패스의 이미지를 정의할 수 있습니다 (패스에 이미지를 올바르게 렌더링하기 위한 일반 이미지의 요구사항). Wallet API를 사용하여 이미지를 업로드하고 월렛 패스 객체에서 해당 이미지를 참조하는 데 사용할 수 있는 식별자를 수신합니다.

지원되는 패스 유형은 다음과 같습니다.

  • 이벤트 티켓
  • 탑승권
  • 대중교통 이용권
  • 혜택 카드
  • 기프트 카드
  • 포인트 이용권
  • 일반 패스

기능 예시

보안 비공개 이미지 예
보안 비공개 이미지를 사용하는 멤버십 카드

사용 사례

보안 비공개 이미지를 사용하면 공개적으로 액세스할 필요가 없는 이미지를 사용할 수 있으므로 프로필 사진과 같은 용도로 사용할 수 있습니다. 이를 통해 다음과 같은 사용 사례를 사용할 수 있습니다(이에 국한되지 않음).

  • 연간 멤버십 패스
  • 명함
  • 대중교통 이용권

참고: 보안 비공개 이미지는 허용되는 사용 정책에 정의된 추가 가이드라인과 함께 정부 발급 신분증으로 패스를 나타내는 데 사용되지 않습니다.

월렛 기능 사용 시 고려사항

  • 일반 비공개 패스와 함께 사용할 수 없음
  • 패스 객체에만 추가할 수 있습니다 (클래스에는 추가할 수 없음).
  • 단일 객체와만 사용할 수 있습니다.
  • ImageModuleData와만 사용할 수 있습니다 (다른 이미지, 예: 로고 및 와이드 헤더 로고는 사용할 수 없음).

개발 중인 기능

  • 웹 지원
  • 히어로 이미지의 비공개 이미지

통합 단계

  1. Google 월렛 API를 사용하여 비공개 이미지를 업로드하여 privateImageId를 받습니다.
  2. 패스 객체 (예: ImageModuleData)에 이미지를 추가합니다. 이미지에서 sourceUri 필드를 설정하는 대신 이전 단계에서 가져온 값으로 privateImageId 필드를 설정합니다.

순차적 다이어그램

보안 이미지 시퀀스 다이어그램
비공개 이미지 시퀀스 보안

예시 코드

이미지 업로드

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();

패스 객체에서 비공개 이미지 사용

// 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();

앞면에 이미지가 표시되도록 패스 업데이트

imageModulesDatafield에서 보안 비공개 이미지를 사용할 수 있습니다. 다음은 imageModulesData 필드를 사용하여 템플릿 재정의를 통해 카드 앞면에 이미지를 배치하는 방법의 예입니다. 다음은 템플릿 재정의를 사용하여 클래스를 삽입하는 예입니다.

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))));
}

예외 처리

잘못된 Wallet FeatureAPI 사용으로 인해 발생할 수 있는 오류는 다음과 같습니다.

메시지 이유
이미지에 source_uri와 private_image_id가 모두 있을 수 없음 발급자가 단일 이미지에 source_uri와 private_image_id를 설정하려고 했으나 허용되지 않음
발급자 %s의 ID가 %s인 비공개 이미지를 찾을 수 없습니다. 객체에 존재하지 않는 비공개 이미지 ID 설정
발급자 %s의 ID %s인 비공개 이미지가 이미 객체 %s에 사용되고 있으므로 객체 %s에 추가할 수 없습니다. 비공개 이미지는 하나의 객체에만 사용할 수 있습니다. 두 개 이상의 객체에서 동일한 비공개 이미지를 사용하려고 합니다. 둘 이상의 객체에서 동일한 비공개 이미지를 사용하려면 이미지를 다시 업로드해야 하며, 두 번째 객체와 함께 사용할 수 있는 새 비공개 이미지 ID가 제공됩니다.