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

الخلفية

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

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

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

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

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

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

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

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

خطوات الدمج

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

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

هناك حدّ أدنى للحمولة المطلوبة لضبط ‎linkedObjectIds في ملف ‎primary pass. تشمل المَعلمات الثلاث المطلوبة ما يلي:

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.
الكائن المرتبط غير موجود.	يجب أن يكون العنصر المرتبط قد تم إدراجه في واجهة برمجة التطبيقات Wallet API.
يتضمّن العنصر المرتبط عنصرًا مرتبطًا آخر. لا يمكن إضافة عناصر متداخلة مرتبطة.	لا يمكن أن يتضمّن العنصر المرتبط عنصرًا مرتبطًا آخر.
سبق أن تم ربط العنصر بعنصر آخر. لا يمكن إضافة عناصر مرتبطة متداخلة.	لا يمكن أن يكون الكائن الأساسي عنصرًا مرتبطًا في حد ذاته.
لا يمكن إضافة المزيد من العناصر المرتبطة، تم تجاوز الحد الأقصى.	بلغت الحدّ الأقصى المسموح به للبطاقات المرتبطة، وهو 50 بطاقة، في البطاقة الأساسية.