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