تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إنشاء البطاقات على الويب باستخدام Google Wallet API

1. مقدمة

نظرة عامة

تسمح لك Google Wallet API بالتفاعل مع المستخدمين من خلال أنواع مختلفة من البطاقات، مثل بطاقات الولاء والعروض وبطاقات الهدايا وتذاكر حضور الفعاليات وتذاكر النقل العام وبطاقات صعود الطائرة وغيرها. يشمل كل نوع تذكرة أو فئة ناجحة حقول وميزات خاصة بحالات الاستخدام لتحسين تجربة المستخدم.

ومع ذلك، قد لا تناسب هذه الحالات جميع حالات الاستخدام. لإنشاء تجربة أكثر تخصيصًا، يمكنك استخدام نوع البطاقة العام. في ما يلي بعض الأمثلة على حالات الاستخدام لنوع البطاقة العامة:

بطاقات ركن السيارات
بطاقات عضوية المكتبات
قسائم القيمة المخزّنة
بطاقات عضوية في الصالات الرياضية
الحجوزات

يمكنك استخدام البطاقات العامة لأي حالة استخدام يمكن تقديمها مع:

ما يصل إلى ثلاثة صفوف من المعلومات
(اختياري) رسم الرمز الشريطي
(اختياري) قسم التفاصيل

نموذج من بطاقة "محفظة Google" الخاصة بحدث مؤتمر

لمزيد من المعلومات حول Google Wallet API أو إضافة زر الإضافة إلى "محفظة Google" إلى صفحة ويب، يُرجى الاطّلاع على مستندات مطوّري "محفظة Google".

تمرير الفئات والكائنات

تعرض Google Wallet API طرقًا لإنشاء ما يلي:

النوع	الوصف
اجتياز الصف	يشير إلى نموذج لعنصر بطاقة فردي. تتضمّن هذه الصفحة معلومات مشتركة بين جميع عناصر البطاقات التي تنتمي إلى هذه الفئة.
تمرير كائن	يشير ذلك المصطلح إلى نسخة من فئة بطاقة فريدة لرقم تعريف المستخدم.

لمحة عن هذا الدرس التطبيقي حول الترميز

في هذا الدرس التطبيقي حول الترميز، ستُكمل المهام التالية.

إنشاء حساب جهة إصدار جديد في الوضع التجريبي
إنشاء حساب خدمة لإصدار البطاقات
إنشاء فئة بطاقات عامة جديدة
إنشاء عنصر بطاقة جديد
لحفظ بطاقة، أنشِئ زر الإضافة إلى "محفظة Google".
عرض الزر في صفحة الويب
التعامل مع نتيجة حفظ البطاقة

المتطلبات الأساسية

Git
حساب Google لديه إذن بالوصول إلى وحدة تحكُّم Google Cloud
Node.js الإصدار 10 أو أحدث

الأهداف

بعد إكمال هذا الدرس التطبيقي، ستتمكّن من تنفيذ ما يلي:

إنشاء عناصر البطاقات باستخدام "محفظة Google"
إنشاء زر الإضافة إلى "محفظة Google"

الدعم

إذا واجهتك مشكلة في أي مرحلة من الدرس التطبيقي حول الترميز، يحتوي مستودع GitHub google-pay/wallet-web-codelab على حلّ كامل يمكن الرجوع إليه.

2. ضبط إعدادات الجهاز

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

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

لمزيد من المعلومات عن الوضع التجريبي، يُرجى الاطّلاع على المتطلبات الأساسية للبطاقات العامة.

افتح تطبيق Google Pay وحدة تحكُّم المحفظة
اتّبِع التعليمات الظاهرة على الشاشة لإنشاء حساب جهة إصدار.
اختَر Google Wallet API.
تأكيد فهمك لبنود الخدمة وسياسة الخصوصية
انسخ قيمة رقم تعريف جهة الإصدار إلى محرِّر نصوص أو موقع آخر.
ضمن علامة التبويب إدارة، اختَر إعداد الحسابات التجريبية.
أضِف أي عناوين بريد إلكتروني ستستخدمها في هذا الدرس التطبيقي حول الترميز.

تفعيل Google Wallet API

سجِّل الدخول إلى وحدة تحكُّم Google Cloud
إذا لم يكن لديك مشروع على Google Cloud، يمكنك إنشاء مشروع الآن (راجِع إنشاء المشاريع وإدارتها للحصول على مزيد من المعلومات).
تفعيل Google Wallet API (يُشار إليها أيضًا باسم Google Pay for Cards API) لمشروعك

إنشاء حساب خدمة ومفتاح

يجب توفّر حساب خدمة ومفتاح حساب خدمة لطلب بيانات Google Wallet API. حساب الخدمة هو الهوية التي تستدعي Google Wallet API. يحتوي مفتاح حساب الخدمة على مفتاح خاص يحدّد تطبيقك على أنّه حساب الخدمة. هذا المفتاح حساس، لذا يُرجى الحفاظ على سريته.

إنشاء حساب خدمة

في وحدة تحكُّم Google Cloud، افتح حسابات الخدمة.
أدخِل اسمًا ورقم تعريف ووصفًا لحساب الخدمة الخاص بك.
انقر على إنشاء ومتابعة.
انقر على تم.

إنشاء مفتاح حساب خدمة

اختيار حساب الخدمة
انقر على قائمة 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 وحدة تحكُّم المحفظة
اختيار المستخدمون
اختَر دعوة مستخدم.
أدخِل عنوان البريد الإلكتروني لحساب الخدمة (مثل 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. في هذا الدرس التطبيقي حول الترميز، ستُنشئ فئة البطاقة العامة باستخدام واجهة برمجة التطبيقات. يتبع هذا الإجراء العملية التي يستخدمها خادم خلفية خاص لإنشاء فئات البطاقات.

فتح ملف web/app.js
يُرجى استبدال قيمة issuerId برقم تعريف جهة الإصدار من Google Pay. وحدة التحكم في المحفظة
```
// 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 لطلب إذن بالإصدار العلني

راجِع المتطلبات الأساسية لواجهة برمجة تطبيقات الويب للاطّلاع على مزيد من المعلومات.