الخلفية
تتيح لك ميزة "البطاقات المرتبطة تلقائيًا" إرسال بطاقات إضافية إلى مستخدم لديه بطاقتك الحالية في "محفظة Google". يمكنك أيضًا ربط الحساب المسبق ببطاقة أساسية عندما يحفظ المستخدم البطاقة الأساسية (الرئيسية). يتم تجميع "البطاقة المرتبطة تلقائيًا" مع البطاقة الأساسية مع وسيلة شرح أعلى البطاقة الأساسية لإعلام المستخدم بأنّه قد تم ربط بطاقة جديدة. يُسمح باستخدام أنواع البطاقات التالية كبطاقات أساسية أو مرتبطة.
- بطاقة الحدث
- جواز المرور على متن الطائرة
- بطاقة نقل عام
- العرض الترويجي
- بطاقة هدايا
- بطاقة ولاء
- بطاقة عامة
حالات الاستخدام
قد تكون لديك حالات استخدام مختلفة لربط البطاقات ببطاقة حالية. تتضمن بعض الأمثلة ما يلي:
- ربط عرض ببطاقة ولاء حالية
- اربط قسيمة وجبات ببطاقة صعود الطائرة أو تذكرة لحضور فعالية.
- اربط بطاقة موقفًا للسيارات بتذكرة لحضور فعالية.
بعض الاعتبارات عند استخدام البطاقات المرتبطة تلقائيًا
- يجب أن يستخدم العنصر الأساسي والعنصر المرتبط رقم تعريف الإصدار نفسه.
- هناك حد أقصى يبلغ 50 عنصرًا مرتبطًا لكل عنصر أساسي.
- يُرجى العِلم أنّ إرسال البطاقات المرتبطة تلقائيًا ليس مضمونًا، يُعتبر ذلك أفضل جهد. يمكن للمستخدمين إيقاف تلقّي "البطاقات المرتبطة تلقائيًا". إذا كانت حالة الاستخدام حرجة وكان على المستخدم تلقّي البطاقة المرتبطة، ننصحك بالتواصل عبر قناة أخرى لضمان إضافة المستخدم للبطاقة.
- إنّ التعديلات التي تم إجراؤها على سياسة الاستخدام المقبول (AUP) في "محفظة Google" تتضمّن إرشادات حول استخدام البطاقات المرتبطة تلقائيًا والتي يجب الالتزام بها.
خطوات الدمج
إذا سبق لك إنشاء عنصر أساسي، يمكنك تخطّي الخطوة 1.
- أنشئ كائنًا من أي نوع تمرير مُدرج مع المعلَمات المطلوبة. وهذا هو الكائن الأساسي.
- أنشئ عنصرًا آخر من أي نوع تمرير مدرج. وسيكون هذا هو الكائن linked.
- قبل حفظ العنصر الأساسي أو بعده، عليك تعديل الكائن الأساسي برقم تعريف العنصر المرتبط في المَعلمة linkedObjectIds.
هناك حد أدنى للحمولة مطلوب لضبط linkedObjectIds على تصريح أساسي. تشمل المعلمات الثلاث المطلوبة ما يلي:
- ISSUERID.PRIMARY_OBJECT_ID
- ISSUERID.PRIMARY_CLASS_ID
- 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 بطاقة مرتبطة. |