لمحة عن هذا الدرس التطبيقي حول الترميز
1. مقدمة
نظرة عامة
تتيح لك Google Wallet API التفاعل مع المستخدمين من خلال أنواع مختلفة من البطاقات: بطاقات الولاء والعروض وبطاقات الهدايا وتذاكر حضور الفعاليات وتذاكر النقل العام وبطاقات الصعود إلى الطائرة والمزيد. يتضمّن كل نوع من أنواع البطاقات أو فئة منها حقولًا وميزات خاصة بحالة الاستخدام لتحسين تجربة المستخدم.
ومع ذلك، قد لا تتوافق هذه الحلول مع كل حالات الاستخدام. لإنشاء تجربة أكثر تخصيصًا، يمكنك استخدام نوع البطاقة العام. في ما يلي بعض أمثلة حالات الاستخدام لنوع البطاقة العام:
- بطاقات ركن السيارات
- بطاقات الاشتراك في المكتبة
- قسائم القيمة المخزّنة
- بطاقات العضوية في الصالات الرياضية
- الحجوزات
يمكنك استخدام البطاقات العامة لأي حالة استخدام يمكن تقديمها باستخدام:
- ما يصل إلى ثلاثة صفوف من المعلومات
- (اختياري) رسم الرمز الشريطي
- (اختياري) قسم "التفاصيل"
لمزيد من المعلومات عن Google Wallet API أو إضافة زر الإضافة إلى محفظة Google إلى صفحة ويب، يُرجى الاطّلاع على مستندات مطوّري "محفظة Google".
تمرير الفئات والكائنات
تعرض Google Wallet API طرقًا لإنشاء ما يلي:
النوع | الوصف |
فئة البطاقة | قالب لعنصر بطاقة فردي يحتوي على معلومات شائعة لجميع عناصر البطاقة التي تنتمي إلى هذه الفئة. |
تمرير العنصر | مثيل لفئة بطاقة مرور فريد لرقم تعريف مستخدم |
لمحة عن هذا الدرس التطبيقي حول الترميز
في هذا الدرس التعليمي حول رموز البرامج، عليك إكمال المهام التالية.
- إنشاء حساب جهة إصدار جديد في الوضع التجريبي
- إنشاء حساب خدمة لإصدار البطاقات
- إنشاء فئة بطاقة عامة جديدة
- إنشاء عنصر بطاقة جديدة
- إنشاء زر الإضافة إلى محفظة Google لحفظ بطاقة
- عرض الزر في صفحة الويب
- معالجة نتيجة حفظ البطاقة
المتطلبات الأساسية
- Git
- حساب Google يمكنه الوصول إلى وحدة تحكّم Google Cloud
- الإصدار 10 من Node.js أو إصدار أحدث
الأهداف
بعد إكمال هذا الدليل التعليمي حول الرموز البرمجية، ستتمكّن من إجراء ما يلي:
- إنشاء عناصر بطاقة باستخدام "محفظة Google"
- إنشاء زر الإضافة إلى "محفظة Google"
الدعم
إذا واجهت مشكلة في أي مرحلة من مراحل ورشة العمل، يمكنك الرجوع إلى مستودع GitHub google-pay/wallet-web-codelab للحصول على حلّ كامل.
2. ضبط إعدادات الجهاز
في هذه الخطوة، ستنشئ حسابًا لجهة إصدار في الوضع التجريبي. سيتيح لك ذلك إنشاء فئات وعناصر بطاقات يمكن إضافتها إلى محافظ المستخدمين. بعد ذلك، عليك إنشاء مشروع وحساب خدمة على Google Cloud. وسيتم استخدامها لإنشاء فئات وعناصر البطاقة بشكل آلي بالطريقة نفسها التي يستخدمها خادم الواجهة الخلفية. أخيرًا، عليك تفويض حساب خدمة Google Cloud لإدارة البطاقات في حساب جهة إصدار "محفظة Google".
الاشتراك للحصول على حساب مُصدِر في "محفظة Google"
يجب توفُّر حساب مُصدِر لإنشاء البطاقات وتوزيعها في "محفظة Google". يمكنك الاشتراك باستخدام Google Pay & Wallet Console. في البداية، ستتمكّن من إنشاء البطاقات في الوضع التجريبي. وهذا يعني أنّه لن يتمكّن سوى مستخدمي الاختبار المحدّدين من إضافة البطاقات التي تنشئها. يمكن إدارة المستخدمين التجريبيين في Google Pay & Wallet Console.
لمزيد من المعلومات عن الوضع التجريبي، يُرجى الاطّلاع على متطلبات المرور العامة.
- افتح Google Pay & Wallet Console.
- اتّباع التعليمات الظاهرة على الشاشة لإنشاء حساب جهة إصدار
- اختَر Google Wallet API.
- تأكيد فهم بنود الخدمة وسياسة الخصوصية
- انسخ قيمة رقم تعريف جهة الإصدار إلى محرِّر نصوص أو مكان آخر.
- ضمن علامة التبويب إدارة، انقر على إعداد حسابات اختبارية.
- أضِف أي عناوين بريد إلكتروني ستستخدمها في هذا الدليل التعليمي.
تفعيل Google Wallet API
- سجِّل الدخول إلى وحدة تحكُّم Google Cloud.
- إذا لم يكن لديك مشروع على Google Cloud، أنشئ مشروعًا الآن (اطّلِع على إنشاء المشاريع وإدارتها لمزيد من المعلومات).
- تفعيل Google Wallet API (المعروفة أيضًا باسم Google Pay for Passes API) لمشروعك
إنشاء حساب خدمة ومفتاح
يجب توفُّر حساب خدمة ومفتاح حساب خدمة لاستدعاء Google Wallet API. حساب الخدمة هو الهوية التي تستدعي Google Wallet API. يحتوي مفتاح حساب الخدمة على مفتاح خاص يعرّف تطبيقك على أنّه حساب الخدمة. هذا المفتاح حسّاس، لذا يُرجى الحفاظ على سريته.
إنشاء حساب خدمة
- في Google Cloud Console، افتح حسابات الخدمة.
- إدخال اسم وتعريف ووصف لحساب الخدمة
- انقر على إنشاء ومتابعة.
- انقر على تم.
إنشاء مفتاح حساب خدمة
- اختيار حساب الخدمة
- اختيار قائمة KEYS
- انقر على إضافة مفتاح، ثم على إنشاء مفتاح جديد.
- اختَر نوع مفتاح JSON.
- انقر على إنشاء.
سيُطلب منك حفظ ملف المفتاح في محطة العمل المحلية. احرص على تذكُّر مكانه.
ضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS
تستخدم حِزم تطوير البرامج (SDK) من Google متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS للمصادقة كحساب خدمة والوصول إلى واجهات برمجة تطبيقات مختلفة لمشروع على Google Cloud.
- اتّبِع التعليمات الواردة في مستندات مفاتيح حسابات الخدمة في Google Cloud لضبط متغيّر البيئة
GOOGLE_APPLICATION_CREDENTIALS. - تأكَّد من ضبط متغيّر البيئة في جلسة وحدة طرفية جديدة (نظام التشغيل MacOS/Linux) أو جلسة سطر أوامر (نظام التشغيل Windows) جديدة (قد تحتاج إلى بدء جلسة جديدة إذا كانت لديك جلسة مفتوحة).
echo $GOOGLE_APPLICATION_CREDENTIALS
تفويض حساب الخدمة
أخيرًا، عليك تفويض حساب الخدمة لإدارة البطاقات في "محفظة Google".
- افتح Google Pay & Wallet Console.
- اختَر المستخدمون.
- انقر على دعوة مستخدم.
- أدخِل عنوان البريد الإلكتروني لحساب الخدمة (مثل
test-svc@myproject.iam.gserviceaccount.com). - اختَر مطوّر أو مشرف من القائمة المنسدلة مستوى الوصول.
- انقر على دعوة.
3. تشغيل نموذج تطبيق Node.js
المدة 10:00
في هذه الخطوة، ستُشغّل نموذجًا لتطبيق Node.js يعمل كموقع إلكتروني للتسوّق وخادم خلفية.
استنساخ مستودع النماذج
يحتوي مستودع google-pay/wallet-web-codelab على نموذج مشروع يستند إلى Node.js وملفات نصوص برمجية مختلفة تحاكي خادمًا في الخلفية يُستخدَم لتوفير فئات البطاقات والعناصر. ستُعدّل هذه الصفحات لتضمين زر الإضافة إلى "محفظة Google" على شاشة تفاصيل المنتج.
- استنساخ المستودع إلى محطة العمل المحلية
git clone https://github.com/google-pay/wallet-web-codelab.git
تثبيت تبعيات المشروع
- افتح المستودع المُنشئ في المحطة الطرفية أو موجه سطر الأوامر.
- انتقِل إلى الدليل
web(هذا هو التطبيق الذي ستُجري تعديلات عليه في بقية هذا الدرس التطبيقي حول الترميز).cd web - تثبيت تبعيات Node.js
npm install . - ابدأ التطبيق.
node app.js - افتح التطبيق الذي يعمل على http://localhost:3000.
إذا أدخلت عنوان بريدك الإلكتروني واخترت إنشاء كلمة مرور، لن يحدث أي شيء. في الخطوات التالية، عليك ضبط التطبيق لإنشاء فئة بطاقة وعنصر جديدَين.
4. إنشاء فئة بطاقة عامة
في هذه الخطوة، ستنشئ الفئة الأساسية لبطاقتك. في أي وقت يتم فيه إنشاء بطاقة جديدة لمستخدم، سترث هذه البطاقة السمات المحدّدة في فئة البطاقة.
تستخدِم فئة البطاقة التي ستُنشئها خلال هذا الدرس التطبيقي حول الترميز مرونة البطاقات العامة لإنشاء عنصر يعمل كبطاقة تعريف وجهاز تتبُّع نقاط التحدي. عند إنشاء عنصر بطاقة من هذه الفئة، سيظهر على النحو الموضّح في الرسم التالي.
يمكن إنشاء فئات البطاقات مباشرةً في Google Pay & Wallet Console أو باستخدام Google Wallet API. في هذا الدرس التطبيقي حول الترميز، ستُنشئ فئة Generic pass باستخدام واجهة برمجة التطبيقات. ويتبع ذلك العملية التي سيستخدمها خادم خاص في الخلفية لإنشاء فئات البطاقات.
- افتح ملف
web/app.js. - استبدِل القيمة
issuerIdبمعرّف جهة الإصدار من Google Pay & Wallet Console.// TODO: Define Issuer ID
const issuerId = 'ISSUER_ID'; - ابحث عن دالة
createPassClass. - في الدالة، أنشئ مزوّد خدمة بروتوكول HTTP تمّت مصادقته واستخدِم Google Wallet API لإنشاء فئة بطاقة جديدة.
// TODO: Create a Generic pass class
let genericClass = {
'id': `${classId}`,
'classTemplateInfo': {
'cardTemplateOverride': {
'cardRowTemplateInfos': [
{
'twoItems': {
'startItem': {
'firstValue': {
'fields': [
{
'fieldPath': 'object.textModulesData["points"]'
}
]
}
},
'endItem': {
'firstValue': {
'fields': [
{
'fieldPath': 'object.textModulesData["contacts"]'
}
]
}
}
}
}
]
},
'detailsTemplateOverride': {
'detailsItemInfos': [
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.imageModulesData["event_banner"]'
}
]
}
}
},
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.textModulesData["game_overview"]'
}
]
}
}
},
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.linksModuleData.uris["official_site"]'
}
]
}
}
}
]
}
},
'imageModulesData': [
{
'mainImage': {
'sourceUri': {
'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-2021-card.png'
},
'contentDescription': {
'defaultValue': {
'language': 'en-US',
'value': 'Google I/O 2022 Banner'
}
}
},
'id': 'event_banner'
}
],
'textModulesData': [
{
'header': 'Gather points meeting new people at Google I/O',
'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.',
'id': 'game_overview'
}
],
'linksModuleData': {
'uris': [
{
'uri': 'https://io.google/2022/',
'description': 'Official I/O \'22 Site',
'id': 'official_site'
}
]
}
};
let response;
try {
// Check if the class exists already
response = await httpClient.request({
url: `${baseUrl}/genericClass/${classId}`,
method: 'GET'
});
console.log('Class already exists');
console.log(response);
} catch (err) {
if (err.response && err.response.status === 404) {
// Class does not exist
// Create it now
response = await httpClient.request({
url: `${baseUrl}/genericClass`,
method: 'POST',
data: genericClass
});
console.log('Class insert response');
console.log(response);
} else {
// Something else went wrong
console.log(err);
res.send('Something went wrong...check the console logs!');
}
}
عند تشغيل الرمز البرمجي، سيتم إنشاء فئة جديدة للبطاقة وعرض معرّف الفئة. يتألّف معرّف الفئة من معرّف جهة الإصدار متبوعًا بلاحقة يحدّدها المطوّر. في هذه الحالة، يتم ضبط اللاحقة على codelab_class (سيبدو رقم تعريف الصف مشابهًا 1234123412341234123.codelab_class). وستتضمّن سجلات الإخراج أيضًا الردّ من Google Wallet API.
5. أنشئ عنصر بطاقة مرور عام.
في هذه الخطوة، عليك ضبط تطبيق Node.js لإنشاء عنصر بطاقة عام باستخدام الفئة التي أنشأتها سابقًا. هناك تدفقان لإنشاء عناصر البطاقة للمستخدمين.
إنشاء عنصر البطاقة على خادم الخلفية
في هذا النهج، يتم إنشاء عنصر البطاقة على خادم في الخلفية وإعادته إلى تطبيق العميل كملف JWT موقَّع. وهذا الإجراء هو الأنسب للحالات التي يكون فيها استخدام المستخدمين مرتفعًا، لأنّه يضمن توفّر العنصر قبل أن يحاول المستخدم إضافته إلى محفظته.
إنشاء عنصر البطاقة عندما يضيفها المستخدم إلى محفظته
في هذا النهج، يتمّ تحديد عنصر البطاقة وتشفيره في رمز JWT موقَّع على خادم الخلفية. بعد ذلك، يتم عرض زر الإضافة إلى محفظة Google في تطبيق العميل الذي يشير إلى JWT. عندما ينقر المستخدم على الزر، يتم استخدام JWT لإنشاء عنصر البطاقة. وهذا الخيار هو الأنسب للحالات التي يكون فيها استخدام المستخدمين متغيّرًا أو غير معروف، لأنّه يمنع إنشاء عناصر البطاقة وعدم استخدامها. سيتم استخدام هذا الأسلوب في ورشة رموز البرامج.
- افتح ملف
web/app.js. - ابحث عن دالة
createPassObject. - في الدالة، حدِّد عنصر بطاقة جديد للمستخدم.
// TODO: Create a new Generic pass for the user
let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`;
let objectId = `${issuerId}.${objectSuffix}`;
let genericObject = {
'id': `${objectId}`,
'classId': classId,
'genericType': 'GENERIC_TYPE_UNSPECIFIED',
'hexBackgroundColor': '#4285f4',
'logo': {
'sourceUri': {
'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg'
}
},
'cardTitle': {
'defaultValue': {
'language': 'en',
'value': 'Google I/O \'22'
}
},
'subheader': {
'defaultValue': {
'language': 'en',
'value': 'Attendee'
}
},
'header': {
'defaultValue': {
'language': 'en',
'value': 'Alex McJacobs'
}
},
'barcode': {
'type': 'QR_CODE',
'value': `${objectId}`
},
'heroImage': {
'sourceUri': {
'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg'
}
},
'textModulesData': [
{
'header': 'POINTS',
'body': '1234',
'id': 'points'
},
{
'header': 'CONTACTS',
'body': '20',
'id': 'contacts'
}
]
};
// TODO: Create the signed JWT and link
res.send("Form submitted!");
في حال إعادة تحميل التطبيق وإدخال عنوان بريدك الإلكتروني وإرسال النموذج، لن يظهر لك أي ناتج. يتم تحديد عنصر البطاقة من خلال تطبيق الخلفية، ولكن لا يتم عرض أي إخراج. بعد ذلك، عليك تحويل البطاقة إلى رابط الإضافة إلى محفظة Google.
6. إنشاء زر الإضافة إلى "محفظة Google"
في الخطوة الأخيرة، عليك إنشاء رمز JWT موقَّع وإرجاع رابط يمكن استخدامه في الزر الإضافة إلى "محفظة Google". عندما ينقر المستخدم على الزر، سيُطلب منه حفظ البطاقة في محفظته.
- أنشئ مطالبات JWT وشفِّرها باستخدام المفتاح الخاص لحساب الخدمة، ثم أعِد زر الإضافة إلى محفظة Google مع الرابط المضمّن
// TODO: Create the signed JWT and link
const claims = {
iss: credentials.client_email,
aud: 'google',
origins: [],
typ: 'savetowallet',
payload: {
genericObjects: [
genericObject
]
}
};
const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' });
const saveUrl = `https://pay.google.com/gp/v/save/${token}`;
res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`); - إعادة تحميل التطبيق الذي يتم تشغيله في المتصفّح
- أدخِل عنوان بريدك الإلكتروني في النموذج وانقر على إنشاء بطاقة.
- انقر على الزر الإضافة إلى "محفظة Google" عندما يظهر.
7. تهانينا
تهانينا، لقد نجحت في دمج Google Wallet API على الويب.
مزيد من المعلومات
يمكنك الاطّلاع على عملية دمج كاملة في مستودع GitHub على الرابط google-pay/wallet-web-codelab.
إنشاء البطاقات وطلب الحصول على إذن بالإصدار العلني
عندما تصبح مستعدًا لإصدار البطاقات في قناة الإصدار العلني، انتقِل إلى Google Pay & Wallet Console لطلب الحصول على إذن بالإصدار العلني.
اطّلِع على متطلبات Web API الأساسية لمزيد من المعلومات.