فرص القيمة المضافة

خلفية

يمكنك الآن تعديل الكائنات والفئات لتضمين وحدات فرص القيمة المضافة. سيتم عرض الوحدات في القسم السفلي من البطاقة ويمكن أن تتضمّن روابط تؤدي إلى محتوى الجهة المصدرة. يوضّح هذا المستند الخطوات الأساسية المطلوبة لتفعيل الوحدات واستخدامها باستخدام Google Wallet API.

مثال على الميزة

مثال واحد على وحدة فرص القيمة مثال على قائمة وحدات فرص القيمة
عرض واحد عرض على شكل قائمة

يفترض الدليل التالي أنّك على دراية بالمفاهيم الأساسية لمحفظة Google وأنّك سبق لك إكمال المتطلبات الأساسية الموصى بها. يمكنك إرسال أي أسئلة أو ملاحظات إلى جهة الاتصال المعنيّة في "محفظة Google".

خطوات الدمج

لإضافة وحدة جديدة، عليك تعديل العنصر و/أو الفئة لتضمين ValueAddedModuleData. يحتوي ValueAddedModuleData على الحقول التالية:

[Required] LocalizedString header

العنوان المعروض على الوحدة عدد الأحرف المسموح به هو 60 حرفًا، وسيتم اقتطاع السلاسل الأطول. مثال على عنوان فرصة القيمة

LocalizedString body

نص الإعلان المعروض في الوحدة يبلغ عدد الأحرف المسموح به 50 حرفًا، وسيتم اقتطاع السلاسل الأطول.
مثال على نص فرصة القيمة

صورة الصورة

الصورة المعروضة على الوحدة نسبة العرض إلى الارتفاع المقترَحة هي 1:1، وسيتم تغيير حجم الصور لتتلاءم مع هذه النسبة.
مثال على صورة فرصة القيمة

[مطلوب] معرّف الموارد المنتظم (URI) للسلسلة

معرّف URI الذي يؤدي إليه العنصر عند النقر عليه يمكن أن يكون رابط ويب أو رابط لصفحة معيّنة.

ModuleViewConstraints viewConstraints

القيود التي يجب استيفاؤها كلها لعرض الوحدة يحتوي ModuleViewConstraints على الحقل التالي:

TimeInterval displayInterval

الفترة الزمنية التي سيتم خلالها عرض الوحدة للمستخدمين يمكن تحديد كل من `startTime` و`endTime`. يتم عرض الوحدة فور إدراجها ما لم يتم ضبط `startTime`. يتم عرض الوحدة لأجل غير مسمى إذا لم يتم ضبط `endTime`.

int32 sortIndex

فهرس ترتيب الوحدات. يتم عرض الوحدات التي لديها فهرس ترتيب أقل قبل الوحدات التي لديها فهرس ترتيب أعلى. إذا لم يتم تحديدها، يُفترض أنّ فهرس الترتيب هو INT_MAX. بالنسبة إلى وحدتَين لهما الفهرس نفسه، يكون سلوك الترتيب غير محدّد.

مثال على ValueAddedModuleData:

  {
    "valueAddedModuleData": [
      {
        "header": {
          "defaultValue": {
            "language": "en-US",
            "value": "10% off merch"
          }
        },
        "body": {
          "defaultValue": {
            "language": "en-US",
            "value": "Shirts, caps, mugs, and more"
          }
        },
        "image": {
          "sourceUri": {
            "uri": "http://www.images.google.com/opportunity"
          }
        },
        "uri": "http://www.google.com/opportunity",
        "viewConstraints": {
          "displayInterval": {
            "start": {
              "date": "2024-08-01T18:30:00"
            },
            "end": {
              "date": "2025-08-01T18:30:00"
            }
          }
        },
        "sortIndex": 0
      },
      {
        "header": {
          "defaultValue": {
            "language": "en-US",
            "value": "10% off concessions"
          }
        },
        "uri": "http://www.google.com/new_opportunity"
      }
    ]
  }

السلوك المتوقّع

بعد تعديل العنصر و/أو الفئة بنجاح، ستظهر لك الآن وحدات على البطاقة ذات الصلة. إذا أضفت وحدة واحدة فقط، ستظهر في مقدّمة البطاقة.

إرشادات بشأن وحدات الفرص ذات القيمة المضافة

الوحدات هي فرص تتيح لك تحسين تجربة المستخدم في البطاقة من خلال اتّخاذ إجراءات إضافية. يجب مراعاة ما يلي عند إنشاء الوحدات وإدارتها:

  • يجب تحديد الوحدات باستخدام لغة مناسبة للإشارة إلى أنّها قابلة للتنفيذ، وذلك لمساعدة المستخدمين على فهم أنّ هذه الوحدات قابلة للنقر.
  • يجب أن تتضمّن الوحدات صورًا مناسبة مرتبطة بالوحدة المحدّدة.
  • يمكنك التحكّم في الوحدات وعليك إدارة ترتيب أولويتها بشكل استباقي حسب أهميتها ومدى صلتها بالموضوع.
  • يجب عرض الوحدات النشطة فقط للمستخدمين. يمكنك التحكّم في ذلك من خلال ضبط displayInterval على الوحدة أو إضافة الوحدة أو إزالتها بشكل استباقي من الفئة أو العنصر.

التعامل مع الاستثناءات

رسالة السبب
يجب أن يحتوي ValueAddedModuleData على عنوان. لا يحتوي ValueAddedModuleData على عنوان.
يجب أن يحتوي ValueAddedModuleData على معرّف موارد منتظم (URI) غير فارغ. لا يحتوي ValueAddedModuleData على معرّف موارد منتظم (URI) غير فارغ.
يُسمح بحد أقصى 15 وحدة ذات قيمة مضافة لكل صف. يجب تقليل الوحدات ذات القيمة المضافة في الصف.
يُسمح بحد أقصى 15 وحدة ذات قيمة مضافة لكل عنصر. يجب تقليل الوحدات ذات القيمة المضافة في العنصر.