يسرد هذا المستند المصطلحات والمفاهيم الشائعة التي يجب أن تكون على دراية بها عند استخدام Google Wallet API.
البطاقات
التخطّي
البطاقة هي مثيل لـ "بطاقة" تم إصدارها للمستخدم لحفظها في "محفظة Google". توفّر Google Wallet API إمكانية استخدام عدد من أنواع البطاقات الشائعة، بما في ذلك بطاقات صعود الطائرة وتذاكر حضور الفعاليات وبطاقات التعريف وغيرها. توفّر Google Wallet API أيضًا نوع بطاقة عامة يمكن استخدامه لإنشاء بطاقات غير متوافقة تحديدًا.
وفي معظم الحالات، يتم إنشاء بطاقة باستخدام كل من "فئة البطاقات" و"عنصر البطاقات".
جهة إصدار البطاقة
جهة إصدار البطاقات هي كيان ينشئ البطاقات ويصدرها للمستخدمين لحفظها في "محفظة Google". إنّ "جهة إصدار البطاقة" هي مالك البطاقات، ويمكنها إنشاؤها وإصدارها وتعديلها. ويمكن أن تكون "جهات إصدار البطاقات" عبارة عن مطوّرين فرديين وشركات ومؤسسات، فضلاً عن مجمّعي السلع الذين ينشئون البطاقات ويصدرونها نيابةً عن جهات أخرى، مثل شركة متخصّصة في شراء تذاكر الفعاليات أو القسائم الخاصة ببائعي التجزئة.
فئة البطاقات
يمكن اعتبار فئة البطاقات نموذجًا مشتركًا يتم إنشاء البطاقات منه. تحدّد فئة البطاقات خصائص معيّنة سيتم تضمينها في جميع البطاقات التي تستخدمها. يمكن لجهة إصدار البطاقة إنشاء فئات متعددة، يتضمّن كل منها مجموعة مميّزة من الخصائص التي تحدّد سمات مثل النمط والمظهر، بالإضافة إلى ميزات إضافية، مثل "الدفع الذكي" و"التسجيل" و"تسجيل الدخول".
في معظم الحالات، يتم إنشاء بطاقة من خلال توفير "فئة البطاقات" لتحديد نموذج البطاقة، وكائن "البطاقات" لتحديد تفاصيل البطاقة الفردية التي يتم إصدارها.
عنصر التمرير
يحدّد "عنصر البطاقات" بطاقة فردية يتم إصدارها للمستخدم لحفظها في "محفظة Google". غالبًا ما تحتوي كائنات البطاقات على معلومات خاصة بالمستخدم. على سبيل المثال، بإمكان "فئة البطاقات" تحديد شكل بطاقة الهدايا لمتجر معيّن، في حين سيقدّم "عنصر البطاقات" تفاصيل محدّدة، مثل الرصيد أو تاريخ انتهاء الصلاحية.
يجب إنشاء عنصر بطاقات لكل بطاقة يتم إصدارها، بدلاً من "فئات البطاقات" التي يمكن مشاركتها في العديد من حالات البطاقات.
البطاقات الخاصة
قد تحتوي بعض البطاقات التي تنشئها باستخدام Google Wallet API على بيانات حسّاسة للمستخدمين. تتطلّب هذه البطاقات حماية إضافية للمساعدة في الحفاظ على أمان بيانات المستخدمين، وتتم إدارتها بشكل مختلف في Google Wallet API باستخدام النوع البطاقة الخاصة العامة. يجب استخدام البطاقة الخاصة العامة في الحالات التي تتضمّن فيها بطاقتك بيانات حسّاسة (على النحو المحدّد في سياسة الاستخدام المقبول لواجهة Google Wallet API)، وقد تخضع هذه البطاقة لعناصر تحكّم إضافية في الخصوصية ومراجعتها أثناء عملية الإعداد.
الدفع الذكي
الدفع الذكي هو بروتوكول اتصال قصير المدى تملكه Google ويهدف إلى نقل البيانات بين جهاز جوّال ووحدة طرفية لتقنية NFC. تتيح تكنولوجيا "الدفع الذكي" للمستخدمين تحصيل قيمة البطاقات المحفوظة في "محفظة Google" من خلال تثبيت هواتفهم بالقرب من أي محطة دفع متوافقة مع تقنية NFC.
لاستخدام بروتوكول "الدفع الذكي" مع بطاقاتك، يجب إنشاء علاقة مع موفّر محطة دفع يتيح "الدفع الذكي".
واجهات برمجة التطبيقات وحزمة تطوير البرامج (SDK)
واجهة برمجة تطبيقات محفظة Google
Google Wallet API هي خدمة تقدّمها Google تتيح لك إنشاء بطاقات وإصدارها للمستخدمين لحفظها في "محفظة Google". يمكن استخدام واجهة برمجة التطبيقات بعدة طرق مختلفة، بما في ذلك Google Wallet REST API وحزمة تطوير البرامج (SDK) لنظام التشغيل Android في "محفظة Google" ووحدة تحكّم "محفظة Google".
واجهة برمجة تطبيقات REST في "محفظة Google"
Google Wallet REST API هي واجهة لإنشاء البطاقات وإدارتها آليًا من خلال إرسال طلبات HTTP إلى Google Wallet API.
لاستخدام واجهة برمجة تطبيقات Google Wallet REST، عليك أيضًا إنشاء حساب على Google Cloud لإنشاء حساب خدمة يُستخدم لمصادقة الطلبات المتعلّقة بواجهة Google Wallet REST API.
حزمة تطوير البرامج (SDK) لنظام التشغيل Android في "محفظة Google"
توفّر حزمة تطوير البرامج (SDK) لنظام التشغيل Android في "محفظة Google" مجموعة من الطرق المناسبة للعمل مع Google Wallet API في تطبيقات Android، مثل إنشاء البطاقات وإصدارها.
الإضافة إلى "محفظة Google"
زر "الإضافة إلى محفظة Google"
زر "الإضافة إلى محفظة Google" هو مادة عرض معتمدة من Google لعرض البطاقة للمستخدم. عندما ينقر المستخدم على الزر، يجب أن يظهر رابط "الإضافة إلى "محفظة Google" لبدء عملية إضافة البطاقة التي تم إصدارها إلى "محفظة Google" الخاصة بالمستخدم.
ننصحك باستخدام زر "الإضافة إلى محفظة Google" كلما أمكن ذلك، لأنّه عنصر مألوف في واجهة المستخدم يعرف سابقًا كيفية التفاعل معه.
تتوفر مواد العرض والإرشادات لاستخدام الزر في إرشادات العلامة التجارية لـ Google Wallet API.
رابط "الإضافة إلى محفظة Google"
باستخدام الرابط "الإضافة إلى محفظة Google"، يمكنك إصدار بطاقة لمستخدم لديه رابط تشعّبي عادي. يمكن استخدام هذا في أي مكان يمكنك فيه استخدام الارتباطات التشعبية، مثل البريد الإلكتروني والرسائل القصيرة ومواقع الويب وتطبيقات الأجهزة المحمولة.
يتم إنشاء روابط "الإضافة إلى محفظة Google" من خلال إلحاق JWT مُوقَّع بعنوان URL التالي: https://pay.google.com/gp/v/save/.
حساب جهة الإصدار
الوضع التجريبي
عندما تنشئ حساب جهة الإصدار، سيكون في "الوضع التجريبي" إلى أن تتم الموافقة على إذنك لنشر التطبيق. في الوضع التجريبي، يمكنك إنشاء بطاقات، ولكن لا يمكنك إصدارها إلا للمستخدمين الذين لديهم دور "المشرف" أو "المطوّر" في حساب جهة الإصدار الخاص بك، أو المستخدمين الذين تمت إضافتهم كحسابات تجريبية في وحدة تحكُّم "محفظة Google".
في "وضع العرض التوضيحي"، سيبدأ عنوان أي بطاقات تُصدرها تلقائيًا بالعبارة "[اختبار فقط]" للإشارة إلى أنّ البطاقة مخصّصة لأغراض الاختبار فقط.
حسابات تجريبية
عندما يكون حساب جهة الإصدار في "الوضع التجريبي"، إذا أردت إصدار البطاقات لأي مستخدم لا يملك دور "المشرف" أو "المطوّر" لحسابك، عليك إضافته كحسابات تجريبية في وحدة تحكّم "محفظة Google". سيتمكّن المستخدمون المسجّلون كحسابات تجريبية من إضافة البطاقات التي أصدرتَها إلى "محفظة Google". ويُعدّ هذا الإجراء مفيدًا في اختبار بطاقاتك مع شريحة أكبر من الجمهور أثناء استخدام "الوضع التجريبي".
الملف التجاري
لإنشاء حساب "جهة إصدار" لواجهة Google Wallet API، عليك إعداد ملف تجاري عند التسجيل في وحدة تحكُّم Google Pay & Wallet. يزوِّد الملف التجاري Google بمعلومات أساسية عن شركتك أو مؤسستك، وهو مطلوب للحصول على الموافقة لنشر المحتوى.
إذن النشر
قبل أن تتمكّن من إصدار البطاقات التي يمكن لأي مستخدم حفظها في "محفظة Google"، يجب أن تحصل على الموافقة لنشرك البطاقات. لكي تتم الموافقة على حصولك على إذن النشر، يجب أن تكون قد أنشأت فئة بطاقات واحدة على الأقل، وأن يكون لديك ملف تجاري كامل. على جهات الإصدار التي تريد إصدار البطاقات باستخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android لـ "محفظة Google" إرسال بصمة إصبع SHA-1 لتطبيقاتها.
لطلب الإذن بالنشر، انتقل إلى وحدة تحكّم "محفظة Google" وانقر على الزر "طلب الوصول إلى النشر". سيراجع فريق "محفظة Google" طلبك ويُعلمك بعد أن يتم منحك الإذن بنشر المحتوى.
المصادقة
رمز JSON المميّز للويب (JWT)
الرموز المميّزة للويب JSON هي معيار شائع الاستخدام في المجال لنقل المعلومات بأمان ككائن JSON. عند استخدام واجهة برمجة تطبيقات Google Wallet، يمكنك ترميز تفاصيل "عنصر البطاقات" الذي تريد استخدامه لإنشاء مثيل بطاقة بتنسيق JWT (يُنطق "jot") ثم إرسال JWT هذا في طلب إلى Google Wallet API.
يتم الحفاظ على أمان بيانات JWT من خلال توقيعها باستخدام سر مشترك قبل إرسالها إلى Google Wallet API. إذا كنت تستخدم Google Wallet REST API، يكون سر التوقيع هو مفتاح حسابك في خدمة Google Cloud. إذا كنت تستخدم حزمة تطوير البرامج (SDK) لنظام التشغيل Android لـ "محفظة Google"، يكون سر التوقيع هو بصمة الإصبع SHA-1 لتطبيق Android.
حساب الخدمة
حساب خدمة Google Cloud هو نوع خاص من الحسابات يتم استخدامه عادةً من خلال تطبيق أو احتساب أعباء العمل، بدلاً من الأشخاص. في حال استخدام Google Wallet API، سيتم استخدام حساب الخدمة لمصادقة الطلبات المرسَلة إلى Google Wallet REST API.
يتم إنشاء حسابات الخدمة في Google Cloud Console. لاستخدام حساب خدمة، عليك أيضًا تفعيل Google Wallet API في Cloud Console للسماح لحساب الخدمة بإرسال طلبات إلى Google Wallet REST API.
مفتاح حساب الخدمة
مفتاح حساب الخدمة هو بيانات الاعتماد التي ستستخدمها لمصادقة عمليات الاتصال بواجهة برمجة تطبيقات Google Wallet REST. يُعدّ مفتاح حساب الخدمة حساسًا للغاية ويجب الحفاظ على خصوصيته لأنّه يمنح إمكانية الوصول إلى العديد من ميزات جهة إصدار البطاقات في حسابك باستخدام واجهة برمجة تطبيقات REST API في Google Wallet، بما في ذلك إنشاء فئات البطاقات وعناصر البطاقات.
بصمة إصبع SHA-1
بصمة إصبع SHA-1 لشهادة توقيع تطبيق Android هي بيانات الاعتماد التي ستستخدمها لمصادقة المكالمات إلى Google Wallet API عند استخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android في محفظة Google. يتم إنشاء الملف المرجعي لشهادة SHA-1 لشهادتك باستخدام Gradle أو أداة Keytools. لاستخدام بصمة الإصبع لمصادقة طلباتك، يجب عليك تسجيلها في وحدة تحكم "محفظة Google".