الخلفية
تتيح لك ميزة "الصور الخاصة الآمنة" تحديد الصور على البطاقات التي لا يلزم أن تكون متاحة من عنوان URL متاح للجميع (وهو شرط لعرض الصور العادية بشكل صحيح على البطاقات). يمكنك استخدام Wallet API لتحميل صورة وتلقّي معرّف يمكن استخدامه للإشارة إلى تلك الصورة في عنصر بطاقة Wallet.
تتوفّر أنواع البطاقات التالية:
- تذكرة لحضور فعالية
- جواز مرور على متن طائرة
- بطاقة نقل عام
- بطاقة العرض
- بطاقة هدايا
- بطاقة الولاء
- بطاقة عامة
مثال على الميزة
|
| بطاقة العضوية باستخدام صورة خاصة آمنة |
حالات الاستخدام
تتيح الصور الخاصة الآمنة استخدام الصور التي لا يلزم أن تكون متاحة للجميع، وبالتالي يمكن استخدامها لأغراض مثل صورة الملف الشخصي. يتيح ذلك حالات استخدام مثل، على سبيل المثال لا الحصر، ما يلي:
- بطاقة الاشتراك السنوية
- بطاقة النشاط التجاري
- بطاقة نقل عام
ملاحظة: لا يُقصد استخدام الصور الخاصة الآمنة لتمثيل بطاقات التعريف الصادرة عن جهة حكومية، ويجب الالتزام بالإرشادات الإضافية المحدّدة في سياسة الاستخدام المقبول.
بعض الاعتبارات عند استخدام ميزة "محفظة Google"
- لا يمكن استخدامها مع البطاقات الخاصة العامة
- يمكن إضافتها إلى عناصر البطاقة فقط (وليس إلى فئاتها)
- يمكن استخدامه مع عنصر واحد فقط
- يمكن استخدامها فقط مع ImageModuleData (وليس مع صور أخرى، مثل الشعار وشعار العنوان العريض)
الميزات قيد التطوير
- دعم الويب
- الصور الخاصة في الصور الرئيسية
خطوات الدمج
- حمِّل صورتك الخاصة باستخدام Google Wallet API لتلقّي
privateImageId. - أضِف صورة إلى عنصر البطاقة (على سبيل المثال،
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();
تعديل البطاقة لإظهار الصورة على الجهة الأمامية
يمكنك استخدام الصورة الخاصة الآمنة في أي حقل imageModulesData. في ما يلي مثال على كيفية استخدام حقل 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 للجهة المصدرة %s | ضبط رقم تعريف صورة خاصة غير متوفّرة على عنصر |
| تعذّر إضافة صورة خاصة تحمل رقم التعريف %s للجهة المصدرة %s إلى العنصر %s لأنّها مستخدَمة حاليًا مع العنصر %s. لا يمكن استخدام صورة خاصة إلا مع عنصر واحد. | محاولة استخدام الصورة الخاصّة نفسها في أكثر من عنصر واحد لاستخدام الصورة الخاصة نفسها مع أكثر من عنصر واحد، يجب إعادة تحميلها وستحصل على رقم تعريف جديد للصورة الخاصة، ويمكن استخدام هذا الرقم مع العنصر الثاني. |