البطاقات المرتبطة تلقائيًا

خلفية

تتيح لك ميزة "البطاقات المرتبطة تلقائيًا" إرسال بطاقات إضافية إلى مستخدم لديه بطاقتك الحالية في "محفظة Google". يمكنك أيضًا ربط البطاقات مسبقًا ببطاقة أساسية عندما يحفظ المستخدم البطاقة الأساسية (الرئيسية). يتم تجميع البطاقة المرتبطة تلقائيًا مع البطاقة الأساسية مع وسيلة شرح فوق البطاقة الأساسية لإعلام المستخدم بأنّه تم ربط بطاقة جديدة. تتوفّر أنواع البطاقات التالية كبطاقات أساسية أو مرتبطة:

• بطاقة الحدث
• جواز مرور على متن طائرة
• بطاقة نقل عام
• عرض
• بطاقة هدايا
• بطاقة الولاء
• بطاقة عامة

البطاقة الأساسية مع وسيلة الإيضاح التي تشير إلى أنّه تمت إضافة بطاقة جديدة	بطاقة جديدة مرتبطة بالبطاقة الأساسية

حالات الاستخدام

قد تكون لديك حالات استخدام مختلفة لربط البطاقات ببطاقة حالية. وتشمل بعض الأمثلة ما يلي:

• ربط عرض ترويجي ببطاقة ولاء حالية
• ربط قسيمة وجبات ببطاقة صعود الطائرة أو تذكرة لحضور فعالية
• ربط تصريح وقوف سيارات بتذكرة لحضور فعالية

بعض الاعتبارات عند استخدام ميزة "البطاقات المرتبطة تلقائيًا"

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

خطوات الدمج

إذا سبق لك إنشاء عنصر أساسي، يمكنك تخطّي الخطوة 1.

1. أنشئ عنصرًا من أي نوع بطاقة مدرَج مع المَعلمات المطلوبة. هذا هو الكائن الأساسي.
2. أنشئ عنصرًا آخر من أي نوع بطاقة مُدرَج. سيكون هذا هو العنصر المرتبط.
3. قبل حفظ العنصر الأساسي أو بعده، عدِّل العنصر الأساسي باستخدام رقم تعريف العنصر المرتبط في المَعلمة linkedObjectIds.

هناك حمولة دنيا مطلوبة لضبط linkedObjectIds على بطاقة أساسية. تشمل المَعلمات الثلاث المطلوبة ما يلي:

1. ISSUERID.PRIMARY_OBJECT_ID
2. ISSUERID.PRIMARY_CLASS_ID
3. ISSUERID.LINKED_OBJECT_ID

مثال على طلب JSON لإضافة عنصر مرتبط إلى عنصر بطاقة

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": ["ISSUERID.LINKED_PASS_OBJECTID"]
  }
  …

مثال على استجابة JSON بعد ربط عنصر بعنصر بطاقة

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

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

بعد تلقّي ردّ ناجح، من المفترض أن تتلقّى الأجهزة التي تتضمّن البطاقة التي عدّلتها البطاقة المرتبطة. سيتم تجميع هذه البطاقة المرتبطة مع البطاقة الأساسية. يمكن للمستخدمين الاطّلاع على البطاقة المرتبطة من خلال التمرير سريعًا لليسار.

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

قد تحدث أخطاء محتملة عند استخدام واجهة برمجة التطبيقات بشكل غير صحيح، ويمكن أن تشمل ما يلي:

رسالة	السبب
لا يتشارك العنصر الأساسي والعنصر المرتبط في رقم تعريف الجهة المصدرة نفسه.	لا يمكنك إرفاق عنصر مرتبط بعنصر صادر عن جهة أخرى.
يشير العنصر الأساسي والعنصر المرتبط إلى العنصر نفسه.	لا يمكنك إرفاق الكائن نفسه كـ linkedObject.
العنصر المرتبط غير موجود.	يجب أن يكون العنصر المرتبط قد تم إدراجه في واجهة برمجة التطبيقات الخاصة بـ "محفظة Google".
يتضمّن العنصر المرتبط عنصرًا مرتبطًا آخر. لا يمكن إضافة عناصر مرتبطة متداخلة.	لا يمكن أن تحتوي الكائنات المرتبطة على كائن مرتبط آخر.
العنصر مرتبط حاليًا بعنصر آخر. لا يمكن إضافة عناصر مرتبطة متداخلة.	لا يمكن أن يكون العنصر الأساسي عنصرًا مرتبطًا بذاته.
لا يمكن إضافة المزيد من العناصر المرتبطة، تم تجاوز الحدّ الأقصى.	تم بلوغ الحدّ الأقصى لعدد البطاقات المرتبطة، وهو 50 بطاقة، للبطاقة الأساسية.