البطاقات المرتبطة تلقائيًا
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
الخلفية
تتيح لك ميزة "البطاقات المرتبطة تلقائيًا" إرسال بطاقات إضافية إلى
مستخدم لديه بطاقتك الحالية في "محفظة Google". يمكنك أيضًا
ربط البطاقات مسبقًا ببطاقة أساسية عندما يحفظ المستخدم البطاقة الأساسية
(الأساسية). يتم تجميع البطاقة المرتبطة تلقائيًا مع البطاقة الأساسية مع إشارة توضيحية فوق البطاقة الأساسية لإعلام المستخدم بأنّه تمت
ربط بطاقة جديدة. يمكن استخدام أنواع البطاقات التالية كبطاقات أساسية أو مرتبطة:
- بطاقة الحدث
- جواز مرور على متن طائرة
- بطاقة النقل العام
- عرض
- بطاقة هدايا
- بطاقة الولاء
- بطاقة عامة
|
|
|
البطاقة الأساسية مع التعليق التوضيحي الذي يفيد بإضافة بطاقة جديدة
|
بطاقة جديدة مرتبطة بالبطاقة الأساسية
|
حالات الاستخدام
قد تكون لديك حالات استخدام مختلفة لربط البطاقات ببطاقة حالية. تشمل بعض
الأمثلة ما يلي:
- ربط عرض ترويجي ببطاقة ولاء حالية
- ربط قسيمة طعام ببطاقة صعود طائرة أو تذكرة حضور فعالية
- ربط بطاقة وقوف السيارات بتذكرة حضور حدث
بعض الاعتبارات عند استخدام البطاقات المرتبطة تلقائيًا
- يجب أن يستخدم كلّ من العنصر الأساسي والعنصر المرتبط معًا معرّف المُصدر نفسه.
- الحد الأقصى المسموح به لعدد العناصر المرتبطة لكل عنصر أساسي هو 50 عنصرًا.
- لا يمكن ضمان إرسال البطاقات المرتبطة تلقائيًا، بل يُعد
أفضل جهد ممكن. يمكن للمستخدمين إيقاف تلقّي البطاقات المرتبطة تلقائيًا. إذا كانت حالة الاستخدام
حرجة ويجب أن يتلقّى المستخدم البطاقة المرتبطة، ننصحك
بالتواصل من خلال قناة أخرى لضمان إضافة المستخدم للبطاقة.
- تتضمّن التعديلات على بنود الخدمة في "محفظة Google"
إرشادات حول استخدام البطاقات المرتبطة تلقائيًا والتي يجب الالتزام بها.
خطوات الدمج
إذا سبق لك إنشاء عنصر أساسي، يمكنك تخطّي الخطوة 1.
- أنشئ عنصرًا من أي نوع بطاقة مُدرَج
مع المَعلمات المطلوبة. هذا هو الكائن الأساسي.
- أنشِئ عنصرًا آخر من أي نوع بطاقة مُدرَجة. سيكون هذا هو العنصر
المرتبط.
- قبل حفظ الكائن الأساسي أو بعده، عدِّل
الكائن الأساسي باستخدام رقم تعريف الكائن المرتبط في المَعلمة linkedObjectIds
.
هناك حدّ أدنى للحمولة المطلوبة لضبط linkedObjectIds في ملف primary
pass. تشمل المَعلمات الثلاث المطلوبة ما يلي:
- 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. |
| الكائن المرتبط غير موجود. |
يجب أن يكون العنصر المرتبط قد سبق إدراجه في واجهة برمجة تطبيقات المحفظة. |
| يتضمّن العنصر المرتبط عنصرًا مرتبطًا آخر. لا يمكن إضافة كائنات مرتبطة
متداخلة. |
لا يمكن أن تحتوي الكائنات المرتبطة على عنصر مرتبط آخر. |
| سبق أن تم ربط العنصر بعنصر آخر. لا يمكن إضافة كائنات
مرتبطة متداخلة. |
لا يمكن أن يكون العنصر الأساسي عنصرًا مرتبطًا بحد ذاته. |
| لا يمكن إضافة المزيد من العناصر المرتبطة، تم تجاوز الحد الأقصى. |
بلغت الحدّ الأقصى المسموح به للبطاقات المرتبطة، وهو 50
بطاقة، في البطاقة الأساسية. |
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-09-03 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-09-03 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eAuto Linked Passes enable you to send additional passes to users who already have an existing pass from your organization in their Google Wallet, pre-linking them for a seamless user experience.\u003c/p\u003e\n"],["\u003cp\u003eThis feature supports various pass types including Event tickets, Boarding passes, Transit passes, Offers, Gift cards, Loyalty passes, and Generic passes, offering flexibility for different use cases.\u003c/p\u003e\n"],["\u003cp\u003eWhen utilizing Auto Linked Passes, ensure the primary and linked objects share the same issuerId and be aware of the 50 linked object limit per primary object.\u003c/p\u003e\n"],["\u003cp\u003eWhile automatic delivery of linked passes is best-effort and user-configurable, the feature offers a convenient way to provide users with related passes, enhancing their experience with your services.\u003c/p\u003e\n"]]],["Auto Linked Passes enable grouping additional passes with an existing primary pass in Google Wallet. Supported pass types include event tickets, boarding passes, and loyalty passes. To link passes, create primary and linked objects, then update the primary object with the linked object's ID using the `linkedObjectIds` parameter. Both objects must share the same `issuerId`. There is a limit of 50 linked passes. Errors may occur if linked objects are from different issuers or the 50 limit is reached.\n"],null,["# Auto Linked Passes\n\n#### Background\n\nThe Auto Linked Passes feature lets you send additional passes to a\nuser who already has your existing pass in their Google Wallet. You can also\npre-link passes to a primary pass when a user saves the **primary**\n(main) pass. The Auto Linked Pass is grouped with the primary pass with a\ncallout above the primary pass informing the user that a new pass has been\nlinked. The following pass types are supported as primary or linked passes;\n\n- Event ticket\n- Boarding pass\n- Transit pass\n- Offer\n- Gift card\n- Loyalty pass\n- Generic pass\n\n|--------------------------------------------------------------|-------------------------------------|\n| | |\n| Primary pass with the callout that a new pass has been added | New pass linked to the primary pass |\n\n#### Use Cases\n\nYou may have different use cases for linking passes to an existing pass. Some\nexamples include:\n\n- Link an offer to an existing loyalty card.\n- Link a meal voucher to a boarding pass or event ticket.\n- Link a parking pass to an event ticket.\n\n#### Some considerations when using Auto Linked Passes\n\n- The primary object and linked object must use the same issuerId.\n- There is a limit of 50 linked objects per primary object.\n- Pushing linked passes automatically is not guaranteed and considered best-effort. Users can opt out of receiving Auto Linked Passes. If the use case is critical and the user must receive the linked pass, we recommend communicating through another channel to ensure the user adds the pass.\n- Updates to the [Google Wallet AUP](https://payments.developers.google.com/terms/aup) include guidance on the use of Auto Linked Passes which must be adhered to.\n\n#### Integration Steps\n\nIf you have already created a **primary** object you can skip step 1.\n\n1. Create an [object](/wallet/generic/use-cases/create) of any pass type listed with the required parameters. This is the **primary** object.\n2. Create another object of any pass type listed. This is going to be the **linked** object.\n3. Either before or after the primary object is saved, [update](/wallet/generic/use-cases/update) the primary object with the ID of the linked object in the linkedObjectIds parameter.\n\nThere is a minimum payload required to set the linkedObjectIds on a primary\npass. The 3 required parameters include;\n\n1. ISSUERID.PRIMARY_OBJECT_ID\n2. ISSUERID.PRIMARY_CLASS_ID\n3. ISSUERID.LINKED_OBJECT_ID\n\n#### Example JSON Request to add a linked object to a pass object\n\n```carbon\n ...\n {\n \"id\": \"ISSUERID.PASS_OBJECTID\",\n \"classId\": \"ISSUERID.PASS_CLASSID\",\n \"barcode\": {\n \"type\": \"qrCode\",\n \"value\": \"QR code\"\n },\n \"linkedObjectIds\": {\"ISSUERID.LINKED_PASS_OBJECTID\"}\n }\n ...\n```\n\n#### Example JSON Response after linking an object to a pass object\n\n```scdoc\n …\n \"state\": \"active\",\n \"linkedObjectIds\": {\n \"ISSUERID.LINKED_PASS_OBJECTID\"\n }\n …\n```\n\n#### Expected behavior\n\nAfter receiving a successful response, devices with the pass you updated\nshould receive the linked pass. This linked pass will be grouped together with\nthe primary pass. Users can see the linked pass by swiping right.\n\n#### Exception handling\n\nPotential errors may happen with incorrect use of the API which can\ninclude;\n\n| **Message** | **Reason** |\n|------------------------------------------------------------------------------------|----------------------------------------------------------------------|\n| Primary object and linked object don't share the same issuer ID. | You cannot attach a linked object to another issuer's object. |\n| Primary object and linked object refer to the same object. | You cannot attach the same object as the linkedObject. |\n| Linked object does not exist. | The linked object should already be inserted into the Wallet API. |\n| Linked object already has another linked object. Cannot add nested linked objects. | Linked objects cannot have another linked object. |\n| Object is already linked to another object. Cannot add nested linked objects. | Primary object cannot be a linked object by itself. |\n| Cannot add any more linked objects, limit exceeded. | The limit of 50 linked passes has been reached for the primary pass. |"]]
